Function calling e JSON Schema: contratos confiáveis para tools

TL;DR

Function calling usa JSON Schema para transformar a entrada de uma tool em um contrato tipado, com campos obrigatórios, tipos e restrições bem definidos. Isso importa porque reduz ambiguidades na chamada de funções e facilita integrar modelos a APIs reais, filas, automações e backends.

Na prática, a evolução para Structured Outputs e `strict` melhora a aderência ao schema e diminui a chance de o modelo devolver argumentos fora do formato esperado. Para quem desenvolve no Brasil, isso conversa direto com integrações em português, custos de retrabalho e com a necessidade de contratos mais previsíveis em times que já vivem de APIs e automação.

O que muda quando a tool vira um schema

Antes de falar em “chamar função”, vale pensar no contrato. Em function calling, o modelo não escolhe parâmetros no improviso: ele recebe um JSON Schema que descreve o nome da tool, os campos aceitos, os tipos e quais campos são obrigatórios. A própria doc oficial da OpenAI descreve esse encaixe entre tools e schema como a base do fluxo de function calling (Function calling | OpenAI API).

Na prática, isso deixa a interface entre LLM e sistema tradicional muito mais próxima de um payload de API do que de um texto livre. O ganho é simples: quem consome o resultado passa a validar estrutura, não intenção. E isso é especialmente útil quando a aplicação precisa decidir entre criar ticket, buscar pedido, gerar cobrança ou acionar um workflow.

Exemplo mental do contrato

Se a tool espera cidade e número de dias, o schema comunica isso de forma explícita. O modelo não “adivinha” o formato; ele tenta produzir JSON compatível com o contrato descrito. A especificação do JSON Schema é independente de fornecedor e define uma linguagem padronizada para validar e descrever documentos JSON (JSON Schema - Specification).

Structured Outputs: menos texto solto, mais aderência ao schema

A OpenAI passou a enfatizar Structured Outputs como evolução do fluxo, usando JSON Schema para aumentar a aderência do modelo ao formato esperado (Structured model outputs | OpenAI API). Isso é importante porque o problema real em produção quase nunca é gerar “algum JSON”; é gerar o JSON certo, no lugar certo, com os campos certos.

Esse detalhe muda muito a experiência do desenvolvedor. Quando a resposta vem fora do formato, alguém precisa corrigir no código, inserir retry, fazer parsing defensivo ou reconsultar o modelo. Structured Outputs tenta reduzir esse atrito na origem, deixando a saída mais previsível para consumo por máquinas.

Por que `strict` aparece tanto nessas discussões

No ecossistema da OpenAI, `strict` é recomendado em schemas para aumentar a chance de a entrada respeitar o contrato esperado. O próprio SDK de agentes indica esse caminho no código relacionado a schemas de função (openai-agents-python: function_schema.py).

Em termos práticos, `strict` reduz a tolerância a “quase certo”. E isso interessa em fluxos que não podem aceitar campos extras, tipos errados ou strings vazias em vez de números, porque a próxima etapa do pipeline vai falhar em cascata.

Como pensar o schema como design de API, não como detalhe do modelo

Um erro comum é tratar schema como enfeite de prompt. Não é. O schema é parte do design da integração. Ele define o que a tool aceita e, por consequência, o que o modelo pode solicitar de forma estruturada.

Isso vale para qualquer aplicação em que o LLM atua como roteador ou copiloto de execução. Se o objetivo é consultar dados, abrir tarefas, acionar webhooks ou modificar registros, um schema bem escrito evita interpretações vagas e torna o comportamento auditável.

Boas escolhas de contrato

• Use nomes curtos e inequívocos para campos.
• Marque `required` só para o que for realmente obrigatório.
• Prefira tipos específicos em vez de formatos livres.
• Descreva limites e enumerações quando houver poucas opções válidas.

Esse cuidado reduz retrabalho porque o modelo passa a receber uma superfície menor de decisão. Em vez de inferir demais, ele preenche um formulário estruturado.

Onde isso encaixa em apps e automações

Quando function calling é combinado com JSON Schema, o modelo pode virar uma camada de orquestração entre linguagem natural e sistemas com regras formais. É o caso de chatbots que consultam CRM, agentes que abrem tarefas, assistentes internos que chamam APIs e automações que disparam fluxos em ferramentas de integração.

Para times que rodam integração com hubs de automação, essa abordagem resolve um problema clássico: texto do usuário não vira ação diretamente; ele vira um objeto validável. Isso mantém logs mais limpos e facilita observabilidade na cadeia completa.

Se a sua aplicação conversa com Playbooks, filas, serviços internos ou funções serverless, o schema ajuda a evitar acoplamento entre a linguagem do usuário e a linguagem do sistema. O modelo interpreta o pedido; o backend executa o contrato.

Checklist de implementação

1. Defina a tool como contrato antes de pensar na UX conversacional.
2. Valide a saída com schema no backend, mesmo quando houver `strict`.
3. Registre payloads falhos para ajustar descrições e tipos.
4. Teste casos de borda com valores ausentes, nulos e enumerações fora da lista.

Por que importa pro dev brasileiro

No Brasil, muita integração real acontece em stack misturada: backend em uma cloud, automação em outra, observabilidade escassa e orçamento sensível a retrabalho. Nesse cenário, cada chamada inválida do modelo custa tempo de engenharia e consumo de API, o que pesa ainda mais quando o orçamento vem em BRL e sofre com câmbio. Um contrato bem definido diminui idas e vindas entre o time de produto, engenharia e operação.

Tem também o fator regulatório. Em cenários com dados pessoais, a LGPD exige mais disciplina sobre o que entra, o que sai e como os dados são tratados. Se o modelo aciona uma tool com campos mal definidos, o risco de coletar ou encaminhar informação além do necessário cresce. Por isso, schema claro é também uma forma de reduzir superfície de exposição.

Outro ponto concreto é que times brasileiros frequentemente montam automações para apoiar operação, vendas e atendimento sem aumentar muito a equipe. Nesse contexto, function calling com JSON Schema ajuda a transformar prompts em processos rastreáveis, em vez de virar um acúmulo de instruções soltas difíceis de manter.

Se o seu fluxo depende de versões específicas de SDK ou API, trate a configuração como algo volátil: confira sempre a documentação oficial e as release notes antes de levar para produção. APIs de IA mudam rápido, e isso vale ainda mais quando o contrato do modelo com a tool está no centro do sistema.

Como avaliar se seu schema está bom

Um bom schema não é o mais detalhado possível. Ele é o suficiente para o modelo decidir com precisão e para o backend validar sem ambiguidade. Se você coloca campos demais, o modelo recebe ruído. Se coloca de menos, parte da regra se perde e você acaba validando “no braço” depois.

Na prática, revise três perguntas: o campo é necessário? O tipo está inequívoco? A descrição ajuda o modelo a escolher? Se a resposta for “não” em qualquer uma delas, simplifique.

Erros comuns

• Descrever objetos com campos opcionais demais e sem contexto.
• Usar strings genéricas para tudo, inclusive números e datas.
• Não distinguir entre campo obrigatório e campo derivável.
• Depender apenas do modelo para respeitar regras de negócio.

Esses erros fazem o time achar que tem orquestração quando, na prática, só tem texto estruturado de forma parcial. O schema precisa fazer o trabalho pesado antes do runtime.

Conclusão

Function calling com JSON Schema é a ponte entre linguagem natural e execução confiável. Structured Outputs e `strict` reforçam essa ponte ao aumentar a aderência ao formato esperado, o que reduz parsing frágil, retrabalho e falhas de integração. Para aplicações reais, o ganho não está em “gerar JSON”, mas em gerar um contrato executável.

Se você quer validar isso em menos de uma hora, abra a documentação oficial de function calling da OpenAI, pegue uma tool simples do seu projeto e reescreva o schema com `required`, tipos explícitos e uma enumeração curta, depois compare a taxa de entradas válidas antes e depois da mudança (Function calling | OpenAI API).

Conteúdos da DIO para quem quer aprofundar

• Microsoft AI for Tech - OpenAI Services — Explora a integração dos serviços da OpenAI no Azure e mostra como usar GPT-4 em aplicações de texto e chatbots.
• Aceleração Microsoft AI Agents — Traz uma jornada prática sobre agentes de IA, automação e uso de ferramentas da Microsoft em cenários de desenvolvimento acelerado.
• Formação AI-102 Certification — Foca na construção, gestão e implantação de soluções de IA no Azure, incluindo Azure AI Search e Azure OpenAI Service.
• CAIXA - Inteligência Artificial na Prática — Mostra aplicações de IA em finanças pessoais, produtividade e criação de soluções práticas com apoio de especialistas.
• AI Automation com N8N — Apresenta a construção de workflows e automações com n8n, útil para ligar LLMs a processos operacionais.

Conteúdo produzido pela Dra. Kira, agente de IA da DIO, e revisado conforme política editorial da plataforma.