Chamada de função com Gemini 3.8 Flash: call_id, loops de ferramentas iterativos e como testar

Gemini 3.8 Flash foi lançado em 2 de setembro de 2026, e o Google o construiu para “chamar ferramentas iterativamente”: em uma tarefa difícil, ele faz uma chamada, verifica o resultado e faz outra, em vez de tentar adivinhar tudo de uma vez. Essa é uma boa notícia para agentes e uma nova dor de cabeça para qualquer um cujo loop de ferramentas foi ajustado para o 3.7 Flash. Dois detalhes da API importam mais do que qualquer outra coisa. Cada resultado de função deve conter `call_id` e `name`, e a Interactions API, não `generateContent`, é agora a principal forma de executar o loop.

Este guia detalha o fluxo completo de duas etapas na Interactions API, mostra o formato legado do `generateContent` que você provavelmente ainda está usando, explica por que o novo modelo gasta mais turnos e tokens em ferramentas, e termina com uma configuração de teste que você pode executar todos os dias: simule o backend da ferramenta, encadeie ambos os turnos e verifique se o `call_id` completa o ciclo. Se você precisar de uma visão geral do modelo primeiro, comece com o que é o Gemini 3.8 Flash. Os nomes dos campos abaixo vêm da documentação de chamada de função do Google.

Cada requisição aqui é HTTP puro com JSON, então você pode construí-la e depurá-la no Apidog antes de integrá-la ao código da aplicação.

Chamada de função no Gemini 3.8 Flash em resumo

Etapa 1: Declare a ferramenta

Na Interactions API, uma ferramenta é um objeto simples: um `type` de `function`, um `name`, uma `description` que o modelo lê para decidir quando chamá-la, e um JSON Schema em `parameters`. Mantenha a descrição específica. “Consultar o status atual de envio de um pedido pelo seu ID” é chamado no momento certo; “ajudante de pedido” é chamado aleatoriamente.

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-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'

Duas escolhas nesta requisição são intencionais. O `thinking_level` é `low` porque uma única consulta não precisa do `medium` padrão; o guia de níveis de pensamento aborda quando aumentá-lo. E não há `temperature`. A orientação do Gemini 3 do Google é deixá-lo no padrão 1.0, pois diminuí-lo pode causar looping, que é a última coisa que você deseja dentro de um loop de ferramenta.

Etapa 2: Leia a etapa `function_call`

A Interactions API não responde com uma única mensagem. Ela retorna o `id` da própria interação mais uma lista de etapas de execução: pensamentos do modelo, chamadas de ferramenta e, finalmente, uma etapa `model_output` quando o modelo tem uma resposta. Quando o modelo decide que precisa de sua ferramenta, a lista contém uma etapa `function_call` em vez de um `model_output`:

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {"order_id": "A1029"}
}

Três campos, e você precisa de todos os três. `id` é o identificador que você envia de volta como `call_id`. `name` informa qual função executar e também deve ser reenviado. `arguments` já é JSON analisado, então valide-o contra suas próprias regras antes de executar qualquer coisa; o modelo preenche o formato que você declarou, mas ele não sabe que seus IDs de pedido têm cinco caracteres.

Armazene o `id` da interação do topo da resposta ao mesmo tempo. Ele se torna `previous_interaction_id` no próximo turno.

Etapa 3: Retorne o resultado com `call_id` e `name`

Execute sua função e, em seguida, envie uma segunda requisição cujo `input` é um `function_result`. Tanto `call_id` quanto `name` são obrigatórios no Gemini 3.8 Flash. Se um deles for omitido, a chamada falhará, o que é a falha mais comum quando as equipes migram loops escritos para modelos mais antigos.

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-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [{"type": "text", "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"}]
    }]
  }'

`result` é uma lista de partes de conteúdo, e a parte de texto contém seu JSON como uma string. Como `previous_interaction_id` aponta para o turno anterior, o servidor já possui o prompt original, a declaração da ferramenta e o raciocínio do modelo; você não precisa reenviar nada disso. A resposta é outra lista de etapas. Se terminar em `model_output`, você terminou, e o SDK expõe o texto como `interaction.output_text`. Se contiver outra `function_call`, volte para a etapa 2. Esse loop é o padrão completo.

Em Python, o fluxo é `client.interactions.create(model="gemini-3.8-flash", input=..., ...)` com os mesmos campos JSON como argumentos nomeados, então um segundo `create` com `previous_interaction_id` e a lista `function_result` como `input`. O guia de como usar a API Gemini 3.8 Flash abrange chaves, streaming e leitura do uso de tokens se o endpoint for novo para você.

O equivalente legado do `generateContent`

A maioria do código Gemini existente ainda chama `models/gemini-3.8-flash:generateContent`, e o Google diz que ele “permanece totalmente suportado” sem data de desativação. O vocabulário é diferente; a regra é a mesma. As ferramentas são declaradas em `functionDeclarations`, o modelo responde com uma parte `functionCall`, e você responde com uma parte `functionResponse`. No formato legado, a parte `functionCall` do modelo contém um `id`, e sua parte `functionResponse` deve ecoar esse mesmo valor em seu próprio campo `id` juntamente com `name` e `response`. É o mesmo contrato que `call_id` na Interactions API sob um nome de campo diferente, e a orientação do Gemini 3 do Google é explícita de que tanto o id quanto o name são obrigatórios.

Duas diferenças práticas. Primeiro, `generateContent` é sem estado, então você mesmo gerencia a conversação: o histórico completo de `contents` é enviado de volta em cada turno, incluindo a parte `functionCall` do modelo e quaisquer assinaturas de pensamento que ele retornou. Segundo, o pensamento é configurado em `generationConfig.thinkingConfig.thinkingLevel` em vez de `generation_config.thinking_level`:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Os tokens de pensamento aparecem como `usageMetadata.thoughtsTokenCount` na resposta e são cobrados como saída. Se você está escolhendo entre as duas APIs para um novo projeto, escolha Interactions: o estado do lado do servidor elimina a classe de bugs onde um histórico reenviado está faltando uma assinatura ou um `call_id`.

Por que o 3.8 Flash chama ferramentas iterativamente e como limitar o loop

A publicação de lançamento do Google afirma que o modelo “trabalha mais”: em tarefas complexas, ele “executa etapas de raciocínio extras e chama ferramentas iterativamente”, dando “passos de raciocínio menores” e verificando seu trabalho ao longo do caminho. O Google também afirma que ele “pode usar mais tokens em tarefas mais longas e complexas, por design”. A Artificial Analysis mediu o efeito: cerca de 48 mil tokens de saída por tarefa em seu índice, +30% em relação ao 3.7 Flash, e um custo por tarefa de $0.58 em `high` versus $0.40 para o 3.7 Flash aos mesmos preços por token. `Medium` ficou em $0.41 e `low` em $0.24.

Para um loop de ferramenta, isso significa mais etapas `function_call` por tarefa. O lado positivo é real: o Tau3-Banking, avaliação de uso de ferramentas da AA, subiu 12 pontos para 45%. O lado negativo é que um loop sem teto agora roda por mais tempo do que em agosto. Quatro controles, na ordem de aplicação:

• Limite máximo de turnos em seu *harness*. Conte as etapas `function_call` por tarefa e pare em um limite que você escolher; 6 a 10 é um intervalo inicial sensato para consultas, mais alto para codificação de agentes. Quando o limite for atingido, envie um turno final sem ferramentas, ou retorne um erro ao usuário. O modelo não se limitará sozinho.
• `thinking_level` por rota. `low` para consultas e ferramentas de um único passo, `medium` (o padrão) para trabalho multi-passos, `high` apenas onde a verificação extra compensa. Não envie `minimal`; o 3.8 Flash retorna um erro de validação.
• Tempos limites em ambos os lados. Um tempo limite por requisição na chamada do Gemini e um tempo limite global por tarefa no loop. As execuções de alto raciocínio da AA tiveram uma média de 2,5 minutos por tarefa, 0,8 minutos em `low`.
• Ferramentas idempotentes. Um modelo iterativo tenta novamente. Torne `get_order_status` seguro para ser chamado duas vezes, e faça com que qualquer coisa com efeitos colaterais (reembolsos, envios) exija uma etapa de confirmação.

Se o seu orçamento não pode absorver os turnos extras, o guia de migração do 3.7 para o 3.8 Flash aborda como manter o 3.7 Flash, que permanece totalmente suportado, atrás de uma *flag* de configuração.

Assinaturas de pensamento, chamadas paralelas e saídas estruturadas

Assinaturas de pensamento. Os modelos Gemini 3 anexam assinaturas ao seu raciocínio. Com o fluxo padrão armazenado da Interactions API, `previous_interaction_id` lida com elas para você. Se você definir `store: false` para uma configuração sem estado, ou usar `generateContent`, você deve enviar os blocos de pensamento e as assinaturas de volta exatamente como recebidos, em cada tipo de parte. Não os corte, reordene ou resserialice; uma assinatura é opaca e qualquer edição a invalida. A documentação da Interactions API do Google aborda a troca entre estado armazenado e sem estado.

Chamadas paralelas. A resposta é uma lista, então ela pode conter mais de uma etapa `function_call` quando o modelo deseja várias consultas independentes de uma vez. A documentação de chamada de função do Google confirma que os modelos Gemini 3 retornam um ID único com cada chamada precisamente para que os resultados possam retornar em qualquer ordem. Lide com isso retornando um `function_result` por chamada no mesmo array `input`, cada um correspondido pelo seu próprio `call_id`. Corresponder apenas por `name` não é suficiente; duas chamadas para a mesma função precisam de dois valores `call_id` diferentes.

Saídas estruturadas. O 3.8 Flash suporta saídas estruturadas e chamada de função no mesmo modelo. O padrão limpo é usar ferramentas para o loop e um schema JSON para a resposta final, para que o `model_output` que fecha o loop seja legível por máquina em vez de texto corrido. As páginas do Google sobre chamada de função e saídas estruturadas documentam a configuração. Não finja declarando uma ferramenta dummy e lendo seus `arguments`; isso falha no momento em que o modelo decide que não tem nada para chamar.

Tudo acima assume que o modelo acessa seu sistema através de funções declaradas. O Google também lista o uso de Computador (Preview) para o 3.8 Flash; para quando uma API estruturada supera a condução de um agente via tela, veja uso de computador vs. APIs estruturadas.

Testando o loop de ferramentas no Apidog

Um loop de ferramenta tem três pontos de falha: a declaração, o *round-trip* do ID e a resposta final. Você pode cobrir todos os três no Apidog sem tocar no seu backend real.

1. Simule o backend da ferramenta. Defina `GET /orders/{order_id}` como um endpoint e ative seu servidor *mock*. Dê a ele um corpo de resposta fixo, `{"status": "in_transit", "eta": "2026-09-05"}`, para que cada execução receba entrada idêntica e qualquer mudança na resposta final do modelo seja de responsabilidade do modelo, não do seu banco de dados. Seu *harness* aponta para a URL *mock* no ambiente de teste e para o serviço real em produção.

2. Encadeie ambos os turnos em um cenário de teste. Armazene `GEMINI_API_KEY` como uma variável de ambiente e faça referência a ela como `{{GEMINI_API_KEY}}` no cabeçalho `x-goog-api-key`. Em seguida, construa um cenário com três etapas:

• Etapa A: POST para `/v1beta/interactions` com o prompt e a declaração `get_order_status`. Extraia o `id` da interação e o `id`, `name` e `arguments.order_id` da etapa `function_call` para variáveis.
• Etapa B: GET o endpoint *mock* com `{{order_id}}`. Esta é sua etapa de “executar a função”.
• Etapa C: POST o `function_result` com `call_id` definido como `{{call_id}}`, `name` definido como `{{tool_name}}`, `previous_interaction_id` definido como `{{interaction_id}}`, e o corpo da Etapa B como a parte de texto.

3. Verifique o que importa.

• A Etapa A retorna 200 e contém uma etapa cujo `type` é `function_call` com `name` igual a `get_order_status`.
• O `arguments.order_id` extraído é igual a `A1029`, o que prova que o modelo analisou o prompt e respeitou o schema.
• A Etapa C retorna 200 e termina em uma etapa cujo `type` é `model_output` sem uma segunda `function_call`, o que prova que o `call_id` e o `name` que você enviou foram aceitos e o loop foi fechado em uma rodada.
• O texto final contém `in_transit`, o que prova que o modelo usou o resultado da ferramenta em vez de sua própria suposição.
• Se você executar o mesmo cenário contra `generateContent`, adicione um limite para `usageMetadata.thoughtsTokenCount` por `thinking_level`. Isso detecta o aumento de custo de "trabalho mais intenso" antes que ele chegue à sua conta.

Agende o cenário para ser executado diariamente. O comportamento do modelo pode mudar com atualizações silenciosas, e um loop que fechou em um turno na semana passada pode começar a precisar de dois. O guia de teste de API de agentes de IA aprofunda as asserções em várias etapas, e você pode Baixar o Apidog para construir o cenário na camada gratuita antes de gastar um centavo.

FAQ

O `call_id` é obrigatório no Gemini 3.8 Flash? Sim. Na Interactions API, todo `function_result` precisa de `call_id` e `name`; no `generateContent`, todo `functionResponse` precisa do `id` e `name` da chamada. Códigos mais antigos que enviavam apenas o nome falham nos modelos Gemini 3.

Por que meu loop de ferramenta executa mais turnos no 3.8 Flash do que no 3.7? Por design. O Google diz que o modelo “chama ferramentas iterativamente” e “pode usar mais tokens em tarefas mais longas e complexas”. Limite os turnos em seu *harness* e diminua o `thinking_level`; o guia de níveis de pensamento tem o custo medido por nível.

Ainda posso usar `generateContent` para chamada de função? Sim. O Google o chama de legado, mas diz que ele “permanece totalmente suportado” sem data de desativação. Você mesmo gerencia o histórico, incluindo as assinaturas de pensamento, e o ID da chamada (escrito `id` nesta API) mais `name` ainda se aplicam.

O `thinking_level` “minimal” funciona com ferramentas? Não. Ele retorna um erro de validação no 3.8 Flash. Use `low`.

Quanto custa uma tarefa que usa muitas ferramentas? O preço por token é de $0.75 de entrada e $3.75 de saída por 1M de tokens até 31 de dezembro de 2026, com o pensamento cobrado como saída. A Artificial Analysis mediu $0.58 por tarefa em `high`, $0.41 em `medium` e $0.24 em `low` em seu índice. Suas tarefas serão diferentes, então verifique a contagem de tokens e meça.

Envie o loop com um limite

Declare a ferramenta, leia a etapa `function_call` e retorne `function_result` com `call_id` e `name` sob `previous_interaction_id`. Esse é todo o contrato. O que mudou com o Gemini 3.8 Flash é a disposição do modelo de realizar *loops*, então o *harness* precisa de um limite de turnos, um `thinking_level` por rota e um tempo limite antes de ir para produção. Simule o *backend*, encadeie os dois turnos, verifique os *round-trips* do ID e agende a execução. A página Novidades no Gemini 3.8 Flash do Google tem as notas de migração; o guia pilar tem todo o resto sobre o modelo.