Proveedores de modelos (nube)

ADK-Rust admite múltiples proveedores de LLM en la nube a través del crate adk-model. Todos los proveedores implementan el trait Llm, lo que los hace intercambiables en tus agentes.

Descripción general

┌─────────────────────────────────────────────────────────────────────┐
│                     Cloud Model Providers                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   • Gemini (Google)    ⭐ Default    - Multimodal, large context    │
│   • OpenAI (GPT-5)    🔥 Popular    - Best ecosystem               │
│   • Anthropic (Claude) 🧠 Smart      - Best reasoning               │
│   • DeepSeek           💭 Thinking   - Chain-of-thought, cheap      │
│   • Groq               ⚡ Ultra-Fast  - Fastest inference           │
│                                                                     │
│   For local/offline models, see:                                    │
│   • Ollama     → ollama.md                                          │
│   • mistral.rs → mistralrs.md                                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Comparación rápida

---

Paso 1: Instalación

Agrega los proveedores que necesitas a tu Cargo.toml:

[dependencies]
# Pick one or more providers:
adk-model = { version = "2.0.0", features = ["gemini"] }        # Google Gemini (default)
adk-model = { version = "2.0.0", features = ["openai"] }        # OpenAI GPT-5
adk-model = { version = "2.0.0", features = ["anthropic"] }     # Anthropic Claude
adk-model = { version = "2.0.0", features = ["deepseek"] }      # DeepSeek
adk-model = { version = "2.0.0", features = ["groq"] }          # Groq (ultra-fast)

# Or all cloud providers at once:
adk-model = { version = "2.0.0", features = ["all-providers"] }

Paso 2: Establece tu clave API

export GOOGLE_API_KEY="your-key"      # Gemini
export OPENAI_API_KEY="your-key"      # OpenAI
export ANTHROPIC_API_KEY="your-key"   # Anthropic
export DEEPSEEK_API_KEY="your-key"    # DeepSeek
export GROQ_API_KEY="your-key"        # Groq

Normalización de esquemas

Cada proveedor normaliza automáticamente los esquemas de herramientas MCP en tiempo de solicitud. No necesitas hacer nada — funciona de forma transparente. Pero esto es lo que sucede internamente:

Accede al adaptador programáticamente a través del trait Llm:

use adk_core::{Llm, SchemaAdapter};

let adapter = model.schema_adapter();
let normalized = adapter.normalize_schema(raw_schema);

Consulta Normalización de esquema para la documentación completa.

---

Gemini (Google) ⭐ Predeterminado

Ideal para: Tareas de propósito general, multimodales, documentos grandes

Aspectos destacados:

• 🖼️ Multimodal nativo (imágenes, video, audio, PDF)
• 📚 Hasta 2M de ventana de contexto de tokens
• 🧠 Modo de pensamiento: basado en niveles (Gemini 3) y basado en presupuesto (Gemini 2.5) con firmas de pensamiento
• 💰 Precios competitivos
• ⚡ Inferencia rápida

Ejemplo completo funcional

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

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    let agent = LlmAgentBuilder::new("gemini_assistant")
        .description("Gemini-powered assistant")
        .instruction("You are a helpful assistant powered by Google Gemini. Be concise.")
        .model(Arc::new(model))
        .build()?;

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

Modelos disponibles

Modo de razonamiento

Los modelos Gemini 3 admiten razonamiento basado en niveles, mientras que Gemini 2.5 usa razonamiento basado en presupuesto. Al usar el modo de razonamiento con llamadas a funciones, los modelos Gemini 2.5+ y 3.x devuelven valores thoughtSignature que deben reenviarse en turnos posteriores para preservar el contexto del razonamiento. ADK-Rust lo maneja automáticamente: las firmas se serializan cuando están presentes y se omiten cuando None.

use adk_gemini::{Gemini, ThinkingLevel};

// Gemini 3: level-based thinking
let response = client.generate_content()
    .with_user_message("Solve this step by step")
    .with_thinking_level(ThinkingLevel::High)
    .with_thoughts_included(true)
    .execute().await?;

// Gemini 2.5: budget-based thinking
let response = client.generate_content()
    .with_user_message("Solve this step by step")
    .with_thinking_budget(2048)
    .with_thoughts_included(true)
    .execute().await?;

Ejemplo de salida

👤 User: What's in this image? [uploads photo of a cat]

🤖 Gemini: I can see a fluffy orange tabby cat sitting on a windowsill. 
The cat appears to be looking outside, with sunlight illuminating its fur. 
It has green eyes and distinctive striped markings typical of tabby cats.

---

OpenAI (GPT-5) 🔥 Popular

Mejor para: aplicaciones de producción, rendimiento confiable, amplias capacidades

Aspectos destacados:

• 🏆 Estándar de la industria
• 🔧 Excelente llamada de herramientas/funciones
• 📖 Mejor documentación y ecosistema
• 🎯 Salidas consistentes y predecibles
• 📋 Salida estructurada con aplicación estricta del esquema JSON
• 🧠 control de esfuerzo de razonamiento para modelos de razonamiento o1/o3
• 🆕 Responses API — cliente dedicado para /v1/responses con resúmenes de razonamiento, herramientas integradas y estado del lado del servidor

Ejemplo completo funcional

use adk_rust::prelude::*;
use adk_rust::Launcher;
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 = OpenAIClient::new(OpenAIConfig::new(&api_key, "gpt-5-mini"))?;

    let agent = LlmAgentBuilder::new("openai_assistant")
        .description("OpenAI-powered assistant")
        .instruction("You are a helpful assistant powered by OpenAI GPT-5. Be concise.")
        .model(Arc::new(model))
        .build()?;

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

Salida estructurada (esquema JSON)

OpenAI admite salida JSON garantizada mediante output_schema. ADK-Rust conecta esto automáticamente con el response_format OpenAI de API:

use adk_rust::prelude::*;
use serde_json::json;
use std::sync::Arc;

let model = OpenAIClient::new(OpenAIConfig::new(&api_key, "gpt-5-mini"))?;

let agent = LlmAgentBuilder::new("data_extractor")
    .model(Arc::new(model))
    .instruction("Extract person information from the text.")
    .output_schema(json!({
        "type": "object",
        "properties": {
            "name": { "type": "string" },
            "age": { "type": "number" },
            "email": { "type": "string" }
        },
        "required": ["name", "age"]
    }))
    .build()?;

// Response is guaranteed to be valid JSON matching the schema

Para el modo estricto con objetos anidados, incluye additionalProperties: false en cada nivel:

.output_schema(json!({
    "type": "object",
    "properties": {
        "title": { "type": "string" },
        "metadata": {
            "type": "object",
            "properties": {
                "author": { "type": "string" },
                "tags": { "type": "array", "items": { "type": "string" } }
            },
            "required": ["author"],
            "additionalProperties": false  // Required for nested objects
        }
    },
    "required": ["title", "metadata"],
    "additionalProperties": false  // Auto-injected at root level
}))

Esfuerzo de razonamiento (modelos o1, o3)

Para los modelos de razonamiento OpenAI, controla cuánta capacidad de razonamiento aplica el modelo:

use adk_model::openai::{OpenAIClient, OpenAIConfig, ReasoningEffort};

let config = OpenAIConfig::new(&api_key, "o3-mini")
    .with_reasoning_effort(ReasoningEffort::High);
let model = OpenAIClient::new(config)?;

Niveles disponibles: Low, Medium, High. Un mayor esfuerzo produce un razonamiento más minucioso a costa de latencia y tokens.

OpenAI-Compatible Local APIs

Usa OpenAIConfig::compatible() para conectarte a servidores locales (Ollama, vLLM, LM Studio):

// Ollama exposes OpenAI-compatible API at /v1
let config = OpenAIConfig::compatible(
    "not-needed",                      // API key (ignored by Ollama)
    "http://localhost:11434/v1",       // Base URL
    "llama3.2"                         // Model name
);
let model = OpenAIClient::new(config)?;

Nota: la salida estructurada (output_schema) requiere compatibilidad del backend. El OpenAI nativo la admite plenamente; los servidores locales pueden tener compatibilidad limitada.

Gemini a través del punto final compatible con OpenAI

Los modelos Gemini son accesibles a través del formato de cableado Chat Completions de OpenAI en https://generativelanguage.googleapis.com/v1beta/openai. Usa el preset OpenAICompatibleConfig::gemini(...) (dentro de la función openai) con un GEMINI_API_KEY para ejecutar Gemini mediante el mismo cliente compatible con OpenAI que usas para cualquier otro proveedor:

use adk_model::openai_compatible::{OpenAICompatible, OpenAICompatibleConfig};

let api_key = std::env::var("GEMINI_API_KEY")?;
let model = OpenAICompatible::new(
    OpenAICompatibleConfig::gemini(api_key, "gemini-3.5-flash"),
)?;

Esta ruta admite chat, streaming, llamada a funciones, salida estructurada y esfuerzo de razonamiento (OpenAI's reasoning_effort se mapea a los niveles/presupuestos de pensamiento de Gemini). Las opciones específicas de Gemini — por ejemplo, thinking_config con include_thoughts, o cached_content — se pasan a través del mapa extensions["openai"]["extra_body"]["google"] de la solicitud, que el cliente fusiona literalmente en el cuerpo de la solicitud.

Cuándo usar esto vs GeminiModel: para funciones nativas de Gemini (herramientas del lado del servidor, el API de Interactions, ThinkingConfig nativo, ergonomía centrada primero en multimodalidad), prefiere GeminiModel. Usa el preset compatible con OpenAI cuando quieras un único cliente uniforme en todos los proveedores.

Ejemplos (requieren GEMINI_API_KEY o GOOGLE_API_KEY):

# Direct client: chat, reasoning effort, extra_body thinking, streaming,
# function calling, structured output.
cargo run -p adk-model --features openai --example gemini_openai_compat

# The same compat client driving a normal LlmAgent in a Runner.
# (Lives in adk-agent: it exercises the agent layer, which sits above adk-model.)
cargo run -p adk-agent --example gemini_openai_compat_agent

Esfuerzo de razonamiento (modelos o1, o3)

Controla cuánta capacidad de razonamiento aplica el modelo con ReasoningEffort:

use adk_model::openai::{OpenAIClient, OpenAIConfig, ReasoningEffort};

let config = OpenAIConfig::new(&api_key, "o3-mini")
    .with_reasoning_effort(ReasoningEffort::High);
let model = OpenAIClient::new(config)?;

Niveles disponibles: Low (más rápido), Medium (equilibrado), High (más minucioso).

Modelos disponibles

Ejemplo de salida

👤 User: Write a haiku about Rust programming

🤖 GPT-5: Memory so safe,
Ownership guards every byte—
Compiler, my friend.

---

Anthropic (Claude) 🧠 Inteligente

Mejor para: Razonamiento complejo, aplicaciones críticas para la seguridad, documentos largos

Aspectos destacados:

• 🧠 Capacidad de razonamiento excepcional
• 🛡️ Más centrado en la seguridad
• 📚 Contexto de 200K tokens
• ✍️ Excelente calidad de escritura

Ejemplo completo y funcional

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

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("ANTHROPIC_API_KEY")?;
    let model = AnthropicClient::new(AnthropicConfig::new(&api_key, "claude-sonnet-4-6"))?;

    let agent = LlmAgentBuilder::new("anthropic_assistant")
        .description("Anthropic-powered assistant")
        .instruction("You are a helpful assistant powered by Anthropic Claude. Be concise and thoughtful.")
        .model(Arc::new(model))
        .build()?;

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

Modelos disponibles

Ejemplo de salida

👤 User: Explain quantum entanglement to a 10-year-old

🤖 Claude: Imagine you have two magic coins. When you flip them, they always 
land the same way - both heads or both tails - even if one coin is on Earth 
and the other is on the Moon! Scientists call this "entanglement." The coins 
are connected in a special way that we can't see, like invisible best friends 
who always make the same choice at the exact same time.

---

DeepSeek 💭 Pensamiento

Mejor para: Resolución de problemas complejos, matemáticas, programación, tareas de razonamiento

Aspectos destacados:

• 💭 Modo de pensamiento - muestra razonamiento paso a paso
• 💰 Muy rentable (10x más barato que GPT-4)
• 🔄 Caché de contexto para prefijos repetidos
• 🧮 Muy sólido en matemáticas y programación

Ejemplo completo funcional

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

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("DEEPSEEK_API_KEY")?;
    
    // Standard chat model
    let model = DeepSeekClient::chat(&api_key)?;
    
    // OR: Reasoning model with thinking mode
    // let model = DeepSeekClient::reasoner(&api_key)?;

    let agent = LlmAgentBuilder::new("deepseek_assistant")
        .description("DeepSeek-powered assistant")
        .instruction("You are a helpful assistant powered by DeepSeek. Be concise.")
        .model(Arc::new(model))
        .build()?;

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

Modelos disponibles

Ejemplo de salida (Reasoner con modo de pensamiento)

👤 User: What's 17 × 23?

🤖 DeepSeek: <thinking>
Let me break this down:
17 × 23 = 17 × (20 + 3)
       = 17 × 20 + 17 × 3
       = 340 + 51
       = 391
</thinking>

The answer is 391.

---

Groq ⚡ Ultra rápido

Ideal para: aplicaciones en tiempo real, chatbots, tareas críticas de velocidad

Aspectos clave:

• ⚡ Inferencia más rápida - 10x más rápido que la competencia
• 🔧 tecnología LPU (Language Processing Unit)
• 💰 precios competitivos
• 🦙 ejecuta modelos LLaMA, Mixtral, Gemma

Ejemplo completo funcional

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

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

    let agent = LlmAgentBuilder::new("groq_assistant")
        .description("Groq-powered assistant")
        .instruction("You are a helpful assistant powered by Groq. Be concise and fast.")
        .model(Arc::new(model))
        .build()?;

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

Modelos disponibles

Salida de ejemplo

👤 User: Quick! Name 5 programming languages

🤖 Groq (in 0.2 seconds): 
1. Rust
2. Python
3. JavaScript
4. Go
5. TypeScript

---

Cambio de proveedores

Todos los proveedores implementan el mismo trait Llm, así que cambiar es fácil:

use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

// Just change the model - everything else stays the same!
let model: Arc<dyn adk_core::Llm> = Arc::new(
    // Pick one:
    // GeminiModel::new(&api_key, "gemini-2.5-flash")?
    // OpenAIClient::new(OpenAIConfig::new(&api_key, "gpt-5-mini"))?
    // AnthropicClient::new(AnthropicConfig::new(&api_key, "claude-sonnet-4-6"))?
    // DeepSeekClient::chat(&api_key)?
    // GroqClient::llama70b(&api_key)?
);

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

---

Ejemplos

Usa cargo-adk para generar proyectos específicos de proveedor con dependencias 0.8 validadas:

cargo adk new gemini_agent --provider gemini
cargo adk new openai_agent --template openai
cargo adk new anthropic_agent --provider anthropic

Los proyectos generados se compilan en CI por scripts/check-cargo-adk-templates.sh. Explora y ejecuta la galería completa de ejemplos en el ADK-Rust Playground integrado en este sitio web.

---

Relacionado

• Ollama (Local) - Ejecutar modelos localmente con Ollama
• Modelos locales (mistral.rs) - Inferencia nativa en Rust
• LlmAgent - Usar modelos con agentes
• Herramientas de función - Añadir herramientas a agentes

---

Anterior: ← Agentes en tiempo real | Siguiente: Ollama (Local) →

Qué ocurre con el contenido que un proveedor no puede transportar

Content puede expresar más de lo que acepta cualquier transporte de proveedor individual, así que cada adaptador tiene que decidir qué hacer con el resto. Esas decisiones ahora se registran en lugar de aplicarse de forma invisible. Cada parte se clasifica:

Las degradaciones y omisiones emiten una advertencia tracing cuando se registran, indicando el tipo de parte, el tipo MIME y el motivo, de modo que ninguna pase desapercibida.

Para ver el resultado antes de enviar una solicitud:

use adk_core::{Content, Part};
use adk_model::bedrock::convert::report_for_contents;

let content = Content {
    role: "user".to_string(),
    parts: vec![Part::inline_data("audio/wav", vec![0u8; 16])],
};
let report = report_for_contents(std::slice::from_ref(&content));

for omission in report.omitted_parts() {
    println!("{} was dropped: {}", omission.kind, omission.detail);
}

Para rechazar una solicitud que llegaría al modelo incompleta, en lugar de recibir una respuesta sobre material que el modelo nunca vio:

use adk_core::{Content, Part};
use adk_model::bedrock::convert::report_for_contents;

let content = Content {
    role: "user".to_string(),
    parts: vec![Part::inline_data("video/mp4", vec![0u8; 16])],
};

if let Some(error) = report_for_contents(std::slice::from_ref(&content)).into_error() {
    return Err(error);
}

into_error solo cubre las omisiones. Una degradación todavía llega al modelo, y rechazarla supondría rechazar la alternativa textual documentada.

Nota: el registro es completo por construcción. Cualquier parte que salga de un adaptador sin un destino registrado —incluida una añadida por un cambio futuro— se registra como una omisión con un explícito "no recorded reason", y adk-model/tests/part_conversion_matrix_tests.rs falla en ella.

Cobertura de Bedrock Converse