Agent Engine (Gemini Enterprise Agent Platform)

Die Funktion agent-engine ermöglicht es, einen ADK-Rust-Agenten als benutzerdefinierten Container-ReasoningEngine von der Gemini Enterprise Agent Platform aus zu steuern. Ein Container, auf dem serve_agent_engine ausgeführt wird, beantwortet reasoningEngines.query, reasoningEngines.streamQuery, das Playground der Konsole und die SDKs der Plattform — derselbe Laufzeitvertrag, den adk-python's AdkApp implementiert.

Überblick

Die Plattform steuert eine bereitgestellte Engine über zwei Container-Endpunkte:

Beide verwenden das Dispatch-Umschlagformat {"class_method": "...", "input": {...}}.
Der Umschlag ist snake_case — die Plattform führt den Dispatch anhand von Python-Methodennamen aus.
Die schlüsselfertige Anwendung stellt außerdem GET /health für Container-Zustandsprüfungen bereit.

Schnellstart

Aktivieren Sie das Feature (es ist im gemini-agent-platform- Meta-Feature enthalten):

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

Für einen Agenten, der die vollständige Plattform verwendet — verwaltete Sitzungen, Memory Bank, Example Store, die Codeausführungs-Sandbox, RAG, Evaluierung sowie die Agent- und Skill-Registries — bringt ein Feature jede Integration zusammen:

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

serve_agent_engine ist die vollständige main einer bereitstellbaren Engine. Sie bindet 0.0.0.0:$PORT (Fallback 8080) und stellt Dienste bereit, bis sie angehalten wird:

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
}

Überprüfen Sie dies mit der Payload des Codelabs:

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"}}'

Jede Antwortzeile ist ein einzelnes ADK-Ereignis als JSON.

Betrieb

Die Engine registriert genau den Operationssatz, den adk-python mit AdkApp bewirbt. Synchron-/Asynchron-Namenspaare werden demselben Handler zugeordnet — die Aufteilung ist ein Python-Artefakt, das der Wire-Vertrag beibehält.

Methoden für unbekannte Klassen geben 400 mit einem Problem-JSON-Body zurück. Die Memory-Methoden geben bis zur Konfiguration eines Memory-Dienstes einen Unsupported-Fehler (501) zurück.

Hinweis: reasoningEngines:asyncQuery (dauerhafte Abfrageaufträge) ist nicht registriert: Die Fähigkeit muss beim Erstellen der Engine deklariert werden, kann nach der Erstellung nicht hinzugefügt werden, und auch adk-pythons AdkApp registriert sie nicht.

Verwaltete Backends

Die Standardeinstellung ohne Konfiguration hält Sitzungen im Speicher — ausreichend, um Abfragen zu beantworten, aber Konversationen überstehen keinen Neustart des Containers. Bereitgestellte Engines konfigurieren verwaltete Backends über AgentEngineOptions.

Verwaltete Sitzungen (Vertex AI Sessions)

Mit dem Feature vertex-session liest VertexAiSessionConfig::from_env() die Variablen, die die Plattform in bereitgestellten Containern setzt (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION und GOOGLE_CLOUD_AGENT_ENGINE_ID — die reine numerische Engine-ID):

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

Außerhalb eines bereitgestellten Containers erstellen Sie die Konfiguration explizit mit VertexAiSessionConfig::new(project, location).with_reasoning_engine(id).

Artefakte (Google Cloud Storage)

Mit dem Feature gcs-artifacts speichert GcsArtifactService Artefakte im Blob-Layout, das die Gemini Enterprise-Konsole liest (Byte-für-Byte-Parität mit adk-python). Übernehmen Sie den Bucket aus einer Umgebungsvariablen oder einem 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))
}

Der Artefaktdienst ist sowohl in den Runner (speicher- und ladebezogene Vorgänge für Tools) als auch in den Dispatch-Status eingebunden.

Memory

AgentEngineOptions::with_memory_service akzeptiert jedes adk_memory::MemoryService und aktiviert die beiden Memory-Klassenmethoden. Das Memory-Bank-Backend der Plattform wird in einer späteren Version mit dem Feature vertex-memory verfügbar.

ServerBuilder-Integration

Ein vorhandener ADK-Server kann die Dispatch-Oberfläche neben seinen REST-, UI- und A2A-Routen bereitstellen:

use adk_server::{ServerBuilder, ServerConfig};

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

Die Dispatch-Routen bedienen den Root-Agenten des Loaders mit den konfigurierten Sitzungs- und Artefaktdiensten. Sie verwenden nicht die Authentifizierungs- Middleware des Servers: Eine bereitgestellte Engine wird von der Plattform vorgeschaltet, die Aufrufer authentifiziert, bevor sie den Container erreichen. Setzen Sie diese Endpunkte nicht direkt nicht vertrauenswürdigen Netzwerken aus.

Bereitstellung aus CLI

Mit installiertem adk-cli und dem Feature gcp-deploy (cargo install adk-cli --features gcp-deploy) erstellt ein Befehl die Engine aus einem gepushten Container-Image:

# 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

Optionale Flags: --display-name (standardmäßig der Image-Name) und --kms-key für CMEK. Der Befehl deklariert den vollständigen Klassen-Methoden-Vertrag aus der Tabelle der Operationen, wartet auf den Erstellvorgang und gibt den Ressourcennamen der Engine aus. Derselbe Client ist programmgesteuert als adk_deploy::gcp::GcpDeployClient verfügbar (Umbrella-Feature gcp-deploy).

Umgebungsvariablen

Wenn GOOGLE_CLOUD_AGENT_ENGINE_ID vorhanden ist und der Sitzungsdienst standardmäßig im Speicher ausgeführt wird, protokolliert der Einstiegspunkt eine Warnung: Bereitgestellte Engines sollten verwaltete Sitzungen verwenden.