Agent Engine (Gemini Enterprise Agent Platform)

agent-engine 기능을 사용하면 ADK-Rust 에이전트를 Gemini Enterprise Agent Platform에서 사용자 지정 컨테이너 ReasoningEngine로 구동할 수 있습니다. 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"] }

관리형 세션, 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"}}'

각 응답 줄은 JSON 형식의 하나의 ADK 이벤트입니다.

운영

엔진은 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, 그리고 숫자로만 구성된 엔진 ID인 GOOGLE_CLOUD_AGENT_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))
}

배포된 컨테이너 외부에서는 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 기능(cargo install adk-cli --features gcp-deploy)이 설치된 adk-cli를 사용하면 하나의 명령으로 푸시된 컨테이너 이미지에서 엔진을 생성할 수 있습니다.

# 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이 있고 세션 서비스가 인메모리 기본값인 경우, 진입점에서 경고를 기록합니다. 배포된 엔진에서는 관리형 세션을 사용해야 합니다.