Inicio rápido

Esta guía muestra cómo empezar a usar ADK-Rust. Crearás tu primer agente de IA en menos de 10 minutos.

Requisitos previos

Antes de empezar, asegúrate de tener:

• Rust 1.85.0 o posterior (rustup update stable)
• Una clave de API de Google para Gemini

Paso 1: Crear un nuevo proyecto

Crea un nuevo proyecto Rust:

cargo new my_agent
cd my_agent

La estructura de tu proyecto se verá así:

my_agent/
├── Cargo.toml
├── src/
│   └── main.rs
└── .env          # Lo crearás para tu clave de API

Paso 2: Añadir dependencias

Actualiza tu Cargo.toml con las dependencias requeridas:

[package]
name = "my_agent"
version = "0.1.0"
edition = "2024"

[dependencies]
adk-rust = "0.2.0"
tokio = { version = "1.40", features = ["full"] }
dotenvy = "0.15"

Instala las dependencias:

cargo build

Paso 3: Configurar tu clave de API

Este proyecto usa la API de Gemini, que requiere una clave de API. Si no tienes una, crea una clave en Google AI Studio.

Crea un archivo .env en la raíz de tu proyecto:

Linux / macOS:

echo 'GOOGLE_API_KEY=your-api-key-here' > .env

Windows (PowerShell):

echo GOOGLE_API_KEY=your-api-key-here > .env

Consejo de seguridad: Añade .env a tu .gitignore para evitar subir tu clave de API.

Paso 4: Escribe tu Agent

Reemplaza el contenido de src/main.rs con:

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Load environment variables from .env file
    dotenvy::dotenv().ok();
    
    // Get API key from environment
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    // Create the Gemini model
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Build your agent
    let agent = LlmAgentBuilder::new("my_assistant")
        .description("A helpful AI assistant")
        .instruction("You are a friendly and helpful assistant. Answer questions clearly and concisely.")
        .model(Arc::new(model))
        .build()?;

    // Run the agent with the CLI launcher
    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Paso 5: Ejecuta tu Agent

Inicia tu agente en modo de consola interactiva:

cargo run

Verás un mensaje donde podrás chatear con tu agente:

🤖 Agent ready! Type your questions (or 'exit' to quit).

You: Hello! What can you help me with?
Assistant: Hello! I'm a helpful AI assistant. I can help you with:
- Answering questions on various topics
- Explaining concepts
- Providing information and suggestions
- Having a friendly conversation

What would you like to know?

You: exit
👋 Goodbye!

Paso 6: Añadir una Herramienta

Vamos a mejorar tu agente con la herramienta Google Search para darle acceso a información en tiempo real:

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Build agent with Google Search tool
    let agent = LlmAgentBuilder::new("search_assistant")
        .description("An assistant that can search the web")
        .instruction("You are a helpful assistant. Use the search tool to find current information when needed.")
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool::new()))  // Add search capability
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Inicia tu agente de nuevo en modo consola interactiva:

cargo run

Ahora puedes pedirle a tu agente que busque en la web:

Tú: What's the weather like in Tokyo today?
Asistente: Déjame buscar esa información...
[Using GoogleSearchTool]
Según la información actual, Tokio está experimentando...

Ejecutando como un Servidor Web

Para una interfaz basada en web, ejecuta con el comando serve:

cargo run -- serve

Esto inicia el servidor en el puerto predeterminado 8080. Accede a él en http://localhost:8080.

Para especificar un puerto personalizado:

cargo run -- serve --port 3000

Esto inicia el servidor en el puerto 3000. Accede a él en http://localhost:3000.

Comprendiendo el Código

Vamos a desglosar lo que hace cada parte:

Importaciones

use adk_rust::prelude::*;  // GeminiModel, LlmAgentBuilder, Arc, etc.
use adk_rust::Launcher;    // CLI launcher for console/server modes
use std::sync::Arc;        // Thread-safe reference counting pointer

• prelude::* importa todos los tipos de uso común: GeminiModel, LlmAgentBuilder, Arc, tipos de error y más.
• Launcher proporciona la interfaz CLI para ejecutar agentes.
• Arc (Atomic Reference Counted) permite compartir de forma segura el modelo y el agente entre tareas async.

Creación del Modelo

let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

Crea una instancia del modelo Gemini que implementa el trait Llm. El modelo:

• Gestiona la autenticación con tu clave de API.
• Gestiona las respuestas en streaming del LLM.
• Soporta la llamada a funciones para herramientas.

Construcción del Agente

let agent = LlmAgentBuilder::new("my_assistant")
    .description("A helpful AI assistant")
    .instruction("You are a friendly assistant...")
    .model(Arc::new(model))
    .build()?;

El patrón builder configura tu agente:

Launcher

Launcher::new(Arc::new(agent)).run().await?;

El Launcher gestiona el tiempo de ejecución:

• Modo consola (predeterminado): Chat interactivo en tu terminal.
• Modo servidor (-- serve): API REST con interfaz web.
• Gestiona el estado de la sesión, las respuestas en streaming y el apagado elegante.

Uso de Otros Modelos

adk-rust es compatible con múltiples proveedores de LLM de forma predeterminada. Habilítelos mediante feature flags en su Cargo.toml:

[dependencies]
adk-rust = { version = "0.2.0", features = ["openai", "anthropic", "deepseek", "groq", "ollama"] }

Establezca la clave API apropiada para su proveedor:

# OpenAI
export OPENAI_API_KEY="your-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# DeepSeek
export DEEPSEEK_API_KEY="your-api-key"

# Groq
export GROQ_API_KEY="your-api-key"

# Ollama (no key needed, just run: ollama serve)

OpenAI

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Anthropic

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

DeepSeek

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("DEEPSEEK_API_KEY")?;

    // Modelo de chat estándar
    let model = DeepSeekClient::chat(api_key)?;

    // O use reasoner para el razonamiento en cadena de pensamiento
    // let model = DeepSeekClient::reasoner(api_key)?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Groq (Inferencia Ultra Rápida)

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Ollama (Modelos Locales)

use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

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

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Modelos Compatibles

Siguientes Pasos

Ahora que tienes tu primer agent en funcionamiento, explora estos temas:

• LlmAgent Configuración - Todas las opciones de configuración
• Function Tools - Crea tools personalizadas
• Workflow Agents - Crea pipelines de múltiples pasos
• Sessions - Gestiona el estado de la conversación
• Callbacks - Personaliza el comportamiento del agent

---

Anterior: Introducción | Siguiente: LlmAgent