Herramientas Integradas

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

Resumen

GoogleSearchTool

GoogleSearchTool permite a los agentes buscar en la web utilizando Google Search. Esta herramienta es gestionada internamente por los modelos Gemini a través de la característica de grounding, lo que significa que la búsqueda se realiza del lado del servidor por el propio modelo.

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 herramientas de función regulares, GoogleSearchTool opera de manera diferente:

1. Ejecución del lado del servidor: La búsqueda es realizada por la característica de grounding de Gemini, no localmente.
2. Invocación automática: El modelo decide cuándo buscar basándose en la consulta.
3. Resultados integrados: Los resultados de la búsqueda se incorporan directamente en la respuesta del modelo.

La implementación de la herramienta 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".to_string()))
}

Detalles de la Herramienta

Casos de Uso

• Eventos actuales: "¿Qué pasó 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: "Encuentra información sobre las tendencias de energía renovable"

Consultas de Ejemplo

// El agente usará automáticamente Google Search para consultas como:
// - "¿Cuál es el pronóstico del tiempo para Nueva York esta semana?"
// - "¿Quién ganó el último partido del campeonato?"
// - "¿Cuáles son los precios actuales de las acciones de las empresas de tecnología?"

ExitLoopTool

ExitLoopTool es una herramienta de control utilizada con LoopAgent para señalar cuándo debe terminar un proceso iterativo. Cuando se llama, establece la bandera escalate, lo que provoca la salida del bucle.

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")?;

    // Crear un agente con ExitLoopTool para un refinamiento iterativo
    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()?;

    // Usar en un 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 Agent evalúa si continuar o salir
2. Cuando está listo para salir, el Agent llama a exit_loop
3. La herramienta establece actions.escalate = true y actions.skip_summarization = true
4. El LoopAgent detecta la bandera escalate y detiene la iteración

Detalles de la Herramienta

Mejores Prácticas

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

// Bueno: Criterios de salida claros
.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."
)

// Evitar: Criterios vagos
.instruction("Improve the text. Exit when done.")

LoadArtifactsTool

LoadArtifactsTool permite a los agentes recuperar artefactos almacenados por su nombre. Esto es útil cuando los agentes necesitan acceder a archivos, imágenes u otros datos binarios que se guardaron 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")?;

    // Crear agente con capacidad de carga de artefactos
    let agent = LlmAgentBuilder::new("document_analyzer")
        .description("Analiza documentos almacenados")
        .instruction(
            "Puedes cargar y analizar artefactos almacenados. \
             Usa la herramienta load_artifacts para recuperar documentos por su nombre. \
             La herramienta acepta un array de nombres de artefactos."
        )
        .model(Arc::new(model))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("¡Agente creado con capacidad de carga de artefactos!");
    Ok(())
}

Detalles de la Herramienta

Parámetros

La herramienta espera un objeto JSON con un array 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 previamente guardados en el servicio
3. La herramienta añadida al agent

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

// Configurar el servicio de artefactos
let artifact_service = Arc::new(InMemoryArtifactService::new());

// Configurar el runner con el servicio de artefactos
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")?;

    // Crear agente con múltiples herramientas integradas
    let agent = LlmAgentBuilder::new("research_agent")
        .description("Agente de investigación con capacidades de búsqueda y artefactos")
        .instruction(
            "Eres un agente de investigación. Puedes:\n\
             - Buscar en la web usando google_search para obtener información actual\n\
             - Cargar documentos almacenados usando load_artifacts\n\
             Usa estas herramientas para ayudar a responder preguntas de manera exhaustiva."
        )
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("¡Agente multi-herramienta creado!");
    Ok(())
}

Creación de Herramientas Integradas Personalizadas

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

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> {
        // Tu lógica de herramienta aquí
        Ok(json!({ "result": "success" }))
    }
}

Referencia de la API

GoogleSearchTool

impl GoogleSearchTool {
    /// Crea una nueva instancia de GoogleSearchTool
    pub fn new() -> Self;
}

ExitLoopTool

impl ExitLoopTool {
    /// Crea una nueva instancia de ExitLoopTool
    pub fn new() -> Self;
}

LoadArtifactsTool

impl LoadArtifactsTool {
    /// Crea una nueva instancia de LoadArtifactsTool
    pub fn new() -> Self;
}

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

Relacionado

• Function Tools - Creación de Function Tools personalizadas
• MCP Tools - Uso de servidores MCP como proveedores de Tool
• Workflow Agents - Uso de ExitLoopTool con LoopAgent
• Artifacts - Gestión de datos binarios con Artifacts

---

Anterior: ← Function Tools | Siguiente: Browser Tools →