Inicializador

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

Visão geral

O Inicializador 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 agente em um console interativo para testes e desenvolvimento
• Implantar seu agente como um servidor HTTP com uma interface web quando um recurso cli-* ou o modelo api do cargo-adk for usado
• Personalizar o nome da aplicação e o armazenamento de artefatos

Uso básico

Modo de console (padrão)

A maneira mais simples de usar o Inicializador é 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-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
}

Execute seu agente:

# Interactive console (default)
cargo run

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

Modo de servidor

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

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 personalizado da aplicação

Por padrão, o Inicializador usa o nome do agente como nome da aplicação. Você pode personalizá-lo:

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 de console

No modo de console, o Inicializador:

1. Cria um serviço de sessão em memória
2. Cria uma sessão para o usuário
3. Inicia um loop REPL interativo
4. Transmite as respostas do agente em tempo real
5. Gerencia transferências de agentes em sistemas multiagente

Interação com o 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 multiagente

Ao usar sistemas multiagente, o console mostra qual agente 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 de servidor

No modo de servidor, o Inicializador:

1. Inicializa a telemetria para observabilidade
2. Cria um serviço de sessão em memória
3. Inicia um servidor HTTP com endpoints REST API
4. Disponibiliza uma UI web para interagir com seu agente

Alternativa para produção

Para aplicações de produção que precisam de rotas personalizadas, middleware, métricas ou controle do loop de atendimento, 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 quiser que as rotas A2A sejam habilitadas explicitamente.

Endpoints disponíveis

O servidor expõe os seguintes endpoints REST API:

• GET /health - Endpoint de verificação de integridade
• POST /run_sse - Executa o agente com transmissão por Eventos Enviados pelo Servidor
• GET /sessions - Lista as sessões
• POST /sessions - Cria uma nova sessão
• GET /sessions/:app_name/:user_id/:session_id - Obtém os detalhes da sessão
• DELETE /sessions/:app_name/:user_id/:session_id - Exclui uma sessão

Consulte a documentação de API do servidor para obter especificações detalhadas dos endpoints.

UI web

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

• Interface de chat interativa
• Inspeção de sessão, estado, artefatos e linha do tempo de eventos
• Respostas transmitidas em tempo real e atividade das ferramentas
• Topologia exata de delegação e transferência da equipe
• Descoberta de recursos do agente e do protocolo da UI

Argumentos de CLI

O iniciador CLI completo é compatível com os seguintes comandos quando um recurso cli-* está habilitado:

Exemplo completo

Veja 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-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
}

Execute no modo de console:

cargo run

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

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

Verificação pré-implantação

Antes de implantar seu agente, use cargo adk build para verificar se o projeto compila corretamente sem realmente fazer a implantação:

# 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 que você confirme uma implantação. É especialmente útil em pipelines de CI como uma etapa de validação antes de cargo adk deploy.

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

Práticas recomendadas

1. Variáveis de ambiente: Sempre carregue configurações sensíveis (chaves API) a partir de variáveis de ambiente
2. Tratamento de erros: Use um tratamento de erros adequado com tipos Result
3. Desligamento adequado: O Launcher trata o Ctrl+C adequadamente em ambos os modos
4. Seleção de porta: Escolha portas que não entrem em conflito com outros serviços (o padrão é 8080)
5. Gerenciamento de sessões: Em produção, considere usar PostgresSessionService ou SqliteSessionService em vez de sessões em memória
6. Verificação pré-implantação: Execute cargo adk build antes da implantação para detectar problemas antecipadamente

Relacionado

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

---

Anterior: ← Telemetria | Próximo: Servidor →