Definindo esquemas de ferramentas (JSON Schema)
Escreva definições JSON Schema para os parâmetros das ferramentas, com tipos, descrições, enumerações e campos obrigatórios.
Definindo esquemas de ferramentas (JSON Schema) é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 2 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.
Os esquemas de ferramentas são esquemas JSON
OpenAI, Anthropic e a maioria dos outros provedores usam Esquema JSON para os parâmetros das ferramentas.
Se você já usou OpenAPI ou Swagger, já conhece 90% disso.
Os três campos obrigatórios
Toda definição de ferramenta contém:
name— identificador exclusivo (snake_case)description— o que a ferramenta faz e quando usá-laparameters— esquema JSON das entradas
Um esquema mínimo
Um objeto com um campo de texto obrigatório:
schema = {
'name': 'search_orders',
'description': 'Find orders by customer email',
'parameters': {
'type': 'object',
'properties': {
'email': {
'type': 'string',
'description': 'Customer email address'
}
},
'required': ['email']
}
}
import json
print(json.dumps(schema, indent=2))
Tipos de esquema JSON
string— textointeger,number— númerosboolean— verdadeiro/falsoarray— lista (também precisa deitems)object— dicionário (também precisa deproperties)
Enumerações para conjuntos fechados
Use enum quando houver exatamente N valores permitidos:
unit_param = {
'unit': {
'type': 'string',
'enum': ['C', 'F'],
'description': 'Temperature unit'
}
}
# The model will only ever output C or F
print(unit_param)
print("Allowed values:", unit_param['unit']['enum'])
Parâmetros de lista
Para entradas em lista, defina items:
tags_param = {
'tags': {
'type': 'array',
'items': {'type': 'string'},
'description': 'List of tags to filter by'
}
}
print(tags_param)
Objetos aninhados
Você pode aninhar objetos, mas mantenha os esquemas superficiais, com no máximo 2 ou 3 níveis, para garantir a confiabilidade do modelo:
filter_param = {
'filter': {
'type': 'object',
'properties': {
'min_price': {'type': 'number'},
'in_stock': {'type': 'boolean'}
}
}
}
print(filter_param)
Os campos de descrição são essenciais
O modelo escolhe as ferramentas e preenche os argumentos com base em description. Trate as descrições como documentação de API:
# Bad
bad = {'description': 'gets data'}
# Good
good = {'description': 'Fetch the most recent 50 orders for the given customer email. Returns order_id, status, total. Use this when the user asks about their order history or order status.'}
print("Bad description:", bad['description'])
print("Good description:", good['description'])
Matriz required
Marque explicitamente os campos obrigatórios. O modelo sempre preencherá esses campos; os opcionais só serão preenchidos quando forem relevantes:
tool_params = {
'parameters': {
'properties': {
'city': {'type': 'string'},
'unit': {'type': 'string', 'enum': ['C', 'F']}
},
'required': ['city']
}
}
print(tool_params)
print("Required fields:", tool_params['parameters']['required'])
Pydantic → esquema JSON
Você pode gerar esquemas automaticamente a partir de modelos Pydantic:
from pydantic import BaseModel, Field
class SearchArgs(BaseModel):
email: str = Field(description='Customer email')
limit: int = Field(50, description='Max orders to return')
schema = SearchArgs.model_json_schema()Modo estrito (saídas estruturadas da OpenAI)
Adicionar strict: true e additionalProperties: false garante que a saída do modelo corresponda exatamente ao esquema:
tools = [{
'type': 'function',
'function': {
'name': 'get_weather',
'strict': True,
'parameters': {
'type': 'object',
'properties': {'city': {'type': 'string'}},
'required': ['city'],
'additionalProperties': False
}
}
}]
import json
print(json.dumps(tools, indent=2))
Importância da descrição
Por que a description de uma ferramenta é tão importante?
Recapitulação
Os esquemas orientam o modelo. Boas descrições, enumerações para conjuntos fechados, matrizes required e o modo estrito são os mecanismos que aumentam sua confiabilidade.
Perguntas Frequentes
A aula “Definindo esquemas de ferramentas (JSON Schema)” é grátis?
Sim — o texto completo de “Definindo esquemas de ferramentas (JSON Schema)” é 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 “Definindo esquemas de ferramentas (JSON Schema)”?
Escreva definições JSON Schema para os parâmetros das ferramentas, com tipos, descrições, enumerações e campos obrigatórios. 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 2 de 4.
Quanto tempo leva a aula “Definindo esquemas de ferramentas (JSON Schema)”?
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
- Como funciona a chamada de funções
- Definindo esquemas de ferramentas (JSON Schema)
- Escolhendo ferramentas em tempo de execução
- Retornando resultados ao modelo