Herramientas integradas

ADK-Rust proporciona varias herramientas integradas que amplían las capacidades de los agentes sin requerir una implementación personalizada. Estas herramientas están listas para usarse de inmediato y se integran perfectamente con el marco de agentes.

Las herramientas nativas del proveedor ahora se declaran mediante el API Tool habitual en lugar de 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 Responses de OpenAI con instancias FunctionTool normales en el mismo agente.

Descripción general

GoogleSearchTool

GoogleSearchTool permite a los agentes buscar en la web mediante Google Search. Esta herramienta es gestionada internamente por los modelos Gemini mediante la función de grounding, lo que significa que la búsqueda la realiza el propio modelo en el servidor.

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-3.7-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 funciones habituales, GoogleSearchTool funciona de otra manera:

1. Ejecución en el servidor: la búsqueda la realiza la función 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 búsqueda se incorporan directamente a la respuesta del modelo

La implementación de la herramienta devuelve un error si se invoca directamente, porque la búsqueda real se realiza dentro de API de Gemini:

// 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 herramienta

Casos de uso

• Acontecimientos actuales: "¿Qué ha sucedido hoy en las noticias?"
• Consultas fácticas: "¿Cuál es la población de Tokio?"
• Información reciente: "¿Cuáles son los últimos avances en IA?"
• Tareas de investigación: "Encuentra información sobre las tendencias de la 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 agente como una herramienta invocable, lo que permite una composición de delegación y retorno: el invocador llama a un agente secundario, recibe su resultado y luego reanuda la ejecución. Los cambios de estado y artefactos emitidos por el agente secundario se combinan con el evento de herramienta del agente principal. La sesión secundaria también aplica cada evento inmediatamente, por lo que los pasos posteriores de un flujo de trabajo delegado ven los cambios anteriores en el estado y el historial.

Los valores predeterminados heredados permanecen aislados y son compatibles con versiones anteriores. Los equipos portátiles optan explícitamente por instantáneas del historial y el estado del agente principal, el reenvío de memoria, los errores propagados, una profundidad de delegación finita, proyecciones exactas del estado y el historial, y la ejecución interna de las transferencias registradas de agentes secundarios. Una transferencia consumida de un agente secundario permanece visible como evento, pero su acción de transferencia se elimina antes del reenvío, de modo que el Runner del agente principal no puede ejecutarla dos veces. Los metadatos de la solicitud, la cancelación, los ámbitos, los secretos, los artefactos y el estado compartido en paralelo siguen la política de reenvío configurada. AgentTool por sí mismo no ejecuta el bucle global de transferencias del Runner; un TeamSpec compilado proporciona el registro exacto de transferencias anidadas para topologías mixtas. Los equipos compilados también optan explícitamente por el reenvío de eventos anidados, de modo que la actividad delegada permanezca visible en el flujo de eventos del agente principal; AgentTool independiente conserva el resultado de eventos heredado, a menos que se seleccione forward_events(true).

Para la escritura controlada de vuelta, usa output_state_keys independientemente de la proyección de entrada state_keys. state_merge_policy(RejectConflicts) compara el valor actual del elemento principal con la instantánea tomada cuando comenzó la delegación y rechaza atómicamente las escrituras en conflicto. artifact_prefixes aplica el mismo principio de lista de permitidos a los nombres de artefactos. Los valores predeterminados independientes siguen aplicando la regla de que gana el último escritor, con salida sin restricciones por compatibilidad con versiones anteriores; los equipos compilados optan por su política de aristas exacta.

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 principal decide llamar al agente envuelto como una herramienta
2. AgentTool crea un contexto de invocación con StreamingMode::None
3. El subagente se ejecuta hasta completarse y acumula su respuesta completa
4. El texto de la respuesta se devuelve al agente principal
5. Los deltas de estado y los deltas de artefactos se reenvían al contexto principal

Detalles de la herramienta

Comportamiento clave

• Los subagentes se ejecutan internamente en modo no streaming para capturar respuestas de forma fiable
• Los cambios de estado (output_key) del subagente se propagan a la sesión principal
• Los artefactos guardados por el subagente se reenvían al contexto principal
• Consulta Sistemas multiagente para obtener más información sobre los patrones de composición de agentes

ExitLoopTool

ExitLoopTool es una herramienta de control que se utiliza con LoopAgent para indicar cuándo debe finalizar un proceso iterativo. Cuando se invoca, establece la marca escalate, lo que hace que el bucle finalice.

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-3.7-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 debe continuar o salir
2. Cuando está listo para salir, el agente invoca exit_loop
3. La herramienta establece actions.escalate = true y actions.skip_summarization = true
4. LoopAgent detecta la marca de escalación 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. Establece siempre max_iterations: Evita bucles infinitos como medida de seguridad
3. Instrucciones significativas: Ayuda al agente a comprender 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 resulta útil cuando los agentes necesitan acceder a archivos, imágenes u otros datos binarios 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-3.7-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 arreglo 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 ejecutor
2. Artefactos guardados previamente en el servicio
3. La herramienta añadida al agente

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

Combinación de 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-3.7-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(())
}

Creación de herramientas integradas personalizadas

Puedes crear tus propias herramientas siguiendo el mismo patrón que las herramientas integradas mediante la implementación del 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> {
        // Your tool logic here
        Ok(json!({ "result": "success" }))
    }
}

Referencia de 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 de 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 de navegador →