Launcher

Launcher는 대화형 콘솔 모드와 HTTP 서버 모드 모두에 대한 내장 지원을 통해 ADK agent를 실행하는 간단한 한 줄 방식을 제공합니다. 이는 CLI 인수 파싱, session 관리 기능을 처리하며 agent 배포를 위한 일관된 인터페이스를 제공합니다.

개요

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

테스트 및 개발을 위해 대화형 콘솔에서 agent를 실행합니다.
웹 UI를 사용하여 agent를 HTTP 서버로 배포합니다.
application 이름과 artifact storage를 사용자 정의합니다.

기본 사용법

콘솔 모드 (기본값)

Launcher를 사용하는 가장 간단한 방법은 agent로 생성하고 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 CLI support (console by default)
    Launcher::new(Arc::new(agent)).run().await
}

agent를 실행합니다.

# Interactive console (default)
cargo run

# Or explicitly specify console mode
cargo run -- chat

서버 모드

agent를 웹 UI가 있는 HTTP 서버로 실행하려면:

# Start server on default port (8080)
cargo run -- serve

# Start server on custom port
cargo run -- serve --port 3000

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

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

구성 옵션

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

기본적으로 Launcher는 agent의 이름을 application 이름으로 사용합니다. 이를 사용자 지정할 수 있습니다.

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

사용자 지정 Artifact Service

자신만의 artifact service 구현을 제공합니다.

use adk_artifact::InMemoryArtifactService;

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

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

콘솔 모드 세부 정보

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

in-memory session service를 생성합니다.
사용자를 위한 session을 생성합니다.
대화형 REPL 루프를 시작합니다.
agent 응답을 실시간으로 스트리밍합니다.
multi-agent 시스템에서 agent transfer를 처리합니다.

콘솔 상호 작용

🤖 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!

Multi-Agent 콘솔

multi-agent 시스템을 사용할 때 콘솔은 어떤 agent가 응답하는지 보여줍니다.

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는 다음을 수행합니다:

관측 가능성을 위한 텔레메트리 초기화
인메모리 Session 서비스를 생성
REST API 엔드포인트를 가진 HTTP 서버를 시작
Agent와 상호 작용하기 위한 웹 UI를 제공

사용 가능한 엔드포인트

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

GET /health - 상태 확인 엔드포인트
POST /run_sse - 서버 센트 이벤트 스트리밍으로 Agent 실행
GET /sessions - Session 목록 조회
POST /sessions - 새 Session 생성
GET /sessions/:app_name/:user_id/:session_id - Session 세부 정보 조회
DELETE /sessions/:app_name/:user_id/:session_id - Session 삭제

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

웹 UI

서버에는 http://localhost:8080/ui/에서 접근 가능한 내장 웹 UI가 포함되어 있습니다. UI는 다음을 제공합니다:

대화형 채팅 인터페이스
Session 관리
실시간 스트리밍 응답
다중 Agent 시각화

CLI 인자

Launcher는 다음 CLI 명령을 지원합니다:

Command	Description	Example
(none)	대화형 콘솔 (기본값)	`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 (supports both console and server modes via CLI)
    Launcher::new(Arc::new(agent))
        .app_name("weather_app")
        .run()
        .await
}

콘솔 모드로 실행:

cargo run

서버 모드로 실행:

cargo run -- serve --port 8080

모범 사례

환경 변수: 항상 민감한 구성(API 키)을 환경 변수에서 로드하세요
오류 처리: Result 타입을 사용하여 적절한 오류 처리를 하세요
정상 종료: Launcher는 두 모드에서 Ctrl+C를 정상적으로 처리합니다
포트 선택: 다른 서비스와 충돌하지 않는 포트를 선택하세요 (기본값 8080)
Session 관리: 프로덕션 환경에서는 인메모리 Session 대신 DatabaseSessionService 사용을 고려하세요