Gemini API Tool Retrieval: tool_search, defer_loading e cobrança
Ative o Tool Retrieval em prévia na Gemini Interactions API (v1beta) com tool_search e defer_loading. Compare os modos no servidor e no cliente, confira os quatro modelos documentados em relação ao blog do Google, gerencie MCP remoto e reenvio sem estado, resolva erros comuns e avalie a cobrança de tokens e o cache implícito de prefixo.
Conteúdo

O Tool Retrieval já está em prévia na Gemini Interactions API (v1beta), permitindo que agentes carreguem sob demanda os esquemas de parâmetros de ferramentas com tool_search e defer_loading. Esse recurso atende desenvolvedores que conectam dezenas de funções personalizadas ou servidores MCP remotos ao Gemini e está disponível apenas na Interactions API (não em generateContent). Conforme o estado verificado em 2026-11-20, para testar chame v1beta/interactions com um dos quatro modelos documentados (gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash ou gemini-3.6-flash), inclua {"type": "tool_search"} e defina defer_loading: true nas ferramentas fora do seu conjunto principal.
Escolha primeiro a rota de API correta
O Google anunciou o Tool Retrieval em 19 de novembro de 2026 no blog do Google e publicou o guia de configuração na documentação de Tool retrieval do AI Studio. Como o recurso está restrito à prévia da Interactions API (v1beta), o endpoint que você usa hoje define se é possível adotá-lo de imediato.
| Rota | Conta e região | Unidade de cobrança | Suporte a Tool Retrieval | Quando escolher |
|---|---|---|---|---|
Gemini Interactions API oficial (v1beta) | Chave de API do Google AI Studio em uma região suportada; gemini-4-argon exige Paid Tier | Por 1M de tokens de entrada, em cache e de saída (Standard Free Tier disponível em gemini-4-hydrogen, gemini-3.8-flash e gemini-3.6-flash) | Suportado em prévia (tool_search, defer_loading, mcp_server remoto) | Você tem uma biblioteca grande de ferramentas e pode chamar v1beta/interactions diretamente |
API oficial generateContent do Gemini | Mesma conta do Google AI Studio e região suportada | Por 1M de tokens de entrada, em cache e de saída | Não suportado | Você tem menos de ~20 ferramentas estáveis, precisa de cache explícito em modelos Gemini 3 ou 2.5 suportados ou ainda não pode migrar |
| Gateway de API com pagamento conforme o uso (como o BetterToken) | Conta própria do BetterToken registrada por você e chave de API criada no console | Saldo pago conforme o uso, cobrado pela unidade de cobrança vigente de cada modelo | A Interactions API não é documentada; o suporte a Tool Retrieval não está verificado | Você permanece nos endpoints documentados de Gemini nativo generateContent ou Chat Completions compatível com OpenAI em vários modelos (confira o suporte de ferramentas por modelo na documentação do BetterToken) |
Se você preferir continuar no endpoint padrão generateContent do Gemini ou em Chat Completions compatível com OpenAI em vez de migrar para a Interactions API, vale consultar a referência da API Gemini no BetterToken para verificar os endpoints documentados, os IDs de modelo e o suporte a ferramentas por modelo.
Modelos suportados e o erro 400 no Gemini 4
O texto de anúncio do Google de 19 de novembro de 2026 afirma que o Tool Retrieval funciona com o Gemini 3.6 e modelos posteriores, incluindo todos os modelos Gemini 4, com link para a página de modelos Gemini mais recentes. Essa página lista quatro modelos Gemini 4: gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen e gemini-4-argon.
Conforme verificado em 2026-11-20, porém, a lista oficial de modelos suportados pelo Tool retrieval traz apenas quatro IDs de modelo:
gemini-4-hydrogengemini-4-argongemini-3.8-flashgemini-3.6-flash
gemini-4-carbon e gemini-4-neon não constam na página de documentação do Tool Retrieval conforme verificado em 2026-11-20. Enviar defer_loading para um modelo sem suporte retorna um erro HTTP 400 com a mensagem deferred loading is not supported for this model.
Comece sua integração com gemini-4-hydrogen, modelo usado pelo Google nos exemplos do Tool Retrieval; consulte nosso guia de preços e migração do Gemini 4 Hydrogen se você estiver saindo dos modelos Flash. Se o seu fluxo depende do gemini-4-carbon, valide o comportamento real em v1beta antes de ativar defer_loading, ou revise preços e migração da API Gemini 4 Carbon mantendo o carregamento estático das ferramentas.
Recuperação no servidor vs. no cliente
A Interactions API oferece dois modos de recuperação mutuamente exclusivos: recuperação no servidor (padrão) e recuperação no cliente (execution: "client"). Ambos mantêm os esquemas fora do prompt inicial, mas diferem em latência, configuração e cadastro das ferramentas.
| Critério | Carregamento estático de ferramentas | Recuperação no servidor | Recuperação no cliente |
|---|---|---|---|
| Como os esquemas chegam ao modelo | Todos enviados no início | O Gemini carrega os esquemas adiados sob demanda | Sua aplicação retorna os esquemas em function_result |
| Código de busca a escrever | Nenhum | Nenhum | Busca, ordenação e filtragem próprias |
| Ferramentas declaradas no início | Sim | Sim | Não |
| Suporte a MCP remoto | Sim | Sim (defer_loading: true em mcp_server) | Não se aplica |
| Ida e volta extra pela rede | Nenhuma | Nenhuma. A busca faz uma chamada adicional ao modelo na mesma requisição. | Uma ida e volta pela rede por busca |
| Melhor cenário | Menos de ~20 ferramentas estáveis | Bibliotecas grandes e fixas ou múltiplos servidores MCP | Registros proprietários, permissões por usuário, ferramentas dinâmicas no meio da sessão |
Você pode declarar apenas uma entrada tool_search por requisição. Combinar entradas tool_search de servidor e de cliente na mesma requisição retorna o erro Cannot specify both client-side and server-side tool_search tools..
Configure a recuperação no servidor e MCP remoto
A recuperação no servidor exige a versão v1beta da API. Embora o trecho publicado no blog do Google omita api_version, o guia oficial de Tool retrieval determina que a prévia exige v1beta: em Python, inicialize genai.Client(http_options={"api_version": "v1beta"}); em JavaScript, inicialize new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }).
No Bash, carregue sua chave de API do Gemini sem exibi-la no terminal e envie uma requisição POST para https://generativelanguage.googleapis.com/v1beta/interactions. O exemplo abaixo combina uma função local adiada (convert_currency) com o servidor MCP de clima documentado pelo Google para demonstração (https://gemini-api-demos.uc.r.appspot.com/mcp):
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-hydrogen",
"input": "Check the temperature in London and convert 100 USD to EUR.",
"tools": [
{"type": "tool_search"},
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount from one currency to another using live mid-market rates.",
"short_description": "Convert an amount between currencies.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"from": {"type": "string"},
"to": {"type": "string"}
},
"required": ["amount", "from", "to"]
}
},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": true
}
]
}'
Siga quatro regras ao montar o array tools:
- Omita os campos
name,descriptioneparametersno objetotool_searchdo modo servidor. - Envie o esquema
parameterscompleto em cadafunctionadiada. Os esquemas de parâmetros ainda não carregados pelo modelo não são cobrados, e uma ferramenta enviada sem parâmetros retorna de uma busca com um esquema vazio que o modelo não consegue chamar. - Use o campo opcional
short_descriptionsomente junto comdefer_loading: truepara substituir umadescriptionlonga na lista compacta de ferramentas adiadas. - Para servidores MCP remotos, conecte apenas endpoints Streamable HTTP (servidores SSE não são suportados) e use nomes em
snake_casesem-, conforme documentado em Remote MCP. Se o servidor remoto falhar no handshake ou na validação de esquema, consulte nosso guia de solução de problemas na integração com servidores MCP.
Verifique a resposta do lado do servidor
Uma resposta bem-sucedida de recuperação no servidor traz as etapas tool_search_call e tool_search_result dentro de steps na mesma chamada de API, seguidas pela chamada real da ferramenta. No caso de ferramentas MCP remotas como get_weather no servidor de demonstração, a API também executa a chamada remota e retorna as etapas mcp_server_tool_call e mcp_server_tool_result na mesma resposta.
Para as suas próprias funções, procure itens function_call diretamente dentro de steps. Não dependa apenas de status == "requires_action", porque o Google informa que status nem sempre assume requires_action quando uma etapa function_call está presente. Execute a função localmente e envie um function_result no próximo turno.
Configure a recuperação no cliente
Use execution: "client" quando o catálogo de ferramentas depende de permissões do usuário, namespaces internos ou integrações adicionadas após o início da sessão. Tanto name quanto description são obrigatórios na definição de um tool_search no cliente (omitir qualquer um retorna erro 400), e você não deve definir defer_loading em nenhuma ferramenta da requisição.
O trecho em Python abaixo é um exemplo mínimo de protocolo que retorna uma declaração fixa em vez de consultar um registro ativo. Confirme que a ida e volta pela rede funciona quando o script imprimir uma etapa function_call para get_billing_history com {"user_id": 123} a partir de followup.steps:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
{
"type": "tool_search",
"execution": "client",
"name": "search_tool_registry",
"description": "Search internal tool namespaces such as billing and support when needed.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"namespace": {"type": "string"},
},
"required": ["query"],
},
}
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Look up the billing history for user 123.",
tools=tools,
)
for step in interaction.steps:
if step.type == "function_call" and step.name == "search_tool_registry":
# Minimal protocol example: replace with your own registry or permission filter.
matches = [
{
"type": "function",
"name": "get_billing_history",
"description": "Retrieve billing history for a given user.",
"parameters": {
"type": "object",
"properties": {"user_id": {"type": "integer"}},
"required": ["user_id"],
},
}
]
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[
{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": matches,
}
],
)
for next_step in followup.steps:
if next_step.type == "function_call":
print(next_step.name, next_step.arguments)
Retorne declarações completas de funções como objetos JSON dentro do array function_result.result, nunca como uma string JSON serializada, e inclua os valores name e call_id correspondentes à function_call de busca. Se a busca no cliente não encontrar correspondência, retorne um texto curto informando que nada foi encontrado e listando o que o modelo pode buscar para ajustar a consulta.
Estado multiturno, reenvio sem estado e erros comuns
Três restrições da prévia causam a maior parte das falhas de integração após o primeiro turno:
- Reenvie o array
toolscompleto em cada requisição. A Interactions API armazena o histórico de etapas quando você passaprevious_interaction_id, mas não guarda declarações de ferramentas entre requisições. Omitir ferramentas em turnos seguintes faz o modelo ignorar ferramentas não declaradas ou emitir chamadas internasretriever:no modo servidor. - Ferramentas carregadas não podem ser descarregadas e buscas sem resultado retornam texto. Depois que o modelo carrega uma ferramenta, o esquema dela permanece no contexto pelo restante da conversa. Se uma consulta no servidor não corresponder a nenhuma ferramenta adiada, a API retorna texto simples em vez de um erro estruturado de recuperação, então não use
tool_search_resultpara detectar ausências. - Reenvie etapas e assinaturas sem alterações quando
store=false. Em cada continuação sem estado, passe o histórico completo de etapas eminpute reenvie o arraytoolscompleto no nível superior da requisição. Anexe cada etapa da resposta (tool_search_call,tool_search_result,thoughtefunction_call) sem modificações, na ordem original e com asignatureintacta, seguida pelo novofunction_result. Enviar apenasfunction_resultdescarta o contexto de recuperação e gera erro400. Use uma versão do SDK que reconheçatool_search_calletool_search_result, pois versões antigas os tratam como etapas desconhecidas e removem seus campos. Mantenha sem adiamento qualquer ferramenta citada pelo nome nas instruções do sistema ou na saída de outra ferramenta, caso contrário o modelo pode chamá-la sem buscar e falhar ao processarfunction_result.
O Google documenta respostas HTTP 400 para modelos não suportados, ausência de tool_search no servidor ao usar defer_loading, uso de short_description sem defer_loading: true, omissão de name ou description no modo cliente, etapas sem estado ausentes e valores signature removidos. Use a tabela abaixo para relacionar cada mensagem documentada à sua causa e correção:
| Mensagem de erro documentada | Causa | Correção |
|---|---|---|
deferred loading is not supported for this model | defer_loading enviado para um modelo fora da lista suportada | Troque para gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash ou gemini-3.6-flash |
tool_search tool must be specified when using defer_loading. | Uma ferramenta function ou mcp_server define defer_loading: true sem nenhuma ferramenta tool_search na requisição | Adicione {"type": "tool_search"} ou remova defer_loading |
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request. | Uma função define defer_loading: true sem um tool_search no servidor (por exemplo, apenas execution: "client" foi declarado ou uma requisição seguinte omitiu tool_search) | Remova defer_loading no modo cliente ou reenvie o array tools completo incluindo {"type": "tool_search"} |
Cannot specify both client-side and server-side tool_search tools. | A requisição inclui tanto um tool_search no servidor quanto um no cliente | Declare exatamente uma entrada tool_search por requisição |
ToolSearch name must not be specified when execution mode is SERVER_SIDE. | Um tool_search no servidor define name (o mesmo erro ocorre para description e parameters) | Remova o campo; ao mudar para execution: "client", forneça tanto name quanto description e remova defer_loading de todas as ferramentas |
short_description can only be set if defer_loading is true | Uma função define short_description sem defer_loading: true | Adicione defer_loading: true ou remova short_description |
Server side tool call context must be circulated when using deferred loading functions. | Em uma requisição sem estado, o histórico inclui function_result para uma ferramenta adiada sem as etapas tool_search_call e tool_search_result que a carregaram | Reenvie sem alterações cada etapa tool_search_call e tool_search_result, incluindo signature |
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME (mesmo reenviando todas as etapas) | O modelo chamou uma função adiada que nenhum tool_search carregou, geralmente porque o nome dela apareceu nas instruções do sistema ou na saída de outra ferramenta | Mantenha sem adiamento as ferramentas citadas pelo nome |
Tool call part is missing thought_signature. / Tool response part is missing thought_signature. | Em uma requisição sem estado, uma etapa tool_search_call (chamada) ou tool_search_result (resposta) foi reenviada sem o campo signature | Reenvie ambas as etapas de recuperação sem alterações e com os valores de signature intactos |
Campos de cobrança, cache de prefixo e ponto de equilíbrio
O Tool Retrieval em si não possui taxa separada. Cada token é cobrado pelas tarifas padrão de entrada, cache e saída do modelo chamado, publicadas na página de preços da Gemini API. Conforme as tarifas verificadas em 2026-11-20, o gemini-4-hydrogen custa $1.50 por 1M de tokens de entrada, $0.075 por 1M de tokens de entrada em cache e $7.50 por 1M de tokens de saída (incluindo tokens de pensamento) no Paid Tier. O acesso Standard Free Tier está disponível para gemini-4-hydrogen, gemini-3.8-flash e gemini-3.6-flash, enquanto o gemini-4-argon existe apenas no Paid Tier por $2.00 de entrada, $0.10 em cache e $10.00 de saída por 1M de tokens até 30 de novembro de 2026, passando para $4.00 / $0.20 / $20.00 a partir de 1º de dezembro de 2026.
Verifique cinco campos em usage em cada resposta de interação para acompanhar o consumo de tokens:
total_input_tokens: o prompt da primeira chamada ao modelo na requisição, incluindo sua entrada, o histórico da conversa, instruções do sistema, esquemas de ferramentas não adiadas, o pequeno bloco fixo de instruções detool_searche entradas de uma linha para ferramentas adiadas (namemaisshort_descriptionou a primeira frase dedescription, cerca de 26 tokens por ferramenta adiada nos testes iniciais do Google).total_tool_use_tokens: os prompts de cada chamada adicional ao modelo que a API executa dentro da mesma requisição após rodar uma ferramenta no servidor, incluindo cada busca no servidor. Cada chamada adicional ao modelo reenvia todo o contexto mais os esquemas recém-carregados e é cobrada na tarifa de entrada; várias buscas no mesmo turno acrescentam várias chamadas adicionais ao modelo.total_cached_tokens: a parcela do prompt atendida pelo cache implícito, cobrada na tarifa de cache em vez da tarifa de entrada.total_output_tokens: tokens de resposta gerados, cobrados na tarifa de saída.total_thought_tokens: tokens de pensamento gerados, cobrados na tarifa de saída.
Ressalva sobre o limite do cache de prefixo
A Interactions API suporta apenas cache implícito; o cache explícito não está disponível na Interactions API nem nos modelos Gemini 4, conforme Context caching. Como os esquemas recuperados são inseridos no ponto em que o modelo os carrega e não no início do prompt, suas instruções do sistema, a lista de ferramentas e os turnos anteriores formam um prefixo inalterado entre turnos. Assim que esse prefixo ultrapassa o tamanho mínimo armazenável em cache do modelo, requisições seguintes na conversa, incluindo a chamada adicional ao modelo feita por cada busca no servidor, podem ser atendidas pelo cache implícito e aparecer em total_cached_tokens.
Conforme verificado em 2026-11-20, porém, todos os quatro modelos suportados pelo Tool Retrieval exigem um mínimo de 4,096 tokens de entrada para o cache implícito. Se o seu prompt só superava 4,096 tokens por causa dos esquemas completos das ferramentas, adiar essas ferramentas pode deixar a requisição abaixo do tamanho mínimo para cache. Em loops multiturno e de agentes com modelos Gemini 4, o Gemini armazena em cache a requisição anterior completa apenas se a nova requisição acrescentar pelo menos 2,050 tokens (saída do modelo, pensamento e resultados de funções entram nessa conta); em acréscimos menores, o Gemini reprocessa os últimos 2,050 tokens da requisição anterior na tarifa padrão de entrada.
Quando o Tool Retrieval economiza tokens e quando custa mais
A documentação do Google apresenta uma estimativa ilustrativa de duas requisições (números arredondados, sem incluir tokens de saída nem cache) em que o modelo carrega duas ferramentas de 400 tokens e retorna um function_call na resposta da requisição 1, seguido pelo envio de function_result pela sua aplicação na requisição 2:
| Cenário ilustrativo (estimativa da documentação do Google) | Carregamento estático (tokens de entrada) | Tool retrieval (tokens de entrada + uso de ferramentas) | Resultado líquido |
|---|---|---|---|
| 200 ferramentas (400 tokens cada), contexto de 2,000 tokens | 2 × (2,000 + 80,000) = 164,000 | Requisição 1: 7,350 + chamada adicional ao modelo 8,150; Requisição 2: 8,150 = ~23,650 | Economiza ~86% dos tokens do lado de entrada |
| 10 ferramentas (400 tokens cada), contexto de 30,000 tokens | 2 × (30,000 + 4,000) = 68,000 | Requisição 1: 30,410 + chamada adicional ao modelo 31,210; Requisição 2: 31,210 = ~92,830 | Custa ~37% a mais em tokens do lado de entrada |
Adiar ferramentas compensa quando sua biblioteca é grande e a maioria dos turnos aciona poucas funções. Com um conjunto pequeno de ferramentas ou uma conversa longa que faz buscas em quase todo turno, a chamada adicional ao modelo feita pela busca no servidor (total_tool_use_tokens) pode superar a economia. Mantenha carregadas desde o início as ferramentas de uso mais frequente, adie a cauda longa e meça total_input_tokens, total_tool_use_tokens e total_cached_tokens no seu próprio tráfego junto com o valor efetivamente faturado antes de expandir o uso.