런처

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

개요

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

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

기본 사용법

콘솔 모드 (기본값)

런처를 사용하는 가장 간단한 방법은 에이전트와 함께 런처를 생성하고 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-2.5-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::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

콘솔 모드 세부 정보

콘솔 모드에서 런처는 다음을 수행합니다:

인메모리 세션 서비스를 생성합니다.
사용자를 위한 세션을 생성합니다.
대화형 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.

서버 모드 세부 정보

서버 모드에서 런처는 다음을 수행합니다:

관찰 가능성을 위한 텔레메트리를 초기화합니다.
인메모리 세션 서비스를 생성합니다.
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는 다음을 제공합니다:

대화형 채팅 인터페이스
세션 관리
실시간 스트리밍 응답
다중 에이전트 시각화

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-2.5-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

배포 전 검증

Agent를 배포하기 전에, cargo adk build를 사용하여 실제로 배포하지 않고 프로젝트가 올바르게 컴파일되는지 확인하십시오:

# Verify compilation (no deployment)
cargo adk build

# Build with release optimizations
cargo adk build --release

이는 배포를 확정하기 전에 컴파일 오류, 누락된 종속성 및 구성 문제를 잡아냅니다. 특히 CI 파이프라인에서 cargo adk deploy 전의 게이트로 유용합니다.

cargo adk build에서 전체 명령어 문서를 참조하십시오.

모범 사례

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

Server API - 상세한 REST API 문서
Sessions - 세션 관리
Artifacts - 아티팩트 저장소
Observability - 텔레메트리 및 로깅

이전: ← Telemetry | 다음: Server →

런처

개요