Ferramentas Embutidas

ADK-Rust oferece várias ferramentas embutidas que estendem as capacidades do Agent sem exigir implementação personalizada. Essas ferramentas estão prontas para usar e se integram perfeitamente com a estrutura do Agent.

Visão Geral

GoogleSearchTool

GoogleSearchTool permite que Agents pesquisem na web usando o Google Search. Esta ferramenta é gerenciada internamente por 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

Diferente das FunctionTool comuns, a 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 Tool retorna um erro se chamada diretamente porque a pesquisa real acontece dentro da 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()))
}

Detalhes da Tool

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

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 agent avalia se deve continuar ou sair
2. Quando pronto para sair, o agent chama exit_loop
3. A tool define actions.escalate = true e actions.skip_summarization = true
4. O LoopAgent detecta a flag escalate e para de iterar

Detalhes da Tool

Melhores Práticas

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

// Bom: Critérios de saída claros
.instruction(
    "Melhore o texto até que ele:\n\
     - Não tenha erros gramaticais\n\
     - Tenha menos de 100 palavras\n\
     - Use voz ativa\n\
     Quando todos os critérios forem atendidos, chame exit_loop."
)

// Evitar: Critérios vagos
.instruction("Melhore o texto. Saia quando terminar.")

LoadArtifactsTool

LoadArtifactsTool permite que 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 salvos anteriormente no service
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 várias 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 Built-in Personalizadas

Você pode criar suas próprias ferramentas seguindo o mesmo padrão das ferramentas built-in, implementando o 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 da API

GoogleSearchTool

impl GoogleSearchTool {
    /// Cria uma nova instância de GoogleSearchTool
    pub fn new() -> Self;
}

ExitLoopTool

impl ExitLoopTool {
    /// Cria uma nova instância de ExitLoopTool
    pub fn new() -> Self;
}

LoadArtifactsTool

impl LoadArtifactsTool {
    /// Cria uma nova instância de LoadArtifactsTool
    pub fn new() -> Self;
}

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

Relacionado

• Function Tools - Criando ferramentas de função 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 →