Inicio rápido

Crea tu primer agente de IA en menos de 5 minutos.

Requisitos previos

• Rust 1.95.0 o posterior (rustup update stable)
• Una clave de OpenAI API para este recorrido

Paso 1: Crear la estructura de un servidor OpenAI

cargo install cargo-adk
cargo adk new quickstart_agent --template api --provider openai
cd quickstart_agent

Esto crea un proyecto completo de Rust con un agente OpenAI, sesiones en memoria, el runtime ADK HTTP, endpoints de streaming y la interfaz de desarrollo integrada.

Otras plantillas

# Agent with custom tools using #[tool] macro
cargo adk new my_agent --template tools

# RAG agent with Gemini embeddings and in-memory vector search
cargo adk new my_agent --template rag

# REST API server with the embedded runtime UI
cargo adk new my_agent --template api

# OpenAI GPT-5-mini agent
cargo adk new my_agent --template openai

# A2A protocol agent with builder API
cargo adk new my_agent --template a2a

# Use any provider with any template
cargo adk new my_agent --template tools --provider anthropic

# Add optional addons to any template
cargo adk new my_agent --template tools --addon docker --addon ci

Consejo: Usa la opción --addon para componer plantillas con complementos opcionales como docker, ci, telemetry y más. Consulta la página Plantillas componibles para ver la lista completa de 9 complementos y 5 patrones empresariales.

Paso 2: Añade tu clave API

cp .env.example .env
# Open .env and replace the OPENAI_API_KEY placeholder.

El .gitignore generado excluye .env. Mantén la clave local y nunca la confirmes en el repositorio.

Paso 3: Ejecuta el agente

cargo run

Abre http://127.0.0.1:8080/ui/. El agente aparece automáticamente; no necesitas crear una sesión ni llamar primero a un endpoint.

Paso 4: Pruébalo en la interfaz de usuario del entorno de ejecución

Introduce un mensaje como:

Explain what this agent can do in three concise Markdown bullets.

La respuesta se transmite a la conversación. Usa el inspector de la derecha para revisar la topología de ejecución, la cronología ordenada de eventos, los cambios de estado, los artefactos, las sesiones, las capacidades del protocolo y la telemetría sin salir de la página.

Esta grabación utiliza la demostración de equipo portátil para que la transferencia animada sea fácil de ver. Tu agente creado mediante el andamiaje utiliza la misma interfaz de usuario del entorno de ejecución con una topología de un solo nodo.

Verifica el entorno de ejecución de HTTP por separado si quieres realizar una prueba rápida:

curl -fsS http://127.0.0.1:8080/api/health

Ahora tienes un ejecutable que ejecuta el agente, administra sesiones, transmite eventos y ofrece su propia interfaz de prueba. No se necesita instalar un frontend independiente.

¿Prefieres un agente que solo use la terminal?

Usa en su lugar la plantilla de consola OpenAI:

cargo adk new quickstart_console --template openai
cd quickstart_console
cp .env.example .env   # replace the OPENAI_API_KEY placeholder
cargo run

---

Alternativa sin configuración — adk::run()

Si solo quieres ejecutar rápidamente un agente sin crear un andamiaje, usa el comando de una sola línea:

use adk_rust::run;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    // Minimal default: set GOOGLE_API_KEY. Add provider features for OpenAI/Anthropic.
    let response = run("You are a helpful assistant.", "Explain Rust in one sentence.").await?;
    println!("{response}");
    Ok(())
}

Esto gestiona la detección de proveedores compilados, la creación de sesiones, la construcción del agente y la ejecución en una sola llamada. Es ideal para scripts, prototipos y experimentos rápidos.

---

Comprender el código generado

El API del scaffold src/main.rs construye un LlmAgent ordinario y, después, lo monta en el servidor estándar. La conexión importante es:

use adk_rust::prelude::*;
use adk_rust::server::{ServerConfig, create_app};
use adk_rust::session::InMemorySessionService;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("OPENAI_API_KEY")?;

    let model = adk_rust::model::openai::OpenAIClient::new(
        adk_rust::model::openai::OpenAIConfig::new(&api_key, "gpt-5.6-terra"),
    )?;

    let agent: Arc<dyn Agent> = Arc::new(
        LlmAgentBuilder::new("quickstart_agent")
            .description("REST API agent")
            .instruction("You are a helpful assistant accessible via REST API.")
            .model(Arc::new(model))
            .build()?,
    );

    let config = ServerConfig::new(
        Arc::new(adk_rust::SingleAgentLoader::new(agent)),
        Arc::new(InMemorySessionService::new()),
    );
    let app = create_app(config);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

---

Añadir herramientas personalizadas

La forma más rápida de añadir herramientas es mediante la macro #[tool]. Añade adk-tool a tus dependencias:

[dependencies]
adk-tool = "2.1.0"
schemars = "1"
serde = { version = "1", features = ["derive"] }

A continuación, define una herramienta; el comentario de documentación se convierte en la descripción y la estructura de argumentos se convierte en el esquema de JSON:

use adk_tool::{tool, AdkError};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::{json, Value};

#[derive(Deserialize, JsonSchema)]
struct WeatherArgs {
    /// The city to look up
    city: String,
}

/// Get the current weather for a city.
#[tool]
async fn get_weather(args: WeatherArgs) -> std::result::Result<Value, AdkError> {
    Ok(json!({ "temp": 22, "city": args.city, "condition": "sunny" }))
}

La macro genera una estructura GetWeather que implementa Tool. Añádela a tu agente:

let agent = LlmAgentBuilder::new("weather_agent")
    .instruction("Use the get_weather tool for weather questions.")
    .model(Arc::new(model))
    .tool(Arc::new(GetWeather))  // Generated by #[tool]
    .build()?;

Consejo: También puedes crear un proyecto con las herramientas ya configuradas: cargo adk new my-agent --template tools

Herramientas integradas

ADK también incluye herramientas listas para usar:

// Google Search (handled server-side by Gemini)
.tool(Arc::new(GoogleSearchTool::new()))

// Exit a LoopAgent
.tool(Arc::new(ExitLoopTool::new()))

---

Ejecutar como servidor web

Crea un proyecto de servidor cuando quieras servir HTTP:

cargo adk new my-api --template api --provider openai
cd my-api
cp .env.example .env
cargo run

Abre http://127.0.0.1:8080/ui/. La plantilla básica predeterminada utiliza en su lugar el lanzador ligero de consola.

---

Usar otros modelos

Habilita los proveedores mediante indicadores de funcionalidad. La compilación predeterminada solo incluye Gemini para agilizar las instalaciones, así que añade únicamente el proveedor que necesites:

[dependencies]
adk-rust = { version = "2.1.0", features = ["openai"] }

También puedes crear un proyecto con un proveedor: cargo adk new my-agent --provider openai

OpenAI

let api_key = std::env::var("OPENAI_API_KEY")?;
let model = OpenAIClient::new(OpenAIConfig::new(api_key, "gpt-5.6-terra"))?;

Anthropic

let api_key = std::env::var("ANTHROPIC_API_KEY")?;
let model = AnthropicClient::new(AnthropicConfig::new(api_key, "claude-sonnet-5"))?;

DeepSeek

let api_key = std::env::var("DEEPSEEK_API_KEY")?;
let model = DeepSeekClient::chat(api_key)?;         // standard
// let model = DeepSeekClient::reasoner(api_key)?;   // chain-of-thought

Groq

let api_key = std::env::var("GROQ_API_KEY")?;
let model = GroqClient::new(GroqConfig::gpt_oss_120b(api_key))?;

Ollama (local)

// Requires: ollama serve && ollama pull llama3.2
let model = OllamaModel::new(OllamaConfig::new("llama3.2"))?;

Modelos compatibles

---

Próximos pasos

• LlmAgent Configuración — todas las opciones de configuración
• Herramientas de función — crea herramientas personalizadas con #[tool]
• Agentes de flujo de trabajo — canalizaciones secuenciales, paralelas y en bucle
• Sesiones — gestiona el estado de la conversación
• Devoluciones de llamada — personaliza el comportamiento del agente

---

Anterior: Introducción | Siguiente: LlmAgent