Motor de agentes (Plataforma de agentes empresariales de Gemini)

La función agent-engine permite que un agente ADK-Rust sea ejecutado por la Plataforma de agentes empresariales de Gemini como un ReasoningEngine de contenedor personalizado. Un contenedor que ejecuta serve_agent_engine responde a reasoningEngines.query, reasoningEngines.streamQuery, el entorno de pruebas de la consola y SDKs de la plataforma: el mismo contrato de ejecución que implementa adk-python's AdkApp.

Descripción general

La plataforma ejecuta un motor implementado mediante dos endpoints del contenedor:

Ambos toman el envoltorio de despacho {"class_method": "...", "input": {...}}. El envoltorio es snake_case — la plataforma despacha según los nombres de los métodos de Python. La aplicación llave en mano también sirve GET /health para las comprobaciones de estado del contenedor.

Inicio rápido

Habilita la funcionalidad (está incluida en la metafuncionalidad gemini-agent-platform):

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

Para un agente que utiliza toda la plataforma — sesiones administradas, Banco de memoria, Almacén de ejemplos, el entorno aislado de ejecución de código, RAG, evaluación y los registros de agentes y habilidades — una funcionalidad reúne todas las integraciones:

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

serve_agent_engine es todo el main de un motor desplegable. Vincula 0.0.0.0:$PORT (alternativa 8080) y sirve hasta que se detiene:

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
}

Verifica con la carga útil del laboratorio práctico:

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 línea de respuesta es un evento ADK como JSON.

Operaciones

El motor registra el conjunto exacto de operaciones que anuncia adk-python mediante AdkApp. Los pares de nombres síncronos/asíncronos se asignan al mismo controlador; la separación es un artefacto de Python que el contrato de comunicación conserva.

Los métodos de clase desconocidos devuelven 400 con un cuerpo de problema-JSON. Los métodos de memoria devuelven un error Unsupported (501) hasta que se configura un servicio de memoria.

Nota: reasoningEngines:asyncQuery (trabajos de consulta duraderos) no está registrado: la capacidad debe declararse al crear el motor, no puede añadirse después de la creación, y adk-python's AdkApp tampoco lo registra.

Backends administrados

La configuración predeterminada sin configuración mantiene las sesiones en memoria, lo que basta para responder consultas, pero las conversaciones no sobreviven al reinicio de un contenedor. Los motores desplegados configuran backends administrados mediante AgentEngineOptions.

Sesiones administradas (Vertex AI Sessions)

Con la funcionalidad vertex-session, VertexAiSessionConfig::from_env() lee las variables que la plataforma establece dentro de los contenedores desplegados (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION y GOOGLE_CLOUD_AGENT_ENGINE_ID — el ID numérico sin formato del motor):

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))
}

Fuera de un contenedor desplegado, construye la configuración explícitamente con VertexAiSessionConfig::new(project, location).with_reasoning_engine(id).

Artefactos (Google Cloud Storage)

Con la funcionalidad gcs-artifacts, GcsArtifactService almacena los artefactos en el diseño de blobs que lee la consola de Gemini Enterprise (paridad byte por byte con adk-python). Obtén el bucket de una variable de entorno o de una opción:

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))
}

El servicio de artefactos está conectado tanto al ejecutor (guardados y cargas orientados a herramientas) como al estado de despacho.

Memoria

AgentEngineOptions::with_memory_service acepta cualquier adk_memory::MemoryService y habilita los dos métodos de clase de memoria. El backend Memory Bank de la plataforma llegará con la funcionalidad vertex-memory en una versión posterior.

Integración con ServerBuilder

Un servidor ADK existente puede exponer la superficie de despacho junto con sus rutas de REST, interfaz de usuario y A2A:

use adk_server::{ServerBuilder, ServerConfig};

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

Las rutas de despacho sirven al agente raíz del cargador con los servicios de sesión y artefactos configurados. No incorporan el middleware de autenticación del servidor: una implementación del motor está detrás de la plataforma, que autentica a los clientes antes de que lleguen al contenedor. No expongas estos endpoints directamente a redes que no sean de confianza.

Implementación desde la CLI

Con adk-cli instalada con la característica gcp-deploy (cargo install adk-cli --features gcp-deploy), un comando crea el motor a partir de una imagen de contenedor subida:

# 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

Banderas opcionales: --display-name (por defecto, el nombre de la imagen) y --kms-key para CMEK. El comando declara el contrato completo de clase y método de la tabla de operaciones, espera a que finalice la operación de creación e imprime el nombre del recurso del motor. El mismo cliente está disponible programáticamente como adk_deploy::gcp::GcpDeployClient (característica global gcp-deploy).

Variables de entorno

Cuando GOOGLE_CLOUD_AGENT_ENGINE_ID está presente y el servicio de sesiones es el predeterminado en memoria, el punto de entrada registra una advertencia: los motores implementados deben usar sesiones administradas.