Moteur d’agent (Gemini Enterprise Agent Platform)

La fonctionnalité agent-engine permet à un agent ADK-Rust d’être piloté par la Gemini Enterprise Agent Platform en tant que ReasoningEngine dans un conteneur personnalisé. Un conteneur exécutant serve_agent_engine répond à reasoningEngines.query, reasoningEngines.streamQuery, au Playground de la console et à l’SDKs de la plateforme — le même contrat d’exécution que adk-python's AdkApp implémente.

Vue d’ensemble

La plateforme pilote un moteur déployé via deux points de terminaison du conteneur :

Les deux utilisent l’enveloppe de répartition {"class_method": "...", "input": {...}}.
L’enveloppe est snake_case — la plateforme effectue la répartition selon les noms des méthodes Python.
L’application clé en main expose également GET /health pour les vérifications de santé du conteneur.

Démarrage rapide

Activez la fonctionnalité (elle est incluse dans la méta-fonctionnalité gemini-agent-platform) :

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

Pour un agent qui utilise la plateforme complète — sessions gérées, Memory Bank, Example Store, bac à sable d’exécution de code, RAG, évaluation, ainsi que les registres Agent et Skill — une seule fonctionnalité fournit toutes les intégrations :

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

serve_agent_engine constitue l’ensemble main d’un moteur déployable. Il lie 0.0.0.0:$PORT (8080 de secours) et reste disponible jusqu’à son arrêt :

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
}

Vérifiez avec la charge utile du 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"}}'

Chaque ligne de réponse correspond à un événement ADK tel que JSON.

Opérations

Le moteur enregistre l’ensemble exact d’opérations que adk-python de AdkApp annonce. Les paires de noms synchrones/asynchrones correspondent au même gestionnaire — cette séparation est un artefact Python que le contrat filaire préserve.

Les méthodes de classe inconnues renvoient 400 avec un corps problem-JSON. Les méthodes de mémoire renvoient une erreur Unsupported (501) jusqu’à ce qu’un service de mémoire soit configuré.

Remarque : reasoningEngines:asyncQuery (tâches de requête durables) n’est pas enregistré : la capacité doit être déclarée lors de la création du moteur, ne peut pas être ajoutée après la création, et adk-python's AdkApp ne l’enregistre pas non plus.

Backends gérés

La valeur par défaut sans configuration conserve les sessions en mémoire — ce qui suffit pour répondre aux requêtes, mais les conversations ne survivent pas au redémarrage d’un conteneur. Les moteurs déployés configurent les backends gérés via AgentEngineOptions.

Sessions gérées (Vertex AI Sessions)

Avec la fonctionnalité vertex-session, VertexAiSessionConfig::from_env() lit les variables définies par la plateforme à l’intérieur des conteneurs déployés (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION et GOOGLE_CLOUD_AGENT_ENGINE_ID — l’ID numérique brut du moteur) :

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

En dehors d’un conteneur déployé, construisez explicitement la configuration avec VertexAiSessionConfig::new(project, location).with_reasoning_engine(id).

Artefacts (Google Cloud Storage)

Avec la fonctionnalité gcs-artifacts, GcsArtifactService stocke les artefacts dans la structure de blobs lue par la console Gemini Enterprise (parité octet par octet avec adk-python). Récupérez le bucket depuis une variable d’environnement ou une option :

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

Le service d’artefacts est intégré à la fois au runner (enregistrements et chargements destinés aux outils) et à l’état de dispatch.

Mémoire

AgentEngineOptions::with_memory_service accepte n’importe quel adk_memory::MemoryService et active les deux méthodes de classe de mémoire. Le backend Memory Bank de la plateforme sera fourni avec la fonctionnalité vertex-memory dans une version ultérieure.

Intégration de ServerBuilder

Un serveur ADK existant peut exposer la surface de dispatch aux côtés de ses routes REST, d’interface utilisateur et A2A :

use adk_server::{ServerBuilder, ServerConfig};

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

Les routes de répartition servent l’agent racine du chargeur avec les services de session et d’artefacts configurés. Elles ne transportent pas le middleware d’authentification du serveur : un moteur déployé est placé derrière la plateforme, qui authentifie les appelants avant qu’ils n’atteignent le conteneur. N’exposez pas directement ces points de terminaison à des réseaux non fiables.

Déploiement depuis CLI

Avec adk-cli installé avec la fonctionnalité gcp-deploy (cargo install adk-cli --features gcp-deploy), une commande crée le moteur à partir d’une image de conteneur envoyée :

# 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

Indicateurs facultatifs : --display-name (la valeur par défaut est le nom de l’image) et --kms-key pour CMEK. La commande déclare le contrat complet entre classe et méthode à partir de la table des opérations, attend la fin de l’opération de création et affiche le nom de la ressource du moteur. Le même client est disponible par programmation sous la forme adk_deploy::gcp::GcpDeployClient (fonctionnalité globale gcp-deploy).

Variables d’environnement

Lorsque GOOGLE_CLOUD_AGENT_ENGINE_ID est présent et que le service de session est le service par défaut en mémoire, le point d’entrée consigne un avertissement : les moteurs déployés doivent utiliser des sessions gérées.