Como parsear tool calls da OpenAI, Anthropic e Google

Um problema, três dialetos

OpenAI, Anthropic e Google expressam a mesma intenção: “quero executar esta função com estes argumentos”. O envelope muda. A OpenAI retorna um item function_call, a Anthropic um bloco tool_use e o Google uma parte functionCall.

Um harness não deveria espalhar esses três formatos por todo o produto. Traduza-os na fronteira do provedor para um comando comum do executor. Mas normalizar não significa apagar: o identificador nativo da chamada precisa sobreviver para que o resultado volte à solicitação correta.

O JSON retornado por cada API

Estes exemplos reduzem capturas reais aos campos envolvidos na chamada. Os identificadores opacos foram substituídos por nomes legíveis. OpenAI e Google foram capturados com uma solicitação mínima forçada; o exemplo da Anthropic vem de uma fixture gravada anteriormente e foi conferido com a documentação oficial porque a credencial de captura havia expirado.

{
  "type": "function_call",
  "id": "fc_openai_1",
  "call_id": "call_openai_1",
  "name": "lookup_demo_value",
  "arguments": "{\"key\":\"height\"}",
  "status": "completed"
}

{
  "type": "tool_use",
  "id": "toolu_anthropic_1",
  "name": "lookup_demo_value",
  "input": {
    "key": "height"
  }
}

{
  "functionCall": {
    "name": "lookup_demo_value",
    "args": {
      "key": "height"
    },
    "id": "call_google_1"
  }
}

Uma forma comum sem perder contexto

O código que executa uma função precisa apenas de name e args. O código que monta o próximo turno também precisa do provedor e de seu identificador nativo. Separar esses conceitos impede que um detalhe da OpenAI chegue ao handler e também evita responder apenas “por nome” quando duas chamadas usam a mesma função.

{
  "execution": {
    "name": "lookup_demo_value",
    "args": {
      "key": "height"
    }
  },
  "correlation": {
    "provider": "openai | anthropic | google",
    "callId": "identificador nativo da chamada"
  }
}

Parseie o stream, não os pacotes

Em streaming, um fragmento de rede não é igual a um evento SSE nem a um JSON completo. A rede pode cortar no meio de "arguments", juntar cinco eventos no mesmo fragmento ou deixar o evento final sem a linha em branco de encerramento.

1. Acumule texto em um buffer.
2. Extraia apenas eventos SSE completos e preserve o restante.
3. Interprete o tipo do evento e agregue deltas pelo índice ou identificador.
4. Ao fechar o stream, processe o restante mais uma vez se ele formar um evento válido.

A OpenAI pode separar a criação do item e os deltas de argumentos; a Anthropic transmite input_json_delta; o Google costuma enviar uma parte de função completa. O parser deve esconder essa diferença e produzir o mesmo resultado para qualquer partição de bytes.

Várias chamadas e dados quebrados

Argumentos inválidos podem ser normalizados para um objeto vazio para manter o parser estável, mas isso não é validação. Antes de executar uma ação com efeitos, o harness ainda precisa verificar JSON Schema, permissões e regras de negócio.

O contrato de testes

Adicione regressões para JSON truncado, erros explícitos e formatos inesperados de argumentos. Esses testes não provam que o modelo escolherá a tool certa; provam que o harness interpretará de forma determinística tudo o que receber.

Fontes oficiais

• OpenAI: Function calling.
• Anthropic: Handle tool calls.
• Google: Function calling with the Gemini API e a referência de GenerateContent.