런처

Launcher는 ADK 에이전트를 한 줄로 실행할 수 있는 간단한 방법을 제공합니다. 기본 최소 티어에서는 adk-runner의 경량 콘솔 런처입니다. 전체 CLI 인수 파서와 HTTP 서버 모드가 필요할 때는 cli-openai와 같은 옵트인 CLI 기능을 활성화하세요.

개요

Launcher는 에이전트 배포를 최대한 간단하게 만들도록 설계되었습니다. 코드 한 줄로 다음을 수행할 수 있습니다.

테스트 및 개발을 위해 대화형 콘솔에서 에이전트 실행
cli-* 기능 또는 cargo-adk api 템플릿을 사용할 때 웹 UI가 포함된 HTTP 서버로 에이전트 배포
애플리케이션 이름 및 아티팩트 저장소 사용자 지정

기본 사용법

콘솔 모드(기본값)

Launcher를 사용하는 가장 간단한 방법은 에이전트로 생성한 후 run()을 호출하는 것입니다.

use adk_rust::prelude::*;
use adk_rust::Launcher;
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("my_agent")
        .description("A helpful assistant")
        .instruction("You are a helpful assistant.")
        .model(model)
        .build()?;
    
    // Run with the lightweight console launcher
    Launcher::new(Arc::new(agent)).run().await
}

에이전트를 실행합니다.

# Interactive console (default)
cargo run

# Full CLI mode is available when your app enables a `cli-*` feature

서버 모드

웹 UI가 포함된 HTTP 서버로 에이전트를 실행하려면 api 템플릿을 사용하거나 cli-* 기능을 활성화하세요.

cargo adk new my-api --template api
cd my-api
cargo run

서버가 시작되며 다음을 표시합니다.

🚀 ADK Server starting on http://localhost:8080
📱 Open http://localhost:8080 in your browser
Press Ctrl+C to stop

구성 옵션

사용자 지정 애플리케이션 이름

기본적으로 Launcher는 에이전트의 이름을 애플리케이션 이름으로 사용합니다. 다음과 같이 사용자 지정할 수 있습니다.

Launcher::new(Arc::new(agent))
    .app_name("my_custom_app")
    .run()
    .await

사용자 지정 아티팩트 서비스

직접 구현한 아티팩트 서비스를 제공합니다.

use adk_artifact::InMemoryArtifactService;

let artifact_service = Arc::new(InMemoryArtifactService::new());

Launcher::new(Arc::new(agent))
    .with_artifact_service(artifact_service)
    .run()
    .await

콘솔 모드 세부 정보

콘솔 모드에서 Launcher는 다음을 수행합니다.

메모리 내 세션 서비스 생성
사용자를 위한 세션 생성
대화형 REPL 루프 시작
에이전트 응답을 실시간으로 스트리밍
다중 에이전트 시스템에서 에이전트 전환 처리

콘솔 상호 작용

🤖 Agent ready! Type your questions (or 'exit' to quit).

You: What is the capital of France?
Assistant: The capital of France is Paris.

You: exit
👋 Goodbye!

다중 에이전트 콘솔

다중 에이전트 시스템을 사용할 때 콘솔에는 응답 중인 에이전트가 표시됩니다.

You: I need help with my order

[Agent: customer_service]
Assistant: I'll help you with your order. What's your order number?

You: ORDER-12345

🔄 [Transfer requested to: order_lookup]

[Agent: order_lookup]
Assistant: I found your order. It was shipped yesterday.

서버 모드 세부 정보

서버 모드에서 Launcher는 다음을 수행합니다.

관찰 가능성을 위한 원격 측정을 초기화합니다
메모리 내 세션 서비스를 생성합니다
REST API 엔드포인트를 사용하는 HTTP 서버를 시작합니다
에이전트와 상호 작용할 수 있는 웹 UI를 제공합니다

프로덕션 전환 지점

사용자 지정 경로, 미들웨어, 메트릭 또는 서빙 루프의 제어가 필요한 프로덕션 애플리케이션에서는 build_app()을 사용합니다:

let app = Launcher::new(Arc::new(agent))
    .with_a2a_base_url("https://agent.example.com")
    .build_app()?;

let app = app.merge(my_admin_routes());
let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
axum::serve(listener, app).await?;

A2A 경로를 명시적으로 활성화하려면 build_app_with_a2a(...)를 사용합니다.

사용 가능한 엔드포인트

서버는 다음 REST API 엔드포인트를 제공합니다:

GET /health - 상태 확인 엔드포인트
POST /run_sse - Server-Sent Events 스트리밍으로 에이전트 실행
GET /sessions - 세션 나열
POST /sessions - 새 세션 생성
GET /sessions/:app_name/:user_id/:session_id - 세션 세부 정보 가져오기
DELETE /sessions/:app_name/:user_id/:session_id - 세션 삭제

자세한 엔드포인트 사양은 서버 API 문서를 참조하세요.

웹 UI

서버에는 http://localhost:8080/ui/에서 액세스할 수 있는 기본 제공 웹 UI가 포함되어 있습니다. UI는 다음 기능을 제공합니다:

대화형 채팅 인터페이스
세션, 상태, 아티팩트 및 이벤트 타임라인 검사
실시간 스트리밍 응답 및 도구 활동
정확한 팀 위임 및 핸드오프 토폴로지
에이전트 및 UI 프로토콜 기능 검색

CLI 인수

전체 CLI 실행기는 cli-* 기능이 활성화된 경우 다음 명령을 지원합니다:

명령어	설명	예시
(없음)	대화형 콘솔 (기본값)	`cargo run`
`chat`	대화형 콘솔 (명시적)	`cargo run -- chat`
`serve`	HTTP 서버 모드	`cargo run -- serve`
`serve --port PORT`	HTTP 사용자 지정 포트의 서버	`cargo run -- serve --port 3000`

전체 예제

두 모드를 모두 보여 주는 전체 예제입니다:

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<()> {
    // Load API key
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");
    
    // Create model
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-3.7-flash")?);
    
    // Create agent with tools
    let weather_tool = FunctionTool::new(
        "get_weather",
        "Get the current weather for a location",
        |params, _ctx| async move {
            let location = params["location"].as_str().unwrap_or("unknown");
            Ok(json!({
                "location": location,
                "temperature": 72,
                "condition": "sunny"
            }))
        },
    );
    
    let agent = LlmAgentBuilder::new("weather_agent")
        .description("An agent that provides weather information")
        .instruction("You are a weather assistant. Use the get_weather tool to provide weather information.")
        .model(model)
        .tool(Arc::new(weather_tool))
        .build()?;
    
    // Run with Launcher. Enable a `cli-*` feature for full CLI/server mode.
    Launcher::new(Arc::new(agent))
        .app_name("weather_app")
        .run()
        .await
}

콘솔 모드로 실행합니다:

cargo run

생성된 API 프로젝트에서 서버 모드로 실행합니다:

cargo adk new weather-api --template api
cd weather-api
cargo run

배포 전 검증

에이전트를 배포하기 전에 cargo adk build을 사용하여 실제로 배포하지 않고도 프로젝트가 올바르게 컴파일되는지 확인하세요:

# Verify compilation (no deployment)
cargo adk build

# Build with release optimizations
cargo adk build --release

이를 통해 배포를 확정하기 전에 컴파일 오류, 누락된 종속성 및 구성 문제를 발견할 수 있습니다. 특히 cargo adk deploy 전에 게이트로 사용하는 CI 파이프라인에서 유용합니다.

전체 명령어 문서는 cargo adk build를 참조하세요.

모범 사례

환경 변수: 민감한 구성(API 키)은 항상 환경 변수에서 로드하세요.
오류 처리: Result 타입을 사용하여 적절하게 오류를 처리하세요.
정상 종료: Launcher는 두 모드 모두에서 Ctrl+C를 정상적으로 처리합니다.
포트 선택: 다른 서비스와 충돌하지 않는 포트를 선택하세요(기본값 8080).
세션 관리: 프로덕션 환경에서는 인메모리 세션 대신 PostgresSessionService 또는 SqliteSessionService 사용을 고려하세요.
배포 전 확인: 문제를 조기에 발견할 수 있도록 배포 전에 cargo adk build을 실행하세요.

서버 API - 자세한 REST API 문서
세션 - 세션 관리
아티팩트 - 아티팩트 저장소
관측 가능성 - 텔레메트리 및 로깅

이전: ← 텔레메트리 | 다음: 서버 →

런처

개요