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
Gemini API Tool Retrieval: tool_search, defer_loading e cobrança

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.

RotaConta e regiãoUnidade de cobrançaSuporte a Tool RetrievalQuando escolher
Gemini Interactions API oficial (v1beta)Chave de API do Google AI Studio em uma região suportada; gemini-4-argon exige Paid TierPor 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 GeminiMesma conta do Google AI Studio e região suportadaPor 1M de tokens de entrada, em cache e de saídaNão suportadoVocê 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 consoleSaldo pago conforme o uso, cobrado pela unidade de cobrança vigente de cada modeloA Interactions API não é documentada; o suporte a Tool Retrieval não está verificadoVocê 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-hydrogen
  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-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érioCarregamento estático de ferramentasRecuperação no servidorRecuperação no cliente
Como os esquemas chegam ao modeloTodos enviados no inícioO Gemini carrega os esquemas adiados sob demandaSua aplicação retorna os esquemas em function_result
Código de busca a escreverNenhumNenhumBusca, ordenação e filtragem próprias
Ferramentas declaradas no inícioSimSimNão
Suporte a MCP remotoSimSim (defer_loading: true em mcp_server)Não se aplica
Ida e volta extra pela redeNenhumaNenhuma. A busca faz uma chamada adicional ao modelo na mesma requisição.Uma ida e volta pela rede por busca
Melhor cenárioMenos de ~20 ferramentas estáveisBibliotecas grandes e fixas ou múltiplos servidores MCPRegistros 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, description e parameters no objeto tool_search do modo servidor.
  • Envie o esquema parameters completo em cada function adiada. 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_description somente junto com defer_loading: true para substituir uma description longa 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_case sem -, 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 tools completo em cada requisição. A Interactions API armazena o histórico de etapas quando você passa previous_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 internas retriever: 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_result para 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 em input e reenvie o array tools completo no nível superior da requisição. Anexe cada etapa da resposta (tool_search_call, tool_search_result, thought e function_call) sem modificações, na ordem original e com a signature intacta, seguida pelo novo function_result. Enviar apenas function_result descarta o contexto de recuperação e gera erro 400. Use uma versão do SDK que reconheça tool_search_call e tool_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 processar function_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 documentadaCausaCorreção
deferred loading is not supported for this modeldefer_loading enviado para um modelo fora da lista suportadaTroque 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çãoAdicione {"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 clienteDeclare 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 trueUma função define short_description sem defer_loading: trueAdicione 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 carregaramReenvie 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 ferramentaMantenha 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 signatureReenvie 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 de tool_search e entradas de uma linha para ferramentas adiadas (name mais short_description ou a primeira frase de description, 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 tokens2 × (2,000 + 80,000) = 164,000Requisição 1: 7,350 + chamada adicional ao modelo 8,150; Requisição 2: 8,150 = ~23,650Economiza ~86% dos tokens do lado de entrada
10 ferramentas (400 tokens cada), contexto de 30,000 tokens2 × (30,000 + 4,000) = 68,000Requisição 1: 30,410 + chamada adicional ao modelo 31,210; Requisição 2: 31,210 = ~92,830Custa ~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.

Quer otimizar seu fluxo de trabalho com LLMs?

Conecte modelos por uma única API, gerencie chaves e controle os gastos com IA.

Começar grátis