Definindo esquemas de funções para a API
Escreva definições JSON Schema para suas funções, passe-as no parâmetro tools e entenda como o modelo decide quando e como chamá-las.
Definindo esquemas de funções para a API é uma aula grátis de AI Engineering Academy 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 Engineering Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Engineering Academy inclui 4 aulas no total.
O que é chamada de funções?
A chamada de funções da OpenAI (agora chamada de chamada de ferramentas) permite descrever funções Python para o modelo em um formato estruturado de esquema JSON. Quando determina que uma função deve ser chamada, em vez de produzir texto livre, o modelo retorna um objeto JSON estruturado com o nome da função e seus argumentos — que seu código executa de maneira confiável.
Estrutura do parâmetro tools
Você passa as definições das funções para a API, no parâmetro tools, como uma lista de objetos. Cada objeto tem um type igual a 'function' e uma chave function contendo o nome, a descrição e um esquema JSON que define os parâmetros.
from openai import OpenAI
client = OpenAI()
tools = [
{
'type': 'function',
'function': {
'name': 'get_current_weather',
'description': 'Get the current weather in a given location.',
'parameters': {
'type': 'object',
'properties': {
'location': {
'type': 'string',
'description': 'City and country, e.g. London, UK'
},
'unit': {
'type': 'string',
'enum': ['celsius', 'fahrenheit'],
'description': 'Temperature unit to use.'
}
},
'required': ['location']
}
}
}
]Esquema JSON para parâmetros
O campo parameters segue a especificação de esquema JSON. Use type para especificar texto, número, inteiro, booleano, matriz ou objeto. Use description em cada propriedade para informar ao modelo o significado do campo. Liste os campos obrigatórios na matriz required — os campos opcionais podem ser omitidos de required.
# A more complex schema with multiple types
create_event_tool = {
'type': 'function',
'function': {
'name': 'create_calendar_event',
'description': 'Create a new calendar event. Use when the user wants to schedule a meeting or appointment.',
'parameters': {
'type': 'object',
'properties': {
'title': {'type': 'string', 'description': 'Event title.'},
'start_time': {'type': 'string', 'description': 'ISO 8601 datetime, e.g. 2024-03-15T14:00:00.'},
'duration_minutes': {'type': 'integer', 'description': 'Duration in minutes.', 'minimum': 5},
'attendees': {
'type': 'array',
'items': {'type': 'string'},
'description': 'List of email addresses of attendees.'
},
'location': {'type': 'string', 'description': 'Physical or virtual meeting location.'}
},
'required': ['title', 'start_time', 'duration_minutes']
}
}
}Fazendo a chamada da API com ferramentas
Passe a lista tools diretamente para chat.completions.create. O modelo pode responder com uma mensagem de texto comum (se conseguir responder sem uma função) ou com um objeto tool_calls instruindo você a executar uma função. Sempre verifique finish_reason para saber em qual situação você está.
response = client.chat.completions.create(
model='gpt-4o',
messages=[
{'role': 'user', 'content': 'What is the weather in Tokyo?'}
],
tools=tools
)
print('Finish reason:', response.choices[0].finish_reason)
# 'tool_calls' means the model wants to call a function
# 'stop' means the model gave a regular text response
choice = response.choices[0].message
if response.choices[0].finish_reason == 'tool_calls':
print('Model wants to call:', choice.tool_calls[0].function.name)Controlando a seleção de ferramentas com tool_choice
O parâmetro tool_choice controla se o modelo deve chamar uma função ou pode escolher livremente. Defini-lo como 'auto' permite que o modelo decida. Defini-lo como 'required' força uma chamada de ferramenta. Defini-lo como um nome de função específico força a chamada exatamente daquela função — algo útil em tarefas de extração nas quais você sempre deseja uma saída estruturada.
# Force the model to always call extract_contact
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Hi, I am John Smith, john@example.com, +1-555-0100.'}],
tools=[extract_contact_tool],
tool_choice={'type': 'function', 'function': {'name': 'extract_contact'}}
)
# With tool_choice forced, finish_reason will always be 'tool_calls'Campos enum para escolhas restritas
Use o campo enum no seu esquema JSON sempre que um parâmetro precisar ser restrito a um conjunto fixo de valores. Isso melhora drasticamente a confiabilidade — é muito menos provável que o modelo invente uma opção inválida quando consegue ver no esquema a lista exata de valores permitidos.
classify_sentiment_tool = {
'type': 'function',
'function': {
'name': 'classify_sentiment',
'description': 'Classify the sentiment of a customer review.',
'parameters': {
'type': 'object',
'properties': {
'sentiment': {
'type': 'string',
'enum': ['positive', 'negative', 'neutral', 'mixed'],
'description': 'The sentiment classification.'
},
'confidence': {
'type': 'number',
'minimum': 0.0,
'maximum': 1.0,
'description': 'Model confidence from 0 to 1.'
}
},
'required': ['sentiment', 'confidence']
}
}
}Esquemas de objetos aninhados
O JSON Schema é compatível com objetos aninhados. Use 'type': 'object' com suas próprias properties para definir estruturas de dados hierárquicas complexas. Isso é ideal para extrair dados estruturados de textos não estruturados, como e-mails ou documentos.
extract_order_tool = {
'type': 'function',
'function': {
'name': 'extract_order',
'description': 'Extract order details from a customer email.',
'parameters': {
'type': 'object',
'properties': {
'customer': {
'type': 'object',
'properties': {
'name': {'type': 'string'},
'email': {'type': 'string', 'format': 'email'}
},
'required': ['name']
},
'items': {
'type': 'array',
'items': {
'type': 'object',
'properties': {
'product_id': {'type': 'string'},
'quantity': {'type': 'integer', 'minimum': 1}
},
'required': ['product_id', 'quantity']
}
}
},
'required': ['customer', 'items']
}
}
}Gerando esquemas a partir de modelos Pydantic
Escrever esquemas JSON manualmente é trabalhoso e propenso a erros. Em vez disso, defina sua estrutura de dados como um modelo Pydantic e use .schema() para gerar o JSON Schema automaticamente. Isso também oferece validação no nível do Python quando você desserializa a resposta do modelo.
from pydantic import BaseModel, Field
from typing import Optional, List
class ContactInfo(BaseModel):
name: str = Field(description='Full name of the person.')
email: Optional[str] = Field(None, description='Email address.')
phone: Optional[str] = Field(None, description='Phone number in E.164 format.')
company: Optional[str] = Field(None, description='Company or organization.')
# Auto-generate the JSON Schema
schema = ContactInfo.schema()
# Build the tool definition
extract_contact_tool = {
'type': 'function',
'function': {
'name': 'extract_contact',
'description': 'Extract contact information from text.',
'parameters': schema
}
}Escrevendo descrições eficazes de funções
A descrição da função é o principal sinal que o modelo usa para decidir quando chamar uma ferramenta. Uma boa descrição é específica quanto ao caso de uso, menciona quando a função deve e não deve ser chamada e descreve como será a saída. Descrições vagas fazem o modelo chamar a função errada ou perder oportunidades de chamar a função correta.
- Vaga: 'Obter dados meteorológicos.'
- Boa: 'Obter as condições meteorológicas atuais de uma cidade específica. Use quando o usuário perguntar explicitamente sobre o clima em um local mencionado. Retorna temperatura, condições e umidade.'
Modo estrito para garantir a conformidade com o esquema
O modo estrito da OpenAI para saídas estruturadas garante que o modelo produza um JSON que corresponda exatamente ao seu esquema — sem campos extras e sem campos obrigatórios ausentes. Ative-o definindo 'strict': true na definição da função. Observação: o modo estrito exige additionalProperties: false em todos os objetos do esquema.
strict_tool = {
'type': 'function',
'function': {
'name': 'classify_ticket',
'description': 'Classify a support ticket into category and priority.',
'strict': True, # Enable strict schema adherence
'parameters': {
'type': 'object',
'additionalProperties': False, # Required for strict mode
'properties': {
'category': {
'type': 'string',
'enum': ['billing', 'technical', 'account', 'other']
},
'priority': {
'type': 'string',
'enum': ['low', 'medium', 'high', 'urgent']
}
},
'required': ['category', 'priority']
}
}
}Testando seus esquemas de funções
Antes de implantar, teste cada esquema de função com entradas diversas: casos normais, casos extremos e entradas adversariais. Verifique se o modelo chama a função correta, produz tipos de argumentos válidos, lida corretamente com campos opcionais e respeita as restrições de enumeração. Use o OpenAI Playground para iterar rapidamente antes de escrever o código de produção.
Verificação rápida
Teste sua compreensão sobre a definição de esquemas de funções para a API da OpenAI.
Recapitulação da lição
Nesta lição, você aprendeu que: os esquemas de funções usam JSON Schema para definir tipos, descrições e restrições de parâmetros, tool_choice controla se o modelo deve chamar uma função ou pode escolher livremente e os modelos Pydantic podem gerar JSON Schema automaticamente para reduzir a escrita manual de esquemas. A seguir, aprenderemos a processar chamadas de ferramentas na sua aplicação, detectando-as, executando-as e enviando os resultados de volta.
Perguntas Frequentes
A aula “Definindo esquemas de funções para a API” é grátis?
Sim — o texto completo de “Definindo esquemas de funções para a API” é 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 Engineering Academy, atualize para CoddyKit PRO. O curso de AI Engineering Academy inclui 4 aulas no total.
O que vou aprender em “Definindo esquemas de funções para a API”?
Escreva definições JSON Schema para suas funções, passe-as no parâmetro tools e entenda como o modelo decide quando e como chamá-las. Você pratica AI Engineering Academy 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 Engineering Academy?
Nenhuma experiência prévia é necessária. AI Engineering Academy 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 “Definindo esquemas de funções para a API”?
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 Engineering Academy?
Sim. Cada aula de AI Engineering Academy 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
- Definindo esquemas de funções para a API
- Processando chamadas de ferramentas na sua aplicação
- Chamadas de funções em paralelo
- Criando uma interface de banco de dados em linguagem natural