Mecanismo de agentes (Gemini Enterprise Agent Platform)

O recurso agent-engine torna um agente ADK-Rust controlável pela Gemini Enterprise Agent Platform como um ReasoningEngine de contêiner personalizado. Um contêiner que executa serve_agent_engine responde a reasoningEngines.query, reasoningEngines.streamQuery, ao Playground do console e ao SDKs da plataforma — o mesmo contrato de runtime que adk-python's AdkApp implementa.

Visão geral

A plataforma controla um mecanismo implantado por meio de dois endpoints de contêiner:

Ambos recebem o envelope de despacho {"class_method": "...", "input": {...}}.
O envelope é snake_case — a plataforma despacha com base nos nomes dos métodos Python.
O aplicativo pronto para uso também disponibiliza GET /health para verificações de integridade do contêiner.

Início rápido

Habilite o recurso (ele está incluído no meta-recurso gemini-agent-platform):

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "agent-engine"] }

Para um agente que usa a plataforma completa — sessões gerenciadas, Memory Bank, Example Store, o sandbox de execução de código, RAG, avaliação e os Registros de Agentes e Habilidades — um recurso reúne todas as integrações:

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gemini-agent-platform"] }

serve_agent_engine é todo o main de um mecanismo implantável. Ele vincula 0.0.0.0:$PORT (8080 alternativo) e permanece em execução até ser interrompido:

use adk_rust::prelude::*;
use adk_server::agent_engine::{AgentEngineOptions, serve_agent_engine};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<()> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-3.7-flash")?);

    let agent = LlmAgentBuilder::new("weather_agent")
        .description("Answers weather questions")
        .instruction("You are a helpful weather assistant.")
        .model(model)
        .build()?;

    serve_agent_engine(Arc::new(agent), AgentEngineOptions::new()).await
}

Verifique usando o payload do codelab:

curl -s -X POST localhost:8080/api/stream_reasoning_engine \
  -H 'Content-Type: application/json' \
  -d '{"class_method": "async_stream_query", "input": {"user_id": "u", "message": "hi"}}'

Cada linha de resposta é um evento ADK como JSON.

Operações

O mecanismo registra o conjunto exato de operações que adk-python's AdkApp anuncia. Os pares de nomes síncronos/assíncronos são mapeados para o mesmo manipulador — a separação é um artefato do Python que o contrato de transmissão preserva.

Métodos de classe desconhecidos retornam 400 com um corpo problem-JSON. Os métodos de memória retornam um erro Unsupported (501) até que um serviço de memória seja configurado.

Observação: reasoningEngines:asyncQuery (jobs de consulta duráveis) não é registrado: o recurso deve ser declarado no momento da criação do mecanismo, não pode ser adicionado após a criação, e adk-python's AdkApp também não o registra.

Backends gerenciados

O padrão de configuração zero mantém as sessões na memória — suficiente para responder a consultas, mas as conversas não sobrevivem à reinicialização de um contêiner. Mecanismos implantados configuram backends gerenciados por meio de AgentEngineOptions.

Sessões gerenciadas (Vertex AI Sessions)

Com o recurso vertex-session, VertexAiSessionConfig::from_env() lê as variáveis que a plataforma define dentro dos contêineres implantados (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION e GOOGLE_CLOUD_AGENT_ENGINE_ID — o ID numérico simples do mecanismo):

use adk_server::agent_engine::AgentEngineOptions;
use adk_session::{VertexAiSessionConfig, VertexAiSessionService};
use std::sync::Arc;

fn managed_sessions() -> adk_core::Result<AgentEngineOptions> {
    let config = VertexAiSessionConfig::from_env()?;
    let sessions = Arc::new(VertexAiSessionService::new_with_adc(config)?);
    Ok(AgentEngineOptions::new().with_session_service(sessions))
}

Fora de um contêiner implantado, construa a configuração explicitamente com VertexAiSessionConfig::new(project, location).with_reasoning_engine(id).

Artefatos (Google Cloud Storage)

Com o recurso gcs-artifacts, GcsArtifactService armazena artefatos no layout de blobs que o console do Gemini Enterprise lê (paridade byte a byte com adk-python). Obtenha o bucket de uma variável de ambiente ou de uma flag:

use adk_artifact::GcsArtifactService;
use adk_server::agent_engine::AgentEngineOptions;
use std::sync::Arc;

fn gcs_artifacts() -> adk_core::Result<AgentEngineOptions> {
    let bucket = std::env::var("ADK_ARTIFACT_BUCKET").unwrap_or_else(|_| "my-bucket".to_string());
    let artifacts = Arc::new(GcsArtifactService::new_with_adc(bucket)?);
    Ok(AgentEngineOptions::new().with_artifact_service(artifacts))
}

O serviço de artefatos é conectado tanto ao executor (salvamentos e carregamentos voltados para ferramentas) quanto ao estado de despacho.

Memória

AgentEngineOptions::with_memory_service aceita qualquer adk_memory::MemoryService e habilita os dois métodos de classe de memória. O backend Memory Bank da plataforma chega com o recurso vertex-memory em uma versão posterior.

Integração com ServerBuilder

Um servidor ADK existente pode expor a superfície de despacho junto com suas rotas de REST, UI e A2A:

use adk_server::{ServerBuilder, ServerConfig};

fn build_app(config: ServerConfig) -> axum::Router {
    ServerBuilder::new(config).with_agent_engine(true).build()
}

As rotas de despacho atendem ao agente raiz do carregador com os serviços de sessão e artefatos configurados. Elas não incluem o middleware de autenticação do servidor: um mecanismo implantado é protegido pela plataforma, que autentica os chamadores antes que eles cheguem ao contêiner. Não exponha esses endpoints diretamente a redes não confiáveis.

Implantação a partir do CLI

Com o adk-cli instalado com o recurso gcp-deploy (cargo install adk-cli --features gcp-deploy), um comando cria o mecanismo a partir de uma imagem de contêiner enviada:

# 1. Build and push the image
gcloud builds submit --tag us-central1-docker.pkg.dev/PROJECT/agents/my-agent:latest

# 2. Deploy it as a ReasoningEngine
adk-rust deploy agent-engine \
  --image-uri us-central1-docker.pkg.dev/PROJECT/agents/my-agent:latest \
  --project PROJECT \
  --location us-central1 \
  --service-account agent-runner@PROJECT.iam.gserviceaccount.com

Sinalizadores opcionais: --display-name (usa o nome da imagem por padrão) e --kms-key para CMEK. O comando declara o contrato completo de classe e método da tabela de operações, aguarda a operação de criação e exibe o nome do recurso do mecanismo. O mesmo cliente está disponível programaticamente como adk_deploy::gcp::GcpDeployClient (recurso abrangente gcp-deploy).

Variáveis de ambiente

Quando GOOGLE_CLOUD_AGENT_ENGINE_ID está presente e o serviço de sessão é o padrão em memória, o ponto de entrada registra um aviso: os mecanismos implantados devem usar sessões gerenciadas.