Definir esquemas de herramientas (JSON Schema)

Los esquemas de herramientas son JSON Schema

Los tres campos obligatorios

Un esquema mínimo

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 JSON Schema

Enumeraciones para conjuntos cerrados

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 tipo array

tags_param = {
    'tags': {
        'type': 'array',
        'items': {'type': 'string'},
        'description': 'List of tags to filter by'
    }
}
print(tags_param)

Objetos anidados

filter_param = {
    'filter': {
        'type': 'object',
        'properties': {
            'min_price': {'type': 'number'},
            'in_stock': {'type': 'boolean'}
        }
    }
}
print(filter_param)

Los campos description son fundamentales

# 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

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 -> JSON Schema

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 estricto (OpenAI Structured Outputs)

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))

Importancia de la descripción

Repaso