Ferramentas Integradas

ADK-Rust fornece várias ferramentas integradas que estendem as capacidades do agente sem exigir implementação personalizada. Essas ferramentas estão prontas para uso imediato e se integram perfeitamente com o framework de agentes.

Ferramentas nativas do provedor agora são declaradas através do normal Tool API em vez de blobs GenerateContentConfig.extensions específicos do provedor. Isso significa que você pode misturar ferramentas nativas como Gemini Google Search, Anthropic Web Search ou OpenAI Responses web search com instâncias FunctionTool comuns no mesmo agente.

Visão Geral

Ferramenta de Pesquisa Web GoogleSearchTool

GoogleSearchTool permite que os agents pesquisem na web usando o Google Search. Esta ferramenta é tratada internamente pelos modelos Gemini através do recurso de grounding, o que significa que a pesquisa é realizada no lado do servidor pelo próprio 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(())
}

Como Funciona

Ao contrário das function tools regulares, GoogleSearchTool opera de forma diferente:

1. Execução no lado do servidor: A pesquisa é realizada pelo recurso de grounding do Gemini, não localmente
2. Invocação automática: O modelo decide quando pesquisar com base na consulta
3. Resultados integrados: Os resultados da pesquisa são incorporados diretamente na resposta do modelo

A implementação da ferramenta retorna um erro se chamada diretamente porque a pesquisa real acontece dentro do 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"))
}

Detalhes da Ferramenta

Casos de Uso

• Eventos atuais: "O que aconteceu nas notícias hoje?"
• Consultas factuais: "Qual é a população de Tóquio?"
• Informações recentes: "Quais são os últimos desenvolvimentos em IA?"
• Tarefas de pesquisa: "Encontre informações sobre tendências de energia renovável"

Exemplos de Consultas

// 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 envolve qualquer agent como uma ferramenta invocável, permitindo a composição de agents onde um agent pai pode invocar um agent filho como parte de seu fluxo de trabalho de chamada de ferramenta. Mudanças de estado e artefatos do sub-agent são automaticamente encaminhados para o contexto pai.

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

Como Funciona

1. O agent pai decide chamar o agent encapsulado como uma ferramenta
2. AgentTool cria um contexto de invocação com StreamingMode::None
3. O sub-agent executa até a conclusão e acumula sua resposta completa
4. O texto da resposta é retornado ao agent pai
5. Deltas de estado e deltas de artefatos são encaminhados para o contexto pai

Detalhes da Ferramenta

Comportamento Chave

• Sub-agentes são executados em modo não-streaming internamente para captura confiável de respostas
• Mudanças de estado (output_key) do sub-agente se propagam para a sessão pai
• Artefatos salvos pelo sub-agente são encaminhados para o contexto pai
• Veja Sistemas Multi-Agente para mais informações sobre padrões de composição de agentes

ExitLoopTool

ExitLoopTool é uma ferramenta de controle usada com LoopAgent para sinalizar quando um processo iterativo deve terminar. Quando chamada, ela define a flag escalate, fazendo com que o loop seja encerrado.

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(())
}

Como Funciona

1. O agente avalia se deve continuar ou sair
2. Quando pronto para sair, o agente chama exit_loop
3. A ferramenta define actions.escalate = true e actions.skip_summarization = true
4. O LoopAgent detecta a flag de escalonamento e para de iterar

Detalhes da Ferramenta

Melhores Práticas

1. Critérios de saída claros: Defina condições específicas na instrução do agente
2. Sempre defina max_iterations: Evite loops infinitos como medida de segurança
3. Instruções significativas: Ajude o agente a entender quando sair

// 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 que os agentes recuperem artefatos armazenados por nome. Isso é útil quando os agentes precisam acessar arquivos, imagens ou outros dados binários que foram salvos anteriormente.

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(())
}

Detalhes da Ferramenta

Parâmetros

A ferramenta espera um objeto JSON com um array artifact_names:

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

Formato da Resposta

A ferramenta retorna um objeto contendo os artefatos carregados:

{
  "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, você precisa:

1. Um ArtifactService configurado no runner
2. Artefatos previamente salvos no serviço
3. A ferramenta adicionada ao 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 Ferramentas Integradas

Você pode usar múltiplas ferramentas 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(())
}

Criando Ferramentas Integradas Personalizadas

Você pode criar suas próprias ferramentas seguindo o mesmo padrão das ferramentas integradas, implementando a 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" }))
    }
}

Referência 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

• Function Tools - Criando function tools personalizadas
• MCP Tools - Usando servidores MCP como provedores de ferramentas
• Workflow Agents - Usando ExitLoopTool com LoopAgent
• Artifacts - Gerenciando dados binários com artifacts

---

Anterior: ← Function Tools | Próximo: Browser Tools →