Lanzador

El Launcher proporciona una forma sencilla, de una sola línea, de ejecutar agentes ADK. En el nivel mínimo predeterminado, es un lanzador ligero de consola de adk-runner. Habilita una funcionalidad opcional CLI como cli-openai cuando necesites el analizador de argumentos completo de CLI y el modo de servidor de HTTP.

Descripción general

El Launcher está diseñado para hacer que la implementación de agentes sea lo más sencilla posible. Con una sola línea de código, puedes:

• Ejecutar tu agente en una consola interactiva para pruebas y desarrollo
• Implementar tu agente como un servidor HTTP con una interfaz web cuando se utiliza una funcionalidad cli-* o la plantilla api de cargo-adk
• Personalizar el nombre de la aplicación y el almacenamiento de artefactos

Uso básico

Modo de consola (predeterminado)

La forma más sencilla de utilizar el Launcher es crearlo con tu agente y llamar a 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
}

Ejecuta tu agente:

# Interactive console (default)
cargo run

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

Modo de servidor

Para ejecutar tu agente como un servidor HTTP con una interfaz web, utiliza la plantilla api o habilita una funcionalidad cli-*:

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

El servidor se iniciará y mostrará:

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

Opciones de configuración

Nombre de aplicación personalizado

De forma predeterminada, el Launcher utiliza el nombre del agente como nombre de la aplicación. Puedes personalizarlo:

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

Servicio de artefactos personalizado

Proporciona tu propia implementación del servicio de artefactos:

use adk_artifact::InMemoryArtifactService;

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

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

Detalles del modo de consola

En el modo de consola, el Launcher:

1. Crea un servicio de sesiones en memoria
2. Crea una sesión para el usuario
3. Inicia un bucle REPL interactivo
4. Transmite las respuestas del agente en tiempo real
5. Gestiona las transferencias de agentes en sistemas multiagente

Interacción con la consola

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

Consola multiagente

Al utilizar sistemas multiagente, la consola muestra qué agente está respondiendo:

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.

Detalles del modo de servidor

En el modo de servidor, el Launcher:

1. Inicializa la telemetría para la observabilidad
2. Crea un servicio de sesiones en memoria
3. Inicia un servidor HTTP con endpoints REST API
4. Proporciona una interfaz web para interactuar con tu agente

Alternativa para producción

Para aplicaciones de producción que necesiten rutas personalizadas, middleware, métricas o control del bucle de servicio, usa 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?;

Usa build_app_with_a2a(...) si quieres habilitar explícitamente las rutas A2A.

Endpoints disponibles

El servidor expone los siguientes endpoints REST API:

• GET /health - Endpoint de comprobación de estado
• POST /run_sse - Ejecuta el agente con transmisión de Server-Sent Events
• GET /sessions - Enumera las sesiones
• POST /sessions - Crea una sesión nueva
• GET /sessions/:app_name/:user_id/:session_id - Obtiene los detalles de una sesión
• DELETE /sessions/:app_name/:user_id/:session_id - Elimina una sesión

Consulta la documentación de Servidor API para conocer las especificaciones detalladas de los endpoints.

Interfaz web

El servidor incluye una interfaz web integrada accesible en http://localhost:8080/ui/. La interfaz proporciona:

• Interfaz de chat interactiva
• Inspección de sesiones, estado, artefactos y cronología de eventos
• Respuestas transmitidas en tiempo real y actividad de las herramientas
• Topología exacta de delegación y transferencia del equipo
• Descubrimiento de las capacidades del agente y del protocolo de la interfaz

Argumentos de CLI

El lanzador CLI completo admite los siguientes comandos cuando la funcionalidad cli-* está habilitada:

Ejemplo completo

Este es un ejemplo completo que muestra ambos 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
}

Ejecutar en modo consola:

cargo run

Ejecutar en modo servidor desde un proyecto API generado:

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

Verificación previa al despliegue

Antes de desplegar tu agente, usa cargo adk build para verificar que el proyecto se compila correctamente sin realizar el despliegue:

# Verify compilation (no deployment)
cargo adk build

# Build with release optimizations
cargo adk build --release

Esto detecta errores de compilación, dependencias faltantes y problemas de configuración antes de comprometerte con un despliegue. Es especialmente útil en canalizaciones de CI como paso de control antes de cargo adk deploy.

Consulta cargo adk build para ver la documentación completa del comando.

Prácticas recomendadas

1. Variables de entorno: Carga siempre la configuración sensible (claves API) desde variables de entorno
2. Gestión de errores: Usa una gestión adecuada de errores con tipos Result
3. Cierre ordenado: Launcher gestiona Ctrl+C correctamente en ambos modos
4. Selección de puertos: Elige puertos que no entren en conflicto con otros servicios (8080 de forma predeterminada)
5. Gestión de sesiones: En producción, considera usar PostgresSessionService o SqliteSessionService en lugar de sesiones en memoria
6. Comprobación previa al despliegue: Ejecuta cargo adk build antes de desplegar para detectar problemas con antelación

Relacionado

• Servidor API - Documentación detallada de REST API
• Sesiones - Gestión de sesiones
• Artefactos - Almacenamiento de artefactos
• Observabilidad - Telemetría y registro

---

Anterior: ← Telemetría | Siguiente: Servidor →