Los controles del gateway de agentes de IA son las reglas operativas que deciden qué puede invocar un agente, cuánto puede gastar, qué evidencia debe registrarse y cuándo la ejecución debe pausarse, recurrir a un plan B o detenerse. Sin esos controles, un gateway de agentes se convierte en una forma más rápida de ocultar la proliferación de herramientas, el gasto descontrolado de tokens y los fallos de producción poco claros.
El objetivo no es envolver a cada agente en un proceso. El objetivo es hacer que el comportamiento del agente sea inspeccionable antes de que llegue a los usuarios de producción. Un agente de soporte que puede buscar pedidos, un agente de codificación que puede editar archivos y un agente de finanzas que puede comparar facturas no deberían compartir el mismo acceso a herramientas, presupuesto, registro o política de detención.
Utilice esta guía para diseñar los controles del gateway de agentes de IA como políticas, campos de evidencia y pruebas de aceptación. Luego, valide el modelo actual de Flatkey, el enrutamiento, el uso y la evidencia de facturación en la página de precios de Flatkey antes de su implementación.
Los controles del gateway de agentes de IA comienzan con un límite de política
Un gateway de agentes se sitúa entre los entornos de ejecución de los agentes, las API de los modelos, las herramientas internas y la revisión financiera. Eso lo convierte en un buen lugar para estandarizar cuatro decisiones:
| Área de control | Pregunta del gateway | Evidencia de producción |
|---|---|---|
| Uso de herramientas | ¿Qué herramientas puede invocar este flujo de trabajo, con qué argumentos y bajo la aprobación de quién? | Nombre de la herramienta, versión del esquema, argumentos, estado de aprobación, estado del resultado |
| Presupuestos | ¿Cuánto gasto en entrada, salida, razonamiento, herramientas, reintentos y planes B está permitido? | Recuentos de tokens, coste de la solicitud, clave del propietario, resultado del presupuesto, gasto en planes B |
| Registros | ¿Qué sucedió, qué ruta lo atendió y qué se puede revisar más tarde? | ID de la solicitud, flujo de trabajo, modelo, ruta, invocaciones de herramientas, motivo de la detención, código de error |
| Condiciones de detención | ¿Cuándo debería la ejecución finalizar, reintentar, solicitar aprobación, recurrir a un plan B o fallar de forma segura? | Condición de detención, motivo del plan B, decisión del revisor, estado final |
Estos controles del gateway de agentes de IA deben revisarse como una política de infraestructura, no como el texto de un prompt. El prompt puede explicar la intención, pero la política del gateway debe hacer cumplir lo que sucede cuando el modelo solicita una herramienta sensible, excede un presupuesto, recibe un resultado de herramienta inesperado o entra en bucle.
Controles de uso de herramientas: permita menos herramientas de las que el agente conoce
La invocación de herramientas es potente porque conecta los modelos con sistemas reales. También es donde un agente pasa de la sugerencia a la acción. La documentación sobre la invocación de funciones de OpenAI describe las invocaciones de herramientas como un flujo de varios pasos: el modelo solicita una herramienta, su aplicación la ejecuta y el resultado de la herramienta se devuelve al modelo. La documentación sobre el uso de herramientas de Anthropic describe de manera similar cómo Claude devuelve bloques tool_use, siendo el código de la aplicación responsable de la ejecución. La invocación de funciones de Google Gemini también depende de funciones declaradas e invocaciones de funciones generadas por el modelo.
Ese patrón común es importante para los controles del gateway de agentes de IA: el modelo no debe ejecutar la herramienta directamente. Su gateway o entorno de ejecución debe decidir si la herramienta solicitada está permitida, si los argumentos coinciden con la política, si se requiere aprobación y si es seguro devolver el resultado de la herramienta.
Utilice una política de herramientas de tres capas:
- Catálogo de herramientas: el conjunto completo de herramientas que existen en la organización.
- Lista de permitidos del flujo de trabajo: el conjunto más pequeño de herramientas que una ruta de agente específica puede invocar.
- Restricción a nivel de turno: las herramientas disponibles para esta solicitud después de las comprobaciones de rol, inquilino, entorno, presupuesto y riesgo.
Por ejemplo, un agente de atención al cliente puede tener acceso a lookup_order, search_policy y open_ticket en modo normal. No debería recibir issue_refund, cancel_contract o delete_account hasta que el flujo de trabajo alcance una ruta de escalada aprobada.
El control debe ser explícito:
workflow: support_resolution_agent
tool_policy:
default_mode: deny
allowed_tools:
- lookup_order
- search_policy
- open_ticket
approval_required:
- issue_refund
- cancel_subscription
blocked_tools:
- export_customer_database
schema_rules:
require_strict_arguments: true
reject_unknown_fields: true
log_redacted_arguments: true
on_violation:
action: stop
user_message: ask_for_human_reviewLa guía de invocación de funciones de OpenAI recomienda descripciones de funciones claras, esquemas JSON, modo estricto donde sea compatible y mantener un número reducido de funciones disponibles inicialmente. Eso no es solo un consejo para el rendimiento del modelo. También es un control del gateway de agentes: menos herramientas expuestas significa menos estados no válidos que revisar después de un incidente.
Controles de presupuesto: limite toda la ejecución, no solo una invocación al modelo
El coste de un agente rara vez proviene de una única solicitud limpia. Proviene de los esquemas de las herramientas, el historial de la conversación, el contexto de recuperación, los tokens de razonamiento, los resultados de las herramientas, los reintentos, los modelos de respaldo y los intentos repetidos tras fallos parciales.
Los controles de presupuesto del gateway de agentes de IA deben cubrir toda la ejecución:
| Superficie del presupuesto | Qué limitar | Por qué es importante |
|---|---|---|
| Presupuesto de solicitud | tokens de entrada, tokens de salida, tokens de razonamiento, llamadas máximas al modelo | Evitar que un solo turno se convierta en un evento de gasto sorpresa |
| Presupuesto de herramientas | número de llamadas a herramientas, tamaño del resultado de la herramienta, gasto en API externas | Evitar bucles de herramientas y extracciones de datos costosas |
| Presupuesto de reintentos | número de reintentos, códigos de estado reintentables, ventana de backoff | Separar la resiliencia de la repetición incontrolada |
| Presupuesto de respaldo | número de modelos de respaldo, techo de costo de respaldo, motivo del respaldo | Evitar que la fiabilidad enmascare una ruta principal rota |
| Presupuesto del propietario | límite de proyecto, equipo, cliente, entorno, clave o flujo de trabajo | Hacer que el gasto sea revisable por finanzas e ingeniería |
El gateway debe fallar en estado cerrado cuando se excede un límite estricto. Puede resumir, solicitar una reducción del alcance, poner en cola una revisión humana o devolver un error controlado. No debe enviar silenciosamente un prompt más grande, cambiar a una ruta más costosa ni seguir reintentando.
Utilice esta forma de presupuesto:
budget_policy:
workflow: invoice_reconciliation_agent
owner_key: finance_ops
per_request:
max_input_tokens: 32000
max_output_tokens: 4000
max_model_calls: 4
max_tool_calls: 5
per_session:
max_total_tokens: 90000
max_total_cost_usd: reviewed_threshold
retry:
max_attempts: 2
retryable_statuses: [408, 409, 429, 500, 502, 503, 504]
fallback:
max_fallbacks: 1
require_reason: true
on_over_budget:
action: stop_or_request_scope_reductionAquí es donde la superficie pública del producto de Flatkey es relevante. La página de inicio actual de Flatkey posiciona la plataforma en torno al acceso unificado a modelos, enrutamiento, facturación, análisis de uso y controles operativos. La página de precios actual describe recargas prepagas, análisis de uso, controles de costos, registros de solicitudes, una factura única para todos los proveedores y rutas de adquisición para equipos. Trate eso como evidencia de planificación pública actual y luego ejecute su propia prueba en el panel de control antes de la producción.
Registros: registre evidencia, no solo prompts sin procesar
Los registros de los agentes deben responder a dos preguntas: ¿qué ocurrió en tiempo de ejecución y quién puede demostrar que la política funcionó?
La documentación de observabilidad del AI Gateway de Vercel describe los registros del gateway para gastos, uso de modelos, métricas de observabilidad, resúmenes de solicitudes, claves de API y registros de solicitudes. La documentación de observabilidad del SDK de Agentes de OpenAI describe trazas que pueden incluir llamadas a modelos, llamadas a herramientas, transferencias, barreras de seguridad y spans personalizados. Esos ejemplos apuntan al mismo requisito operativo: los gateways de agentes necesitan registros que conecten el comportamiento del modelo con las decisiones de ruta, herramienta, presupuesto y detención.
Para los controles del gateway de agentes de IA, registre como mínimo estos campos:
| Campo | Ejemplo | Por qué es importante |
|---|---|---|
request_id | UUID generado por el gateway | Une los registros del modelo, la herramienta, la facturación y el soporte |
workflow_class | support_agent, code_agent, finance_agent | Agrupa la política y las pruebas de aceptación |
owner_key | equipo, aplicación, cliente, entorno | Admite la asignación de gastos y la revisión de abusos |
requested_model | alias del modelo o nombre de la ruta | Muestra lo que la aplicación solicitó |
served_model | proveedor/modelo real | Muestra lo que el gateway sirvió |
tool_calls | nombre, versión del esquema, argumentos redactados, estado | Demuestra el comportamiento de la política de la herramienta |
usage | tokens de entrada, salida, razonamiento, caché, totales | Conecta el comportamiento con el costo |
budget_result | permitido, advertido, bloqueado | Demuestra que la puerta de control de costos se ejecutó |
stop_condition | completed, max_steps, over_budget, approval_required | Explica cómo terminó la ejecución |
fallback_reason | timeout, 429, provider_error, quality_gate | Separa la recuperación de la desviación |
No registre todo para siempre solo porque sea fácil. Los datos de los clientes, los prompts, los resultados de las herramientas y los archivos pueden contener información sensible. Un diseño de registro duradero debe definir la redacción, la retención, la revisión de acceso, las necesidades de exportación y los procedimientos de incidentes. El gateway debe almacenar suficiente evidencia para depurar y conciliar el uso sin convertir cada solicitud en un archivo de datos incontrolado.
Condiciones de detención: defina el final de la ejecución antes de que el modelo comience
Las condiciones de detención no son solo secuencias de detención del modelo. Son las reglas que finalizan de forma segura la ejecución de un agente.
Las API de los proveedores exponen diferentes superficies de respuesta y detención. La API de Mensajes de Anthropic expone campos de stop_reason como el uso de herramientas, el final del turno, el máximo de tokens y las secuencias de detención en su documentación. La documentación de las barreras de seguridad del SDK de Agentes de OpenAI enmarca las barreras de seguridad y la revisión humana como controles que deciden cuándo una ejecución continúa, se pausa o se detiene. En producción, su gateway debe normalizar esos estados específicos del proveedor en un estado de flujo de trabajo que su equipo entienda.
Utilice una matriz de detención:
| Condición de detención | Acción del gateway | Comportamiento de cara al usuario | Evidencia requerida |
|---|---|---|---|
| Completado | Devolver respuesta final | Respuesta normal | modelo final, uso, sin herramientas no resueltas |
| Se requiere aprobación de la herramienta | Pausar | "Esta acción necesita revisión" | llamada a la herramienta, argumentos, aprobador, decisión |
| Presupuesto excedido | Detener o solicitar reducción del alcance | "Limite la solicitud" | campo de presupuesto, umbral, clave de propietario |
| Máximo de pasos alcanzado | Detener | "No se puede completar en esta ejecución" | recuento de pasos, última acción, señal de bucle |
| Error de la herramienta | Reintentar, recurrir a fallback o detener | Ruta de fallo clara | estado de la herramienta, clase de error, recuento de reintentos |
| Tiempo de espera del proveedor agotado | Reintentar o recurrir a fallback | Respuesta degradada pero controlada | ruta, tiempo de espera, motivo del fallback |
| Infracción de la política | Detener | Rechazar o derivar a un humano | política activada, muestra redactada |
| Baja confianza o falta de evidencia | Hacer seguimiento o escalar | "Se necesita más información" | campo faltante, resultado de la evaluación |
El punto importante es que cada estado terminal tiene un nombre. Si los únicos estados son "éxito" y "error", los equipos no pueden saber si el agente respetó la política o simplemente se detuvo por accidente.
Una plantilla práctica de controles del gateway de agentes de IA
Utilice un archivo de políticas que los equipos de ingeniería, seguridad, finanzas y producto puedan revisar juntos:
policy_name: ai_agent_gateway_controls_v1
owner:
team: ai_platform
reviewers:
- engineering
- finance
- security
workflow_classes:
support_agent:
route: balanced_text_tool_route
allowed_tools: [lookup_order, search_policy, open_ticket]
approval_tools: [issue_refund, cancel_subscription]
max_tool_calls: 5
max_model_calls: 4
code_agent:
route: code_review_route
allowed_tools: [read_repo, search_repo, propose_patch]
approval_tools: [apply_patch, run_shell_command]
max_tool_calls: 12
max_model_calls: 8
budget_rules:
require_owner_key: true
block_when_owner_budget_exceeded: true
require_fallback_reason: true
log_rules:
capture_request_id: true
capture_requested_and_served_model: true
capture_tool_call_status: true
redact_sensitive_arguments: true
stop_rules:
max_steps: 12
max_retries_per_tool: 1
on_policy_violation: stop
on_approval_required: pause
acceptance_tests:
- blocked_tool_is_not_executed
- over_budget_request_fails_closed
- approval_tool_pauses_run
- fallback_records_reason
- request_log_contains_usage_and_stop_conditionEste archivo no reemplaza el código de la aplicación. Le da al código un contrato que hacer cumplir y a los revisores un artefacto concreto para inspeccionar.
Pruebas de aceptación antes de la producción
Ejecute pruebas de aceptación para cada clase de flujo de trabajo antes de que el tráfico se active:
- Envíe una solicitud normal y confirme que solo se exponen las herramientas permitidas.
- Solicite una herramienta bloqueada y confirme que la herramienta no se ejecuta.
- Solicite una herramienta que requiera aprobación y confirme que la ejecución se pausa con un estado reanudable.
- Envíe un prompt demasiado grande y confirme que el gateway se detiene o solicita una reducción del alcance.
- Provoque un error de la herramienta y confirme que se registran el recuento de reintentos, el motivo del fallback y el estado final.
- Fuerce un tiempo de espera agotado del proveedor y confirme que el fallback se mantiene dentro del presupuesto de fallback.
- Active el máximo de pasos y confirme que la ejecución no entra en bucle.
- Confirme que los registros de solicitud muestran la clave del propietario, el modelo solicitado, el modelo servido, el uso, el estado de la herramienta, el resultado del presupuesto y la condición de detención.
- Realice una conciliación financiera de muestra a partir de los registros de solicitud con la factura o el movimiento del saldo prepagado.
- Vuelva a ejecutar la misma prueba después de cambiar modelos, herramientas, prompts o la política de enrutamiento.
Combine este artículo con las guías de Flatkey sobre arquitectura de gateway de API de IA, arquitectura de gateway de API de LLM, balanceo de carga y conmutación por error de API de IA y diseño de políticas de enrutamiento de modelos. La arquitectura del gateway decide dónde residen los controles; las pruebas de aceptación demuestran que funcionan.
Dónde encaja Flatkey
Flatkey no debería ser el único lugar donde exista su política de agentes. Mantenga la política en el código, la configuración o un repositorio de control interno. Utilice Flatkey como la superficie del gateway donde los equipos pueden centralizar el acceso a los modelos, la revisión de rutas, la visibilidad del uso, los registros de solicitudes, los controles de costos, el saldo prepagado y la revisión de la facturación.
Un despliegue práctico de Flatkey se ve así:
- Elija un flujo de trabajo de agente con herramientas y propietarios conocidos.
- Defina las herramientas permitidas, las herramientas de aprobación, los límites de presupuesto, los campos de registro y las condiciones de detención.
- Consulte las opciones actuales de modelos y precios en la página de precios de Flatkey.
- Ejecute las pruebas de aceptación con una clave que no sea de producción.
- Revise los registros para ver el modelo solicitado, el modelo servido, el uso, la decisión de enrutamiento, el motivo del fallback y la condición de detención.
- Mueva solo el flujo de trabajo probado a producción.
- Añada nuevas herramientas y rutas de fallback una fila de la política a la vez.
Cuando la prueba sea exitosa, obtenga una clave y mantenga el primer despliegue limitado. Los controles más sólidos del gateway de agentes de IA son aburridos en producción: cada llamada a una herramienta tiene una razón, cada decisión de presupuesto tiene un rastro, cada fallo tiene una condición de detención con nombre y cada revisor puede ver lo que sucedió.
Preguntas frecuentes
¿Qué son los controles del gateway de agentes de IA?
Los controles del gateway de agentes de IA son políticas que rigen el acceso a herramientas, los presupuestos, los registros, el comportamiento de respaldo y las condiciones de detención para los flujos de trabajo de agentes que llaman a modelos y herramientas a través de un gateway.
¿Son los controles del gateway de agentes de IA lo mismo que el enrutamiento de modelos?
No. El enrutamiento de modelos decide qué modelo o proveedor debe atender una solicitud. Los controles del gateway de agentes de IA deciden si el agente puede llamar a una herramienta, gastar más presupuesto, reintentar, recurrir a un respaldo, pausar para su aprobación o detenerse.
¿Qué se debe registrar para el uso de herramientas por parte del agente?
Registre el ID de la solicitud, la clase del flujo de trabajo, la clave del propietario, el modelo solicitado, el modelo servido, el nombre de la herramienta, la versión del esquema, los argumentos redactados, el estado del resultado, el uso, el resultado del presupuesto, el motivo del respaldo y la condición de detención.
¿Deberían las herramientas sensibles estar disponibles para el modelo todo el tiempo?
No. Mantenga el catálogo completo de herramientas separado de la lista de flujos de trabajo permitidos. Las herramientas sensibles deberían requerir aprobación, un alcance más limitado o una ruta de escalada separada.
¿Cómo se deben gestionar los sobrecostes del presupuesto?
Los sobrecostes estrictos del presupuesto deben provocar un fallo seguro. El gateway puede solicitar una reducción del alcance, resumir, poner en cola para revisión o devolver un error controlado, pero no debe cambiar silenciosamente a una ruta más costosa.
¿Cómo ayuda Flatkey con los controles del gateway de agentes de IA?
Flatkey ofrece a los equipos una única superficie de gateway para el acceso a modelos, la revisión del enrutamiento, la visibilidad del uso, los registros de solicitudes, los controles de costos, el saldo prepago y la revisión de la facturación. Utilice esa superficie junto con políticas como código (policy-as-code) y pruebas de aceptación para los flujos de trabajo de agentes en producción.
