Modo JSON e saídas de chamadas de ferramentas
Utilize response_format={'type':'json_object'} ou uma única chamada de ferramenta para forçar uma saída analisável por máquinas.
Modo JSON e saídas de chamadas de ferramentas é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.
A necessidade de estrutura
Texto livre gerado por LLMs é hostil ao código. Agentes de produção precisam de saídas analisáveis: JSON, XML, argumentos de funções — nunca "a resposta é..."
Modo JSON (OpenAI)
Diga ao modelo "sempre retorne JSON":
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[
{'role': 'system', 'content': 'Return a JSON object with name and age.'},
{'role': 'user', 'content': 'Alice, 30 years old.'}
],
response_format={'type': 'json_object'}
)
import json
data = json.loads(response.choices[0].message.content)Limitação do modo JSON
O modo JSON garante apenas um JSON válido, não o seu SHAPE. O modelo poderia retornar {} ou {"foo": "bar"}. Sempre valide também o formato.
Saídas Estruturadas (Estrito)
As Saídas Estruturadas da OpenAI garantem que a resposta corresponda a um esquema JSON:
schema = {
'name': 'person',
'schema': {
'type': 'object',
'properties': {
'name': {'type': 'string'},
'age': {'type': 'integer'}
},
'required': ['name', 'age'],
'additionalProperties': False
},
'strict': True
}
response = client.chat.completions.create(
model='gpt-4o-2024-08-06',
messages=...,
response_format={'type': 'json_schema', 'json_schema': schema}
)Como funciona o modo estrito
O modo estrito restringe o decodificador para que o modelo literalmente não possa produzir um token inválido. A saída corresponde 100% ao esquema.
Chamadas de ferramentas como saída estruturada
Você pode forçar uma chamada específica de ferramenta como forma de extrair dados estruturados:
tools = [{'type': 'function', 'function': {
'name': 'submit_person',
'parameters': {
'type': 'object',
'properties': {'name': {'type': 'string'}, 'age': {'type': 'integer'}},
'required': ['name', 'age']
}
}}]
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=...,
tools=tools,
tool_choice={'type': 'function', 'function': {'name': 'submit_person'}}
)
args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)Uso de ferramentas da Anthropic como saída
A Anthropic segue o mesmo padrão com tool_choice="tool":
tool_choice = {'type': 'tool', 'name': 'submit_person'}
print(tool_choice)
JSON por pré-preenchimento (Anthropic)
Para o Claude sem ferramentas, pré-preencha o turno do assistente com {
messages = [
{'role': 'user', 'content': 'Give me JSON for Alice, 30.'},
{'role': 'assistant', 'content': '{'}
]
# Output starts with { and likely produces valid JSON.
for m in messages:
print(f"{m['role']}: {m['content']}")
print("Output starts with { and likely produces valid JSON.")
Pydantic + modo estrito
O SDK Python da OpenAI tem um atalho do Pydantic:
from pydantic import BaseModel
class Person(BaseModel):
name: str
age: int
response = client.beta.chat.completions.parse(
model='gpt-4o-2024-08-06',
messages=...,
response_format=Person
)
person = response.choices[0].message.parsed
# Pydantic instance, type-safeArmadilhas comuns
- Modo JSON sem modo estrito — o modelo pode retornar uma estrutura incorreta
- Esquecer
additionalProperties: falseno modo estrito - Campos obrigatórios não listados no vetor "required"
- O modo estrito está disponível somente no gpt-4o-2024-08-06 e posteriores
Custo das saídas estruturadas
O modo estrito tem uma pequena sobrecarga decorrente da decodificação restringida por gramática — insignificante em comparação com o benefício de qualidade. Mantenha-o sempre ativado quando a estrutura for importante.
Combine com validação
Mesmo as saídas estritas devem ser validadas pelo Pydantic posteriormente. É uma defesa em profundidade — captura casos extremos, como inteiros fora do intervalo.
Garantia do modo estrito
O que as Saídas Estruturadas da OpenAI (modo estrito) garantem?
Recapitulação
Use o modo JSON para estruturas permissivas, Saídas Estritas para estruturas garantidas, chamadas de ferramentas para obter o mesmo efeito e o pré-preenchimento da Anthropic para o Claude. Sempre valide depois.
Aprenda AI Agents com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 60
- Aulas
- 239
Perguntas Frequentes
A aula “Modo JSON e saídas de chamadas de ferramentas” é grátis?
Sim — o texto completo de “Modo JSON e saídas de chamadas de ferramentas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.
O que vou aprender em “Modo JSON e saídas de chamadas de ferramentas”?
Utilize response_format={'type':'json_object'} ou uma única chamada de ferramenta para forçar uma saída analisável por máquinas. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Agents?
Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Modo JSON e saídas de chamadas de ferramentas”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Agents?
Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Modo JSON e saídas de chamadas de ferramentas
- Validação de esquemas com Pydantic
- Loops de reparo para saídas malformadas
- Instructor / Outlines para estrutura garantida