O Gemini API passou a oferecer Tool Retrieval em prévia: um mecanismo para agentes de IA consultarem uma biblioteca grande de ferramentas e carregarem o esquema completo apenas quando precisarem dele. Na prática, a proposta ataca um gargalo comum em integrações com muitas funções ou servidores MCP: enviar dezenas — às vezes centenas — de declarações de ferramentas em todas as chamadas, consumindo contexto e tornando a escolha do modelo menos precisa.

O recurso está disponível apenas na Interactions API, requer a versão v1beta e continua marcado como preview. Portanto, é uma opção para prototipagem e para arquiteturas que aceitam mudanças de superfície antes da disponibilidade geral; não é uma troca transparente para quem usa somente generateContent.

Resumo: o que muda para agentes com muitas ferramentas

  • O desenvolvedor declara a biblioteca de ferramentas, mas pode marcar as menos usadas com defer_loading: true.
  • O Gemini recebe inicialmente o nome e a descrição das ferramentas adiadas, não todos os parâmetros.
  • Quando identifica uma necessidade, o modelo pesquisa a biblioteca, carrega o esquema necessário e então emite a chamada da função.
  • Há dois modos: recuperação no servidor do Google, sem lógica adicional no app, e recuperação no cliente, na qual a própria aplicação encontra e devolve os esquemas.
  • O recurso foi desenhado para bibliotecas grandes, inclusive cenários com servidores MCP; para poucas ferramentas estáveis, enviar os esquemas normalmente pode continuar mais simples.

Por que bibliotecas extensas de ferramentas viraram um problema

Agentes modernos raramente operam com uma única API. Um assistente corporativo pode ter conectores de CRM, faturamento, agenda, busca interna, base de conhecimento, suporte, deploy, observabilidade e automação. Cada função normalmente leva nome, descrição, tipos de parâmetros, campos obrigatórios e restrições. Repetir esse catálogo inteiro em cada turno ocupa tokens de entrada e dá ao modelo uma lista de candidatos maior do que a tarefa exige.

A documentação do Google explica que algumas dezenas de declarações podem consumir dezenas de milhares de tokens por requisição e que a precisão de seleção tende a cair à medida que a lista cresce. Tool Retrieval separa a descoberta da ferramenta do uso dela: o modelo primeiro localiza as funções pertinentes e só então recebe os detalhes para chamá-las.

Como o Tool Retrieval funciona

Modo no servidor: menos código na aplicação

No modo padrão, o aplicativo inclui um objeto tool_search na matriz tools e marca ferramentas postergadas com defer_loading: true. O Gemini pesquisa essas ferramentas dentro da própria solicitação, resolve a seleção e retorna a chamada que o aplicativo deve executar. Segundo a documentação, as etapas internas de busca aparecem como tool_search_call e tool_search_result, seguidas de function_call.

from google import genai

# v1beta é obrigatório porque o recurso ainda está em preview.
client = genai.Client(http_options={"api_version": "v1beta"})

tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "crm_buscar_cliente",
        "description": "Busca dados de um cliente pelo e-mail.",
        # Evita mandar o esquema completo em todo turno.
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {"email": {"type": "string"}},
            "required": ["email"],
        },
    },
]

resposta = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Localize o cadastro de [email protected].",
    tools=tools,
)

O exemplo mostra a ideia central, não uma integração completa. A função crm_buscar_cliente ainda precisa existir no aplicativo, validar autorização e executar a consulta de forma segura. Tool Retrieval ajuda a escolher e carregar a descrição da ferramenta; ele não delega para o modelo o controle de acesso nem a execução de operações externas.

Modo no cliente: indicado para catálogos dinâmicos

Também existe recuperação no cliente. Nesse caso, a aplicação declara uma ferramenta de busca com execution: "client", recebe a consulta do modelo, aplica sua própria busca, ranking e filtragem e devolve as declarações que combinam com o pedido. Esse caminho é útil quando o catálogo varia por cliente, namespace, permissão ou sessão. Em contrapartida, acrescenta uma ida e volta à conversa e exige que o produto mantenha sua lógica de recuperação.

EstratégiaComo o modelo recebe ferramentasQuando faz mais sentido
Carregamento estáticoTodos os esquemas em cada requisiçãoMenos de 20 ferramentas estáveis
Recuperação no servidorGemini carrega esquemas adiados dentro da chamadaBiblioteca conhecida e grande, com prioridade para latência
Recuperação no clienteO app devolve esquemas sob demandaFerramentas dinâmicas, por usuário ou por namespace
Comparação baseada na documentação do Tool Retrieval do Gemini API.

Limitações que mudam a decisão técnica

Há limites explícitos. Tool Retrieval funciona somente na Interactions API e não é compatível com generateContent. A documentação informa que recuperação no servidor e no cliente não podem ser combinadas na mesma requisição; defer_loading vale somente no fluxo do servidor; e ferramentas já carregadas permanecem no contexto pelo restante da conversa, sem mecanismo para descarregá-las.

Em conversas sem estado, o integrador precisa reenviar o histórico completo. Se houver recuperação de ferramentas, isso inclui as etapas tool_search_call e tool_search_result com seus campos signature preservados. Omitir ou alterar essas etapas pode gerar erro 400. Para fluxos persistentes, também é necessário reenviar a matriz tools em cada chamada: as declarações não são armazenadas automaticamente na interação.

O suporte também não é universal. A página de referência lista Gemini 4 Carbon, Neon, Hydrogen e Argon, além de Gemini 3.8 Flash e 3.6 Flash. Antes de migrar um agente existente, a equipe deve conferir o modelo efetivamente usado, a versão do SDK e a rota de API.

Segurança: reduzir contexto não substitui controle de acesso

Um erro comum em projetos de agentes é confundir seleção de ferramenta com autorização. Uma descrição bem escrita pode ajudar o modelo a encontrar financeiro_emitir_reembolso, mas não deve autorizar essa operação. A aplicação precisa validar identidade, escopo, dados de entrada, limites financeiros e confirmação humana quando houver efeito irreversível.

Também vale manter as ferramentas mais frequentes carregadas e não adiar funções citadas nominalmente em instruções de sistema ou nas saídas de ferramentas. A recomendação do Google é usar nomes com prefixo de serviço — por exemplo, billing_get_customer e crm_get_customer — para reduzir ambiguidades. Isso melhora a recuperação, mas não elimina testes de avaliação: cada catálogo precisa ser testado com pedidos reais, negações de permissão e casos ambíguos.

Onde o recurso pode ser útil

  • Agentes internos: um assistente que acessa RH, suporte e CRM sem carregar todo o catálogo em cada pergunta.
  • Servidores MCP extensos: ambientes que conectam múltiplos serviços e precisam impedir que uma longa lista de schemas domine o contexto.
  • Plataformas multiempresa: recuperação no cliente pode devolver somente funções permitidas para o tenant e o papel atual.
  • Automação de desenvolvedores: agentes que alternam entre repositório, CI/CD, observabilidade e incidentes, mas usam uma fração dessas integrações por tarefa.

Análise do NoticIA: uma peça de infraestrutura, não um atalho para agentes confiáveis

Na análise do NoticIA, a relevância do Tool Retrieval está menos em “dar mais ferramentas” ao modelo e mais em tornar catálogos grandes administráveis. O custo e a qualidade da seleção passam a depender de como cada ferramenta é nomeada, descrita, agrupada e autorizada. Para equipes com poucos conectores, a complexidade adicional provavelmente não se paga. Para plataformas com dezenas de integrações e agentes especializados, a separação entre descoberta e esquema pode reduzir desperdício de contexto e facilitar a evolução do catálogo.

Como o recurso está em preview, a recomendação é iniciar com uma avaliação controlada: medir tokens de entrada, taxa de escolha correta, latência e falhas de recuperação; manter caminhos críticos com validação determinística; e evitar prometer estabilidade de produção antes de a API sair da fase beta. O ganho potencial é real, mas depende mais da arquitetura do agente e da governança das ferramentas do que de uma única flag.



Descubra mais sobre noticiAI

Assine para receber nossas notícias mais recentes por e-mail.

Deixe seu comentário