Un esquema de herramienta responde a una pregunta concreta: ¿tiene esta llamada la forma correcta? No responde si la llamada debería producirse. Un agente puede generar un reembolso perfectamente válido de cincuenta mil dólares, una consulta de base de datos válida para las filas de otro inquilino o un correo válido a un cliente que pidió que no se le molestara.
El modo estricto de OpenAI elimina una clase de ambigüedad. Con strict: true, cada objeto necesita additionalProperties: false, cada propiedad debe figurar como obligatoria y los campos opcionales se expresan con un tipo nulo. El modelo no puede colar un admin: true adicional en los argumentos. Es útil, pero sigue siendo sintaxis, no autorización.
Este tutorial añade la capa que falta: una barrera del lado del servidor que valida los argumentos contra un esquema estrecho y después comprueba identidad, propiedad y límites antes de cualquier efecto secundario. El código es lo bastante pequeño para probarlo por separado, y la misma función puede situarse entre el modelo y cada herramienta que expongas.
Paso 1 — haz que el esquema haga el trabajo barato
Empieza con una herramienta y haz que el esquema sea más estrecho que la base de datos. Enumeraciones en lugar de texto libre, patrones para identificadores y un máximo para el dinero.
TOOLS = {
"issue_refund": {
"type": "object",
"additionalProperties": False,
"required": ["order_id", "amount_cents", "reason"],
"properties": {
"order_id": {"type": "string", "pattern": "^ord_[A-Za-z0-9]{8,32}$"},
"amount_cents": {"type": "integer", "minimum": 1, "maximum": 50000},
"reason": {"type": "string", "enum": ["damaged", "late", "duplicate"]},
},
}
}Este esquema rechaza importes negativos, motivos de texto libre y campos desconocidos. Sigue permitiendo un reembolso válido por encima del importe que puede aprobar un agente de soporte, y por eso existe el paso dos.
Paso 2 — valida y autoriza en una sola barrera
Instala el validador con pip install jsonschema y después pon la política en una sola función. La función recibe el inquilino de quien llama y el inquilino al que pertenece el pedido; ambos deben coincidir antes de que se ejecute nada.
from __future__ import annotations
import json
from typing import Any
from jsonschema import Draft202012Validator
TOOLS: dict[str, dict[str, Any]] = {
"issue_refund": {
"type": "object",
"additionalProperties": False,
"required": ["order_id", "amount_cents", "reason"],
"properties": {
"order_id": {"type": "string", "pattern": "^ord_[A-Za-z0-9]{8,32}$"},
"amount_cents": {"type": "integer", "minimum": 1, "maximum": 50000},
"reason": {"type": "string", "enum": ["damaged", "late", "duplicate"]},
},
}
}
class Denied(Exception):
"""The call is well-formed but not allowed."""
def gate(
name: str,
args: dict[str, Any],
*,
principal_tenant: str,
order_tenant: str,
approval_limit_cents: int = 20000,
) -> dict[str, Any]:
schema = TOOLS.get(name)
if schema is None:
raise Denied(f"tool not allowed: {name}")
Draft202012Validator(schema).validate(args)
if order_tenant != principal_tenant:
raise Denied("order belongs to another tenant")
if name == "issue_refund" and args["amount_cents"] > approval_limit_cents:
raise Denied("refund above the auto-approval limit needs a human")
return {"ok": True, "tool": name, "args": args}El orden importa. Las herramientas desconocidas se rechazan antes de la validación. Los errores de esquema se lanzan como ValidationError. Los fallos de política lanzan Denied. Quien llama debe tratar ambos como una negativa, no como un motivo para reintentar con argumentos distintos.
Paso 3 — ejecuta la barrera antes del efecto secundario
No llames a la API de reembolsos y valides después. La barrera se ejecuta primero, y su valor de retorno es lo único que recibe el ejecutor.
if __name__ == "__main__":
valid = {"order_id": "ord_1234ABCD", "amount_cents": 4200, "reason": "late"}
print(gate("issue_refund", valid, principal_tenant="acme", order_tenant="acme"))
cases = [
("unknown tool", "delete_database", {}, "acme", "acme"),
("extra field", "issue_refund", {**valid, "admin": True}, "acme", "acme"),
("negative amount", "issue_refund", {**valid, "amount_cents": -1}, "acme", "acme"),
("wrong enum", "issue_refund", {**valid, "reason": "because"}, "acme", "acme"),
("other tenant", "issue_refund", valid, "acme", "globex"),
("over limit", "issue_refund", {**valid, "amount_cents": 49999}, "acme", "acme"),
]
for label, name, args, tenant, order_tenant in cases:
try:
gate(name, args, principal_tenant=tenant, order_tenant=order_tenant)
except Exception as exc:
print(f"{label}: {type(exc).__name__}: {str(exc)[:70]}")
else:
raise SystemExit(f"FAIL: {label} was allowed")Ejecútalo con python gate.py. La llamada válida imprime un resultado. Todos los casos adversariales imprimen una negativa, y el programa termina con un código distinto de cero si alguno se cuela.
Paso 4 — devuelve al modelo una negativa estructurada
El modelo necesita un fallo legible por máquina, no una traza de pila. En el bucle de Responses API, envía la negativa como salida de la herramienta y deja que el modelo se la explique al usuario o pida aprobación.
import json
import os
from openai import OpenAI
client = OpenAI()
model = os.environ["OPENAI_MODEL"] # usa el modelo actual disponible en tu cuenta
response = client.responses.create(
model=model,
tools=[{
"type": "function",
"name": "issue_refund",
"description": "Refund a paid order after verifying ownership.",
"strict": True,
"parameters": TOOLS["issue_refund"],
}],
input="Refund order ord_1234ABCD: the package arrived late.",
)
for item in response.output:
if item.type != "function_call":
continue
args = json.loads(item.arguments)
try:
result = gate(
item.name,
args,
principal_tenant="acme",
order_tenant=lookup_tenant(args["order_id"]),
)
except Exception as exc:
result = {"error": str(exc)}
response = client.responses.create(
model=model,
tools=[{
"type": "function",
"name": "issue_refund",
"description": "Refund a paid order after verifying ownership.",
"strict": True,
"parameters": TOOLS["issue_refund"],
}],
previous_response_id=response.id,
input=[{
"type": "function_call_output",
"call_id": item.call_id,
"output": json.dumps(result),
}],
)Esta es la forma del bucle, no una aplicación completa: lookup_tenant debe leer de tu propio almacén de pedidos, y el ejecutor que emite el reembolso debe ir después de que la barrera haya dado el visto bueno. Lo importante es que la negativa sea un dato normal. No se propaga como excepción por el orquestador ni provoca un reintento con un importe mayor.
Paso 5 — prueba lo que intentaría un atacante
Los casos unitarios anteriores cubren campos adicionales, límites, enumeraciones y acceso entre inquilinos. Añade los casos propios de tu dominio: un pedido eliminado, un reembolso ya emitido, una moneda que no coincide, un usuario que ha abandonado la organización. Después añade idempotencia. Si el modelo reintenta tras un tiempo de espera, la segunda llamada no debe emitir un segundo reembolso.
Registra el nombre de la herramienta, un hash de los argumentos, el inquilino, la decisión y el identificador de la llamada. No registres los argumentos completos si contienen datos personales.
Lo que esto no arregla
La inyección de prompts todavía puede dirigir al agente hacia una acción permitida. Si un documento le dice al modelo que reembolse un pedido, y el pedido pertenece a quien llama y está por debajo del límite, la barrera lo permitirá. Por eso la barrera es solo una capa: los conectores con privilegios mínimos, las herramientas de solo lectura cuando sea posible, la aprobación humana para acciones irreversibles, los límites de frecuencia y los registros de auditoría hacen el resto.
La regla no es «valida la salida del modelo». Es «nunca dejes que la salida del modelo tenga la última palabra antes de un efecto secundario». Un esquema estricto abarata la conversación. La barrera toma la decisión.