Agent Engine（Gemini Enterprise Agent Platform）

agent-engine 功能使 ADK-Rust agent 能够作为自定义容器 ReasoningEngine，由 Gemini Enterprise Agent Platform 驱动。运行 serve_agent_engine 的容器可以响应 reasoningEngines.query、 reasoningEngines.streamQuery、控制台 Playground 以及平台 SDKs — 即 adk-python 的 AdkApp 所实现的相同运行时契约。

概览

该平台通过两个容器端点驱动已部署的引擎：

两者都接收调度信封 {"class_method": "...", "input": {...}}。
该信封为 snake_case——平台根据 Python 方法名进行调度。
开箱即用的应用还提供 GET /health，用于容器健康检查。

快速开始

启用此功能（它包含在 gemini-agent-platform 元功能中）：

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

对于使用完整平台的 agent——托管会话、Memory Bank、 Example Store、代码执行沙箱、RAG、评估，以及 Agent 和 Skill Registry——一个功能即可集成所有组件：

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

serve_agent_engine 是可部署引擎的完整 main。它绑定 0.0.0.0:$PORT（备用 8080），并持续提供服务，直到停止：

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
}

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

每一行响应都是一个 ADK 事件，格式为 JSON。

运维

引擎注册的确切操作集合，是 adk-python 的 AdkApp 所公布的集合。同步/异步名称对映射到同一个处理程序——这种拆分是 Python 的产物，而线协议会保留它。

未知的类方法会返回带有问题JSON主体的400。在配置内存服务之前，内存方法会返回Unsupported错误（501）。

注意：reasoningEngines:asyncQuery（持久化查询作业）未注册：该功能必须在引擎创建时声明，创建后无法添加，并且adk-python的AdkApp也不会注册它。

托管后端

零配置默认设置会将会话保存在内存中——这足以回答查询，但容器重启后对话不会保留。部署的引擎通过AgentEngineOptions配置托管后端。

托管会话（Vertex AI Sessions）

启用vertex-session功能后，VertexAiSessionConfig::from_env()会读取平台在已部署容器中设置的变量（GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION和GOOGLE_CLOUD_AGENT_ENGINE_ID——不带前缀的数字引擎 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))
}

在已部署容器之外，使用VertexAiSessionConfig::new(project, location).with_reasoning_engine(id)显式构造配置。

工件（Google Cloud Storage）

启用gcs-artifacts功能后，GcsArtifactService会按照 Gemini Enterprise 控制台读取的 Blob 布局存储工件（与adk-python逐字节一致）。从环境变量或标志中获取存储桶：

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

工件服务同时接入运行器（面向工具的保存和加载）以及分发状态。

内存

AgentEngineOptions::with_memory_service接受任意adk_memory::MemoryService，并启用两个内存类方法。平台的 Memory Bank 后端将在后续版本中随vertex-memory功能提供。

ServerBuilder集成

现有的ADK服务器可以将分发接口与其REST、UI 和A2A路由一同公开：

use adk_server::{ServerBuilder, ServerConfig};

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

调度路由为加载器的根代理提供配置的会话和工件服务。它们不承载服务器的身份验证中间件：已部署的引擎由平台置于前端，平台会在调用方到达容器之前对其进行身份验证。请勿将这些端点直接暴露给不受信任的网络。

从 CLI 部署

安装了带有 gcp-deploy 特性的 adk-cli （cargo install adk-cli --features gcp-deploy）后，只需一条命令即可从已推送的容器镜像创建引擎：

# 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

可选标志：--display-name（默认为镜像名称）以及 用于 CMEK 的 --kms-key。该命令根据操作表声明完整的类方法契约，等待创建操作完成，并输出引擎资源名称。同一客户端也可通过 adk_deploy::gcp::GcpDeployClient（总括特性 gcp-deploy）以编程方式使用。

环境变量

当存在 GOOGLE_CLOUD_AGENT_ENGINE_ID 且会话服务为内存中的默认服务时，入口点会记录一条警告：已部署的引擎应使用托管会话。