Ferramentas integradas

ADK-Rust fornece várias ferramentas integradas que ampliam os recursos dos agentes sem exigir uma implementação personalizada. Essas ferramentas estão prontas para uso e se integram perfeitamente à estrutura de agentes.

As ferramentas nativas do provedor agora são declaradas por meio do Tool API normal, em vez de estruturas GenerateContentConfig.extensions específicas do provedor. Isso significa que você pode combinar ferramentas nativas, como a Pesquisa do Google do Gemini, a Pesquisa na Web da Anthropic ou a pesquisa na web de Responses do OpenAI, com instâncias comuns de FunctionTool no mesmo agente.

Visão geral

GoogleSearchTool

GoogleSearchTool permite que os agentes pesquisem na web usando o Google Search. Essa ferramenta é processada internamente pelos modelos Gemini por meio 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-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(())
}

Como funciona

Diferentemente das ferramentas de função comuns, GoogleSearchTool funciona de outra forma:

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 à resposta do modelo

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

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 desenvolvimentos mais recentes em IA?"
• Tarefas de pesquisa: "Encontre informações sobre as tendências de energia renovável"

Consultas de exemplo

// 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 encapsula qualquer agente como uma ferramenta chamável, permitindo a composição de delegação e retorno: o chamador invoca um agente filho, recebe o resultado e, em seguida, retoma a execução. Os deltas de estado e artefatos emitidos pelo agente filho são mesclados ao evento da ferramenta pai. A sessão filha também aplica cada evento imediatamente, para que as etapas posteriores em um fluxo de trabalho delegado vejam as alterações anteriores de estado e histórico.

Os padrões legados permanecem isolados e compatíveis com versões anteriores. Equipes portáteis optam pelo uso de instantâneos do histórico/estado do pai, encaminhamento de memória, falhas propagadas, profundidade finita de delegação, projeções exatas de estado/histórico e execução interna de transferências filhas registradas. Uma transferência filha consumida permanece visível como um evento, mas sua ação de transferência é removida antes do encaminhamento, para que o Runner pai não possa executá-la duas vezes. Os metadados da solicitação, o cancelamento, os escopos, os segredos, os artefatos e o estado compartilhado paralelo seguem a política de encaminhamento configurada. O próprio AgentTool não executa o loop global de transferências do Runner; um TeamSpec compilado fornece o registro exato de transferências aninhadas para topologias mistas. As equipes compiladas também optam pelo encaminhamento de eventos aninhados, para que a atividade delegada permaneça visível no fluxo de eventos pai; o AgentTool independente mantém a saída de eventos legada, a menos que forward_events(true) seja selecionado.

Para write-back controlado, use output_state_keys independentemente da projeção de entrada state_keys. state_merge_policy(RejectConflicts) compara o valor atual do pai com o snapshot obtido quando a delegação começou e rejeita gravações conflitantes atomicamente. artifact_prefixes aplica o mesmo princípio de allowlist aos nomes de artefatos. Os padrões independentes continuam usando a política de último gravador vence, com saída irrestrita para compatibilidade retroativa; equipes compiladas optam pela política exata de suas arestas.

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 agente pai decide chamar o agente encapsulado como uma ferramenta
2. AgentTool cria um contexto de invocação com StreamingMode::None
3. O subagente é executado até a conclusão e acumula sua resposta completa
4. O texto da resposta é retornado ao agente pai
5. Os deltas de estado e de artefatos são encaminhados ao contexto pai

Detalhes da ferramenta

Comportamento principal

• Subagentes são executados internamente no modo não streaming para uma captura confiável da resposta
• Alterações de estado (output_key) do subagente são propagadas para a sessão pai
• Artefatos salvos pelo subagente são encaminhados para o contexto pai
• Consulte Sistemas multiagente para saber mais sobre padrões de composição de agentes

ExitLoopTool

ExitLoopTool é uma ferramenta de controle usada com LoopAgent para sinalizar quando um processo iterativo deve ser encerrado. Quando chamada, ela define o sinalizador 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-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(())
}

Como funciona

1. O agente avalia se deve continuar ou sair
2. Quando está pronto para sair, o agente chama exit_loop
3. A ferramenta define actions.escalate = true e actions.skip_summarization = true
4. O LoopAgent detecta o sinalizador de escalonamento e interrompe a iteração

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

Detalhes da ferramenta

Parâmetros

A ferramenta espera um objeto JSON com uma matriz 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 de:

1. Um ArtifactService configurado no executor
2. Artefatos salvos anteriormente no serviço
3. A ferramenta adicionada ao 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);

Combinação de ferramentas integradas

Você pode usar várias ferramentas integradas em conjunto:

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

Criação de ferramentas integradas personalizadas

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

Relacionados

• Ferramentas de função - Criando ferramentas de função personalizadas
• Ferramentas MCP - Usando servidores MCP como provedores de ferramentas
• Agentes de fluxo de trabalho - Usando ExitLoopTool com LoopAgent
• Artefatos - Gerenciando dados binários com artefatos

---

Anterior: ← Ferramentas de função | Próximo: Ferramentas de navegador →