Herramientas Integradas

ADK-Rust proporciona varias herramientas integradas que extienden las capacidades del agente sin requerir una implementación personalizada. Estas herramientas están listas para usar de inmediato y se integran perfectamente con el framework de agentes.

Las herramientas nativas del proveedor ahora se declaran a través de la API normal Tool en lugar de los blobs GenerateContentConfig.extensions específicos del proveedor. Esto significa que puedes combinar herramientas nativas como Gemini Google Search, Anthropic Web Search o la búsqueda web de OpenAI Responses con instancias FunctionTool ordinarias en el mismo agente.

Resumen

GoogleSearchTool

GoogleSearchTool permite a los agents buscar en la web usando Google Search. Esta tool es gestionada internamente por Gemini models a través de la grounding feature, lo que significa que la búsqueda se realiza server-side por el propio model.

Uso Básico

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create the GoogleSearchTool
    let search_tool = GoogleSearchTool;

    // Add to agent
    let agent = LlmAgentBuilder::new("research_assistant")
        .description("An assistant that can search the web for information")
        .instruction(
            "You are a research assistant. When asked about current events, \
             recent news, or factual information, use the google_search tool \
             to find accurate, up-to-date information."
        )
        .model(Arc::new(model))
        .tool(Arc::new(search_tool))
        .build()?;

    println!("Agent created with Google Search capability!");
    Ok(())
}

Cómo Funciona

A diferencia de las function tools regulares, GoogleSearchTool funciona de manera diferente:

1. Ejecución server-side: La búsqueda la realiza la grounding feature de Gemini, no localmente
2. Invocación automática: El model decide cuándo buscar basándose en la query
3. Resultados integrados: Los resultados de la búsqueda se incorporan directamente en la response del model

La implementación de la tool devuelve un error si se llama directamente porque la búsqueda real ocurre dentro de la Gemini API:

// This is handled internally - you don't call it directly
async fn execute(&self, _ctx: Arc<dyn ToolContext>, _args: Value) -> Result<Value> {
    Err(AdkError::tool("GoogleSearch is handled internally by Gemini"))
}

Detalles de la Tool

Casos de Uso

• Eventos actuales: "¿Qué sucedió en las noticias hoy?"
• Consultas de hechos: "¿Cuál es la población de Tokio?"
• Información reciente: "¿Cuáles son los últimos desarrollos en IA?"
• Tareas de investigación: "Buscar información sobre tendencias de energía renovable"

Consultas de Ejemplo

// The agent will automatically use Google Search for queries like:
// - "What's the weather forecast for New York this week?"
// - "Who won the latest championship game?"
// - "What are the current stock prices for tech companies?"

AgentTool

AgentTool envuelve cualquier agent como una tool invocable, permitiendo la agent composition donde un parent agent puede invocar un child agent como parte de su tool-calling workflow. Los cambios de estado y los artefactos del sub-agent se reenvían automáticamente al parent context.

Uso Básico

use adk_rust::prelude::*;
use adk_tool::AgentTool;
use std::sync::Arc;

let sub_agent = LlmAgentBuilder::new("summarizer")
    .description("Summarizes text content")
    .instruction("Summarize the provided text concisely.")
    .model(model.clone())
    .build()?;

let agent_tool = AgentTool::new(Arc::new(sub_agent));

let coordinator = LlmAgentBuilder::new("coordinator")
    .instruction("Use the summarizer tool when asked to summarize content.")
    .model(model.clone())
    .tool(Arc::new(agent_tool))
    .build()?;

Cómo funciona

1. El agente padre decide llamar al agente envuelto como una herramienta
2. AgentTool crea un contexto de invocación con StreamingMode::None
3. El sub-agente se ejecuta hasta completarse y acumula su respuesta completa
4. El texto de la respuesta se devuelve al agente padre
5. Los deltas de estado y los deltas de artefactos se reenvían al contexto padre

Detalles de la herramienta

Comportamiento clave

• Los sub-agentes se ejecutan en modo no-streaming internamente para una captura de respuesta fiable
• Los cambios de estado (output_key) del sub-agente se propagan a la sesión padre
• Los artefactos guardados por el sub-agente se reenvían al contexto padre
• Ver Sistemas Multi-Agente para más información sobre patrones de composición de agentes

ExitLoopTool

ExitLoopTool es una herramienta de control usada con LoopAgent para señalar cuándo debe terminar un proceso iterativo. Cuando se llama, establece la escalate flag, haciendo que el bucle salga.

Uso Básico

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create an agent with ExitLoopTool for iterative refinement
    let refiner = LlmAgentBuilder::new("content_refiner")
        .description("Iteratively improves content quality")
        .instruction(
            "Review the content and improve it. Check for:\n\
             1. Clarity and readability\n\
             2. Grammar and spelling\n\
             3. Logical flow\n\n\
             If the content meets all quality standards, call the exit_loop tool.\n\
             Otherwise, provide an improved version."
        )
        .model(Arc::new(model))
        .tool(Arc::new(ExitLoopTool::new()))
        .build()?;

    // Use in a LoopAgent
    let loop_agent = LoopAgent::new(
        "iterative_refiner",
        vec![Arc::new(refiner)],
    ).with_max_iterations(5);

    println!("Loop agent created with exit capability!");
    Ok(())
}

Cómo Funciona

1. El agente evalúa si continuar o salir
2. Cuando está listo para salir, el agente llama a exit_loop
3. La herramienta establece actions.escalate = true y actions.skip_summarization = true
4. El LoopAgent detecta la flag de escalada y deja de iterar

Detalles de la Herramienta

Mejores Prácticas

1. Criterios de salida claros: Define condiciones específicas en la instrucción del agente
2. Siempre establece max_iterations: Evita bucles infinitos como medida de seguridad
3. Instrucciones significativas: Ayuda al agente a entender cuándo salir

// Good: Clear exit criteria
.instruction(
    "Improve the text until it:\n\
     - Has no grammatical errors\n\
     - Is under 100 words\n\
     - Uses active voice\n\
     When all criteria are met, call exit_loop."
)

// Avoid: Vague criteria
.instruction("Improve the text. Exit when done.")

LoadArtifactsTool

LoadArtifactsTool permite a los agentes recuperar artefactos almacenados por nombre. Esto es útil cuando los agentes necesitan acceder a archivos, imágenes u otros datos binarios que fueron guardados previamente.

Uso Básico

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create agent with artifact loading capability
    let agent = LlmAgentBuilder::new("document_analyzer")
        .description("Analyzes stored documents")
        .instruction(
            "You can load and analyze stored artifacts. \
             Use the load_artifacts tool to retrieve documents by name. \
             The tool accepts an array of artifact names."
        )
        .model(Arc::new(model))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("Agent created with artifact loading capability!");
    Ok(())
}

Detalles de la Herramienta

Parámetros

La herramienta espera un objeto JSON con un array de artifact_names:

{
  "artifact_names": ["document.txt", "image.png", "data.json"]
}

Formato de Respuesta

La herramienta devuelve un objeto que contiene los artefactos cargados:

{
  "artifacts": [
    {
      "name": "document.txt",
      "content": "The text content of the document..."
    },
    {
      "name": "image.png",
      "content": {
        "mime_type": "image/png",
        "data": "base64-encoded-data..."
      }
    },
    {
      "name": "missing.txt",
      "error": "Artifact not found"
    }
  ]
}

Requisitos

Para que LoadArtifactsTool funcione, necesitas:

1. Un ArtifactService configurado en el Runner
2. Artefactos guardados previamente en el servicio
3. La herramienta añadida al Agent

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

// Set up artifact service
let artifact_service = Arc::new(InMemoryArtifactService::new());

// Configure runner with artifact service
let runner = Runner::new(agent)
    .with_artifact_service(artifact_service);

Combinando Herramientas Integradas

Puedes usar varias herramientas integradas juntas:

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create agent with multiple built-in tools
    let agent = LlmAgentBuilder::new("research_agent")
        .description("Research agent with search and artifact capabilities")
        .instruction(
            "You are a research agent. You can:\n\
             - Search the web using google_search for current information\n\
             - Load stored documents using load_artifacts\n\
             Use these tools to help answer questions comprehensively."
        )
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("Multi-tool agent created!");
    Ok(())
}

Creando Herramientas Integradas Personalizadas

Puedes crear tus propias herramientas siguiendo el mismo patrón que las herramientas incorporadas implementando el Tool trait:

use adk_rust::prelude::*;
use async_trait::async_trait;
use serde_json::{json, Value};
use std::sync::Arc;

pub struct MyCustomTool;

impl MyCustomTool {
    pub fn new() -> Self {
        Self
    }
}

#[async_trait]
impl Tool for MyCustomTool {
    fn name(&self) -> &str {
        "my_custom_tool"
    }

    fn description(&self) -> &str {
        "Description of what this tool does"
    }

    async fn execute(&self, ctx: Arc<dyn ToolContext>, args: Value) -> Result<Value> {
        // Your tool logic here
        Ok(json!({ "result": "success" }))
    }
}

Referencia de la API

GoogleSearchTool

impl GoogleSearchTool {
    /// Create a new GoogleSearchTool instance
    pub fn new() -> Self;
}

ExitLoopTool

impl ExitLoopTool {
    /// Create a new ExitLoopTool instance
    pub fn new() -> Self;
}

LoadArtifactsTool

impl LoadArtifactsTool {
    /// Create a new LoadArtifactsTool instance
    pub fn new() -> Self;
}

impl Default for LoadArtifactsTool {
    fn default() -> Self;
}

Relacionado

• Herramientas de Función - Creación de herramientas de función personalizadas
• Herramientas MCP - Uso de servidores MCP como proveedores de herramientas
• Agentes de Flujo de Trabajo - Uso de ExitLoopTool con LoopAgent
• Artefactos - Gestión de datos binarios con artefactos

---

Anterior: ← Herramientas de Función | Siguiente: Herramientas del Navegador →