Phase 13: Tools & Protocols

Função chamada Deep Dive OpenAI, Antropic, Gemini

Type: Build

Languages: Python (stdlib, schema translators)

Prerequisites: Phase 13 · 01 (the tool interface)

Time: ~75 minutes

Objetivos de aprendizagem

• Explique as três diferenças de forma entre as cargas úteis que chamam a função OpenAI, Anthropic e Gemini (declaração, chamada, resultado).
• Traduzir uma declaração de ferramenta para todos os três formatos do fornecedor e prever onde as restrições de modo rigoroso diferirão.
• Utilizaçãotool_choiceem cada fornecedor para forçar, proibir ou escolher automaticamente as chamadas de ferramentas.
• Conheça os limites de duração por fornecedor (contação de ferramentas, profundidade de esquema, comprimento de argumento) e as assinaturas de erro emitidas quando os limites são violados.

O problema

A forma de uma solicitação de chamada de função difere de um prestador para outro.

OpenAI Chat Completions / Responses API.Passas .tools: [{type: "function", function: {name, description, parameters, strict}}]A resposta do modelo contém choices[0].message.tool_calls: [{id, type: "function", function: {name, arguments}}]ondeargumentsé uma cadeia JSON que você deve analisar.strict: true) impõe a conformidade com o esquema através de decodificação restrita.

Anthropic Messages API.Passas .tools: [{name, description, input_schema}]A resposta é:content: [{type: "text"}, {type: "tool_use", id, name, input}]- Não .inputjá foi analisado (um objeto, não uma cadeia).usermensagem contendo um {type: "tool_result", tool_use_id, content}Bloco.

Google Gemini API.Passas .tools: [{functionDeclarations: [{name, description, parameters}]}](nesteado sob functionDeclarationsA resposta é:candidates[0].content.parts: [{functionCall: {name, args, id}}]ondeidÉ único em Gemini 3 e acima para correlação de chamadas paralelas.{functionResponse: {name, id, response}}- Não .

O mesmo ciclo. nomes de campos diferentes, nidificação diferente, convenções diferentes de cadeia contra objeto, diferentes mecanismos de correlação. Uma equipe que escreve um agente meteorológico na OpenAI paga um porto de dois dias para Anthropic e outro dia para Gemini apenas pela instalação de encanamento.

Esta lição constrói um tradutor que unifica os três formatos em uma declaração canônica de ferramenta e rotas na borda.

O conceito

A estrutura comum

Cada fornecedor precisa de cinco coisas:

1. Tool list.Nome, descrição e esquema de entrada por ferramenta.
2. Tool choice.Forçar uma ferramenta específica, proibir ferramentas, ou deixar o modelo decidir.
3. Call emission.Output estruturado nomeando a ferramenta e os argumentos.
4. Call id.Correlação da resposta à chamada correta (matéria paralela).
5. Result injection.Uma mensagem ou bloqueio que liga o resultado à chamada.

Diferenças de forma, campo por campo

Limite que você vai realmente atingir

• OpenAI.128 ferramentas por pedido. profundidade de esquema 5. cadeia de argumentos <= 8192 bytes.$refNão , não .oneOf- Não .anyOf- Não .allOfcom sobreposição, todas as propriedades enumeradas em required- Não .
• Anthropic.64 ferramentas por pedido. Profundidade do esquema efetivamente ilimitada mas limite prático 10.
• Gemini.64 funções por solicitação. Os tipos de esquema são um subconjunto OpenAPI 3.0 (uma pequena divergência do JSON Schema 2020-12).

tool_choicecomportamento

Três modos que todos suportam, nomeados de forma diferente.

• Auto.O modelo escolhe ferramenta ou texto.
• Required / Any.O modelo deve chamar pelo menos uma ferramenta.
• None.O modelo não deve chamar ferramentas.

Além de um modo único para cada fornecedor:

• OpenAI.Forçar uma ferramenta específica pelo nome.
• Anthropic.Forçar uma ferramenta específica por nome; disable_parallel_tool_useA bandeira separa o único contra o múltiplo.
• Gemini. mode: "VALIDATED"Roteia cada resposta através de um validador de esquema, independentemente da intenção do modelo.

Chamadas paralelas

O OpenAI parallel_tool_calls: true(default) emite várias chamadas em uma mensagem assistente.tool_call_idHistoricamente , o Anthropic fez um único telefonema .disable_parallel_tool_use: false(default em Claude 3.5) permite multi. Gemini 2 permitiu chamadas paralelas, mas não deu ids estáveis; Gemini 3 adiciona UUIDs para que as respostas fora de ordem se correlacionem limpa.

Transmissão

As três chamadas de ferramenta de suporte são transmitidas.

• OpenAI.- Fragmentos de Delta detool_calls[i].function.argumentsAcumulam-se até quefinish_reason: "tool_calls"- Não .
• Anthropic.Eventos de bloqueio de início / bloqueio de delta / bloqueio de parada. input_json_deltaOs pedaços contêm argumentos parciais.
• Gemini. streamFunctionCallArguments(novo em Gemini 3) emite pedaços com um functionCallIdpara que várias chamadas paralelas possam intercalar-se.

A fase 13 · 03 é uma fase de análise profunda da montagem paralela + de streaming.

Erros e reparação

Os erros de argumento inválido também parecem diferentes.

• OpenAI (non-strict).Reto de modelo arguments: "{bad json}"Se o seu JSON falhar, injetam uma mensagem de erro e chamam novamente.
• OpenAI (strict).A validação ocorre durante a decodificação; JSON inválido é impossível, mas refusalPode aparecer.
• Anthropic. inputPode conter campos inesperados; esquema é de aconselhamento. Validação do lado do servidor.
• Gemini.A peculiaridade da OpenAPI 3.0: enumem campos objetos silenciosamente ignorados; validar-se.

O padrão de tradutor

Uma declaração canônica de ferramenta no seu código parece assim (você escolhe a forma):

pythonCopyTool(
    name="get_weather",
    description="Use when ...",
    input_schema={"type": "object", "properties": {...}, "required": [...]},
    strict=True,
)

Três pequenas funções traduzem-no para as três formas do provedor.code/main.pyNão é necessário nenhuma rede. esta lição ensina as formas, não o HTTP.

As equipes de produção envolvem este tradutor em AbstractToolset(AI da Pidantica),UniversalToolNode(LangGraph), ou BaseTool(LlamaIndex). Fase 13 · 17 envia um gateway que expõe uma API em forma de OpenAI na frente de qualquer um dos três.

Usá-lo

code/main.pydefine um canônico ToolDataclass e três tradutores que emitem a declaração OpenAI, Anthropic e Gemini JSON. Ele então analisa uma resposta feita à mão de cada forma de cada provedor no mesmo objeto de chamada canônica, demonstrando que a semântica é idêntica sob a pele.

O que ver:

• Os três blocos de declaração diferem apenas em termos de envelopes e de nomes de campos.
• Os três blocos de resposta diferem em que a chamada vive (nível superior tool_calls- Não .content[]Bloco,parts[](entrada).
• Um .canonical_call()Extracto de função {id, name, args}de todas as três formas de resposta.

Envia-o

Esta lição produzoutputs/skill-provider-portability-audit.md- Tendo em conta uma integração de chamadas de função contra um prestador, a competência produz uma auditoria de portabilidade: quais os limites de que o prestador depende, quais os campos que precisam ser renomeados e quais os rompimentos quando são portados para cada outro prestador.

Exercícios

1. Corra .code/main.pye verificar que as três declarações de fornecedor JSONs todos serializam o mesmo subjacente ToolModificar a ferramenta canônica para adicionar um parâmetro enum e confirmar que apenas o tradutor Gemini precisa para lidar com a peculiaridade do OpenAPI.

1. Adicionar umListToolsResponseparser para cada fornecedor que extrai a lista de ferramentas um modelo retorna após um list_toolsO OpenAI não tem um nativo; note esta assimetria.

1. Implementação tool_choiceconversion: mapa de um canônico ToolChoice(mode="force", tool_name="x")Em todas as três formas do provedor.mode="any"E ...mode="none"Verifique a tabela de diferença da lição.

1. Escolha um dos três provedores e leia o seu guia de chamadas de função de ponta a ponta. Encontre um campo em sua especificação de esquema que os outros dois não suportam.strict, Antropico disable_parallel_tool_use, Gémeos .function_calling_config.allowed_function_names- Não .

1. Escreva um vetor de teste: uma chamada de ferramenta cujos argumentos violam o esquema declarado. Execute-o através do validador de cada fornecedor (o stdlib na lição 01 fará como um proxy) e registre quais erros são causados. Documentar qual fornecedor você usaria na produção para rigor.

Termos-chave

Mais leitura

• OpenAI — Function calling guide Referência canónica, incluindo o modo rigoroso e as chamadas paralelas
• Anthropic — Tool use overview- Não .tool_useE ...tool_resultsemântica de blocos
• Google — Gemini function calling chamadas paralelas, ids únicos e subconjunto OpenAPI
• Vertex AI — Function calling reference Superfície empresarial de Gémeos
• OpenAI — Structured outputs Detalhes sobre a aplicação de esquemas de modo rigoroso

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.