Launcher

O Launcher oferece uma maneira simples e de uma linha para executar seus agentes ADK com suporte integrado para modo de console interativo e modo de servidor HTTP. Ele lida com a análise de argumentos de CLI, gerenciamento de Session e fornece uma interface consistente para implantar agentes.

Visão Geral

O Launcher foi projetado para tornar a implantação de agentes o mais simples possível. Com uma única linha de código, você pode:

Executar seu Agent em um console interativo para testes e desenvolvimento
Implantar seu Agent como um servidor HTTP com uma interface web
Personalizar o nome do aplicativo e o armazenamento de artefatos

Uso Básico

Modo Console (Padrão)

A maneira mais simples de usar o Launcher é criá-lo com seu Agent e chamar 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
}

Execute seu Agent:

# Interactive console (default)
cargo run

# Or explicitly specify console mode
cargo run -- chat

Modo Servidor

Para executar seu Agent como um servidor HTTP com uma interface web:

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

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

O servidor será iniciado e exibirá:

🚀 Servidor ADK iniciando em http://localhost:8080
📱 Abra http://localhost:8080 no seu navegador
Pressione Ctrl+C para parar

Opções de Configuração

Nome de Aplicativo Personalizado

Por padrão, o Launcher usa o nome do Agent como nome do aplicativo. Você pode personalizar isso:

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

Serviço de Artefatos Personalizado

Forneça sua própria implementação de serviço de artefatos:

use adk_artifact::InMemoryArtifactService;

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

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

Detalhes do Modo Console

No modo console, o Launcher:

Cria um SessionService em memória
Cria uma Session para o usuário
Inicia um loop REPL interativo
Transmite as respostas do Agent em tempo real
Lida com transferências de Agent em sistemas multi-Agent

Interação no Console

🤖 Agente pronto! Digite suas perguntas (ou 'exit' para sair).

Você: Qual é a capital da França?
Assistente: A capital da França é Paris.

Você: exit
👋 Adeus!

Console Multi-Agent

Ao usar sistemas multi-Agent, o console mostra qual Agent está respondendo:

Você: Preciso de ajuda com meu pedido

[Agente: customer_service]
Assistente: Ajudarei você com seu pedido. Qual é o número do seu pedido?

Você: ORDER-12345

🔄 [Transferência solicitada para: order_lookup]

[Agente: order_lookup]
Assistente: Encontrei seu pedido. Ele foi enviado ontem.

Detalhes do Modo Servidor

No modo servidor, o Launcher:

Inicializa a telemetry para observabilidade
Cria um serviço de sessão em memória
Inicia um servidor HTTP com endpoints de API REST
Serve uma UI web para interagir com seu agent

Endpoints Disponíveis

O servidor expõe os seguintes endpoints de API REST:

GET /health - Endpoint de verificação de saúde
POST /run_sse - Executa agent com streaming de Server-Sent Events
GET /sessions - Lista sessions
POST /sessions - Cria uma nova session
GET /sessions/:app_name/:user_id/:session_id - Obtém detalhes da session
DELETE /sessions/:app_name/:user_id/:session_id - Exclui uma session

Consulte a documentação da Server API para especificações detalhadas dos endpoints.

UI Web

O servidor inclui uma UI web integrada acessível em http://localhost:8080/ui/. A UI fornece:

Interface de chat interativa
Gerenciamento de sessions
Respostas de streaming em tempo real
Visualização multi-agent

Argumentos da CLI

O Launcher suporta os seguintes comandos da CLI:

Command	Description	Example
(none)	Console interativo (padrão)	`cargo run`
`chat`	Console interativo (explícito)	`cargo run -- chat`
`serve`	Modo de servidor HTTP	`cargo run -- serve`
`serve --port PORT`	Servidor HTTP em porta personalizada	`cargo run -- serve --port 3000`

Exemplo Completo

Aqui está um exemplo completo mostrando ambos os modos:

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
}

Executar no modo console:

cargo run

Executar no modo servidor:

cargo run -- serve --port 8080

Melhores Práticas

Variáveis de Ambiente: Sempre carregue configurações sensíveis (chaves de API) de variáveis de ambiente
Tratamento de Erros: Use tratamento de erros adequado com tipos Result
Desligamento Gracioso: O Launcher lida com Ctrl+C de forma graciosa em ambos os modos
Seleção de Porta: Escolha portas que não entrem em conflito com outros serviços (padrão 8080)
Gerenciamento de Sessions: Em produção, considere usar DatabaseSessionService em vez de sessions em memória

Relacionado

Server API - Documentação detalhada da API REST
Sessions - Gerenciamento de sessions
Artifacts - Armazenamento de artifacts
Observability - Telemetry e logging

Anterior: ← Telemetry | Próximo: Server →