Lançador

O Launcher oferece uma maneira simples e de uma linha para executar agentes ADK. No nível mínimo padrão, é um lançador de console leve do adk-runner. Habilite um recurso CLI opcional, como cli-openai, quando precisar do analisador de argumentos CLI completo e do modo de servidor HTTP.

Visão Geral

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

Execute seu agente em um console interativo para testes e desenvolvimento
Implante seu agente como um servidor HTTP com uma UI web quando um recurso cli-* ou o template cargo-adk api for usado
Personalize o nome do aplicativo e o armazenamento de artefatos

Uso Básico

Modo Console (Padrão)

A maneira mais simples de usar o Lançador é criá-lo com seu agente 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 the lightweight console launcher
    Launcher::new(Arc::new(agent)).run().await
}

Execute seu agente:

# Interactive console (default)
cargo run

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

Modo Servidor

Para executar seu agent como um servidor HTTP com uma interface web, use o api template ou habilite um cli-* recurso:

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

O servidor será iniciado e exibirá:

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

Opções de Configuração

Nome de Aplicação Personalizado

Por padrão, o Launcher usa o nome do agent como o nome da aplicação. Você pode personalizar isso:

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

Serviço de Artefato Personalizado

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

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 serviço de sessão em memória
Cria uma sessão 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

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

Console Multi-Agent

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

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.

Detalhes do Modo Servidor

No modo servidor, o Launcher:

Inicializa telemetria para observabilidade
Cria um serviço de sessão em memória
Inicia um servidor HTTP com endpoints de API REST
Serve uma interface de usuário web para interagir com seu agent

Saída de Emergência para Produção

Para aplicações em produção que precisam de rotas personalizadas, middleware, métricas ou propriedade do loop de serviço, use 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?;

Use build_app_with_a2a(...) se você quiser que as rotas A2A sejam habilitadas explicitamente.

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 o agent com streaming de Server-Sent Events
GET /sessions - Lista sessões
POST /sessions - Cria uma nova sessão
GET /sessions/:app_name/:user_id/:session_id - Obtém detalhes da sessão
DELETE /sessions/:app_name/:user_id/:session_id - Exclui uma sessão

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

Interface de Usuário Web

O servidor inclui uma interface de usuário web (UI) integrada acessível em http://localhost:8080/ui/. A UI oferece:

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

Argumentos da CLI

O launcher completo da CLI suporta os seguintes comandos quando um recurso cli-* está habilitado:

Comando	Descrição	Exemplo
(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. Enable a `cli-*` feature for full CLI/server mode.
    Launcher::new(Arc::new(agent))
        .app_name("weather_app")
        .run()
        .await
}

Executar no modo console:

cargo run

Executar no modo servidor a partir de um projeto de API gerado:

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

Verificação Pré-Implantação

Antes de implantar seu agent, use cargo adk build para verificar se o projeto compila corretamente sem realmente implantar:

# Verify compilation (no deployment)
cargo adk build

# Build with release optimizations
cargo adk build --release

Isso detecta erros de compilação, dependências ausentes e problemas de configuração antes de você se comprometer com uma implantação. É especialmente útil em pipelines de CI como um portão antes de cargo adk deploy.

Veja cargo adk build para a documentação completa do comando.

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 Elegante: O Launcher lida com Ctrl+C de forma elegante 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 Sessões: Em produção, considere usar PostgresSessionService ou SqliteSessionService em vez de sessões em memória
Verificação Pré-Implantação: Execute cargo adk build antes de implantar para identificar problemas precocemente

API do Servidor - Documentação detalhada da REST API
Sessões - Gerenciamento de sessões
Artefatos - Armazenamento de artefatos
Observabilidade - Telemetria e registro

Anterior: ← Telemetria | Próximo: Servidor →