Gobernanza de la herramienta del agente a través de una puerta de enlace API de IA: alcances, aprobaciones, presupuestos y seguimientos de auditoría
Una arquitectura de referencia práctica para gobernar las herramientas de los agentes a través de una puerta de enlace API de IA: registros de herramientas, claves de alcance, puertas de aprobación, presupuestos por herramienta, listas permitidas de MCP y pistas de auditoría de herramientas/modelos unidos.
El riesgo del agente ya no se limita al aviso del modelo. Un agente de producción puede buscar archivos internos, consultar registros de clientes, llamar a un servidor MCP, ejecutar código, abrir un navegador, enviar correo electrónico, actualizar un CRM o activar un flujo de trabajo de facturación. La pregunta de gobernanza es: ¿a qué usuario, clave, modelo, agente y herramienta se le permitió realizar qué acción, con qué presupuesto, seguimiento de auditoría y ruta de reversión?
Si cada equipo maneja el acceso a las herramientas dentro de su propio código SDK, la política se dispersa entre variables de entorno, paneles de control de proveedores, middleware de aplicaciones y servidores MCP no documentados. Un patrón más seguro es tratar la ejecución de la herramienta del agente como un problema del plano de control y aplicarla a través de una puerta de enlace API de IA o un contenedor de ejecución de herramientas estándar que cada agente debe usar.
Este artículo separa hechos, recomendaciones y predicciones. Los hechos se extraen de la orientación pública actual: las 10 principales aplicaciones LLM de OWASP incluyen riesgos como la divulgación de información confidencial, vulnerabilidades de la cadena de suministro y agencia excesiva; El perfil de IA generativa del NIST para el marco de gestión de riesgos de IA hace hincapié en mapear, medir y gestionar los riesgos de IA generativa; La guía para agentes de OpenAI recomienda evaluar el riesgo de la herramienta mediante acceso de lectura/escritura, reversibilidad, permisos e impacto financiero; y la guía de autorización de MCP utiliza conceptos de autorización con alcance para recursos y operaciones confidenciales. Las recomendaciones siguientes son patrones de implementación, no requisitos universales.
El problema del lector: el acceso al modelo y el acceso a la herramienta se están confundiendo
En muchas de las primeras aplicaciones de LLM, una clave API respondía a una pregunta básica: ¿puede este servicio llamar a un modelo? Los agentes lo hacen demasiado grosero. Una clave que puede enviar finalización de chat no debería poder exportar automáticamente datos de clientes, ejecutar comandos de shell, publicar en Slack, modificar tickets, explorar sitios web arbitrarios ni enviar cambios de pago.
La capa de gobernanza necesita responder preguntas más específicas:
- ¿Qué inquilino, espacio de trabajo, usuario, cuenta de servicio o cliente revendedor inició la ejecución?
- ¿Qué modelo, plantilla de solicitud, versión del agente y esquema de herramienta se utilizaron?
- ¿La herramienta solicitada era de solo lectura, reversible, irreversible, externa, financiera o privilegiada?
- ¿Tenía el solicitante el alcance requerido?
- ¿La política de emergencia requirió, otorgó, denegó, expiró o eludió la aprobación?
- ¿Cuánto costó la herramienta, cuántas veces se llamó y cuánto presupuesto acumulado quedó?
- ¿Qué pruebas existen para la depuración, la revisión del cumplimiento y la reversión?
La arquitectura siguiente supone que la puerta de enlace ya recibe llamadas de modelo. Luego, la ejecución de la herramienta se puede enrutar a través de la misma puerta de enlace, a través de un servicio complementario o a través de una biblioteca estándar que informa a la puerta de enlace antes y después de cada llamada a la herramienta.
Arquitectura de referencia: una capa de gobernanza de herramientas a nivel de puerta de enlace
Un sistema práctico de gobernanza de agentes tiene siete componentes:
- Registro de herramientas: la lista autorizada de herramientas aprobadas, servidores MCP, funciones alojadas, herramientas de ejecución local y API internas.
- Capa de identidad y clave: claves de puerta de enlace, usuarios, inquilinos, cuentas de servicio, equipos y clientes revendedores.
- Motor de alcance: comprobaciones de políticas que deciden si una clave o un usuario puede invocar una capacidad de herramienta específica.
- Clasificador de riesgos: metadatos que describen el radio de la explosión, la sensibilidad de los datos, la reversibilidad, el impacto externo y la exposición a los costos.
- Flujo de trabajo de aprobación: aprobación humana o del sistema para acciones de alto riesgo antes de su ejecución.
- Libro mayor de límites de tasas y presupuesto: límites por herramienta y por agente, no solo límites de tokens por modelo.
- Almacén de auditoría y seguimiento: registros unidos para llamadas de modelos, llamadas de herramientas, aprobaciones, errores y resultados.
La decisión de diseño importante es hacer que la puerta de enlace sea el punto de decisión política incluso si la herramienta real se ejecuta en otro lugar. Por ejemplo, una herramienta de navegador puede ejecutarse en un trabajador de espacio aislado y una escritura de CRM puede ejecutarse dentro de un servicio interno. La puerta de enlace aún evalúa si la llamada está permitida, registra la decisión, rastrea el costo y devuelve una decisión de autorización o denegación firmada.
Paso 1: crear un registro de herramientas central
Un registro de herramientas es el inventario que evita que la “capacidad de agente desconocido” se convierta en la opción predeterminada. Cada herramienta debe tener un propietario, un nivel de riesgo y metadatos operativos. Un registro de registro mínimo puede verse así:
{ "tool_id": "crm.create_ticket", "display_name": "Crear ticket de soporte de CRM", "owner_team": "soporte-automatización", "execution_type": "internal_api", "server_url": "https://tools.internal.example/crm", "allowed_tenants": ["empresa", "soporte"],"allowed_models": ["general-grande", "general-rápido"], "risk_tier": "escritura_reversible", "data_classification": "customer_metadata", "required_scopes": ["herramienta:crm.create_ticket"], "approval_policy": "not_required_under_100_tickets_per_day", "default_timeout_ms": 8000, "max_cost_per_call_usd": 0,05, "max_calls_per_run": 3, "rollback_owner": "operaciones de soporte de guardia", "retention_policy": "redacted_30_days" }
Para los servidores MCP, el registro también debe incluir la URL del servidor, las herramientas anunciadas, la versión del esquema, el método de autorización, la fecha de la última revisión y si las nuevas herramientas están deshabilitadas de forma predeterminada. MCP mejora la interoperabilidad, pero la compatibilidad del protocolo no es lo mismo que la autorización de producción. Los recursos y operaciones confidenciales aún necesitan alcances explícitos, comprobaciones de ruta y aislamiento de inquilinos.
Campos de registro recomendados
- Nombre de la herramienta, ID canónico, propietario y contacto de guardia.
- Ubicación de ejecución: herramienta de proveedor alojado, servidor MCP, API interna, trabajador del navegador, ejecutor de código, trabajo en cola o herramienta SDK local.
- Inquilinos, equipos, usuarios, versiones de agentes y perfiles de modelo permitidos.
- Clasificación de datos: públicos, internos, metadatos del cliente, contenido del cliente, secretos, datos de pago, credenciales, datos regulados.
- Nivel de riesgo y reversibilidad.
- Alcances requeridos y política de aprobación.
- Tiempos de espera, límites de velocidad, llamadas máximas por ejecución, presupuesto de ejecución acumulativo y costo máximo por llamada.
- Modo de registro: carga útil completa prohibida, redactada, codificada, muestreada o retenida explícitamente.
- Instrucciones de reversión y ruta de escalada.
Paso 2: separar los alcances del modelo de los alcances de las herramientas
Una clave de puerta de enlace de producción debe expresar lo que puede hacer la persona que llama. El acceso al modelo y el acceso a las herramientas deben ser independientes. Por ejemplo:
modelo:chat modelo:incrustaciones herramienta:docs.search_readonly herramienta: crm.create_ticket herramienta:email.send_requires_approval herramienta: facturación.refund_blocked herramienta:code.execute_blocked
Esto evita que un chatbot de bajo riesgo se convierta en un agente de automatización accidental. También admite plantillas de roles:
- Asistente de desarrollador: chat de modelo, búsqueda de documentación, explicación del código, herramientas de escritura sin producción.
- Bot de soporte: búsqueda de clientes, creación de tickets, redacción de respuestas, aprobación requerida para envíos externos.
- Agente analista: consultas de almacén de datos de solo lectura con límites de filas, sin exportaciones de clientes de forma predeterminada.
- Agente administrador: operaciones con privilegios limitados, aprobación sólida, claves de corta duración, auditoría completa.
- Agente inquilino revendedor: acceso al modelo con alcance de inquilino, herramientas con alcance de inquilino, límites presupuestarios por cliente.
La recomendación es cerrar con error: se deniegan las herramientas desconocidas, los ámbitos faltantes deniegan la ejecución, las herramientas MCP anunciadas recientemente están inactivas hasta que se aprueben y las herramientas locales deben usar el mismo contenedor de políticas que las herramientas alojadas.
Paso 3: Clasificar las herramientas por radio de explosión
No todas las llamadas a herramientas necesitan la aprobación humana. La gobernanza debe ser proporcional al riesgo. Un modelo de clasificación útil es:
Esta clasificación debería estar visible en la revisión del código y en la interfaz de usuario del administrador. Las descripciones de las herramientas por sí solas no son suficientes porque los agentes pueden tratarlas como instrucciones. El motor de políticas debe basarse en los metadatos y alcances del registro, no solo en los nombres de las herramientas en lenguaje natural.
Paso 4: Agregar puertas de aprobación para acciones de alto riesgo
La aprobación debe ser específica. Si cada llamada a una herramienta requiere una persona, el agente queda inutilizable. Si ninguna llamada de herramienta requiere aprobación, el sistema puede otorgar agencia excesiva.
Un flujo de aprobación común:
- El agente solicita una llamada a la herramienta con argumentos estructurados.
- La puerta de enlace evalúa la identidad, el alcance, el nivel de riesgo, el presupuesto y la política.
- Si se requiere aprobación, la puerta de enlace devuelve un evento de aprobación pendiente en lugar de ejecutar la herramienta.
- La aplicación muestra una vista previa al usuario o envía una notificación de operaciones a un canal de aprobación.
- El aprobador puede aprobar, rechazar, editar argumentos si la política lo permite o solicitar aclaraciones.
- La puerta de enlace registra la decisión y ejecuta solo la versión aprobada.
La carga útil de aprobación debe mostrar la acción en términos humanos, no solo en JSON sin formato:
{ "approval_id": "appr_123", "agent_run_id": "run_456", "requested_by_user": "user_789", "tool_id": "correo electrónico.enviar", "risk_tier": "comunicación_externa", "summary": "Enviar una respuesta a [email protected] sobre el ticket #4812", "argumentos_redactados": { "a": "[email protected]", "subject": "Actualización del ticket n.º 4812", "body_hash": "sha256:..." }, "expires_at": "2026-08-09T12:30:00Z" }
La aprobación es más útil para comunicaciones externas, acciones financieras, escrituras irreversibles, administración privilegiada y exportaciones amplias de datos. Generalmente no es necesario para búsquedas de documentación pública de bajo volumen.
Paso 5: realizar un seguimiento de los presupuestos por herramienta y los límites de tarifas
Los presupuestos simbólicos no son suficientes. Un modelo económico puede desencadenar búsquedas costosas, sesiones de navegador, ejecuciones de código, llamadas API de terceros o largos ciclos de herramientas. La puerta de enlace debe realizar un seguimiento de al menos cuatro contadores:
- Recuento de llamadas por herramienta: llamadas máximas por ejecución, usuario, inquilino y ventana de tiempo.
- Costo por herramienta: cargos directos de terceros, costo del navegador/tiempo de ejecución, costo de búsqueda o estimación de contracargo interno.
- Costo acumulado de ejecución del agente: tokens de modelo más costos de herramientas.
- Profundidad del bucle: número máximo de iteraciones modelo-herramienta-modelo.
Cuando se alcanza un límite, la puerta de enlace debe evitar un fallo grave silencioso siempre que sea posible. Los patrones de degradación más seguros incluyen devolver un resumen del progreso, solicitar aprobación para continuar, reducir la profundidad de recuperación, poner en cola un trabajo en segundo plano o cambiar a un modo de solo lectura. La denegación estricta sigue siendo apropiada para herramientas bloqueadas, alcances faltantes, capacidades MCP desconocidas y acciones peligrosas.
Paso 6: unir la telemetría del modelo y la herramienta en un registro de auditoría
La depuración del agente falla cuando los registros del modelo se encuentran en un lugar y los registros de herramientas se encuentran en otro lugar. El registro de auditoría debe conectar la cadena completa:
- Inquilino, espacio de trabajo, usuario, cuenta de servicio y clave de puerta de enlace.
- ID del agente, versión del agente, versión de la plantilla de solicitud e ID del modelo.
- Nombre de la herramienta, versión del registro, URL del servidor o entorno de ejecución y hash del esquema.
- Hash de entrada de herramienta o entrada redactada, nunca cargas útiles sensibles sin procesar de forma predeterminada.
- Estado de aprobación, identidad del aprobador, marca de tiempo de aprobación y hash de argumento aprobado.
- Latencia, reintentos, errores del proveedor, errores de herramientas, costo del token, costo de la herramienta y resultado final.
- Referencia de reversión, si la acción cambió de estado.
La documentación de seguimiento del SDK de agentes de OpenAI incluye seguimientos para generaciones de LLM, llamadas de herramientas, transferencias, barreras de seguridad y eventos personalizados, lo que respalda un principio de observabilidad más amplio: los seguimientos de agentes deben incluir la actividad de las herramientas, no solo el uso de tokens y la latencia. Sin embargo, es posible que una única canalización de SDK no cubra todas las herramientas alojadas, rutas de ejecución local o API internas. La auditoría a nivel de puerta de enlace ayuda a normalizar los registros entre proveedores y marcos.
La privacidad importa. Los registros detallados mejoran la depuración y la revisión del cumplimiento, pero la retención de carga útil de herramientas y avisos sin procesar puede crear una nueva responsabilidad de seguridad. Redactar o hacer hash de entradas que contengan secretos, credenciales, datos de pago, datos personales o documentos de propiedad. Almacene cargas útiles sin procesar solo según una política de retención, controles de acceso y reglas de eliminación explícitas.
Paso 7: Trate los servidores MCP y las herramientas de terceros como dependencias de la cadena de suministro
Los servidores MCP y las herramientas de terceros deben pasar por el mismo proceso de revisión que las bibliotecas, los webhooks y las dependencias de infraestructura. Los controles recomendados incluyen:
- Mantenga una lista permitida de servidores MCP aprobados y orígenes de herramientas.
- Fijar versiones siempre que sea posible y registrar hashes de esquema.
- Requerir un propietario para cada servidor y herramienta de alto riesgo.
- Revise los nombres de las herramientas, las descripciones, los esquemas y los permisos antes de habilitarlas.
- Desactive las herramientas recién agregadas hasta que se revisen.
- Verifique los alcances requeridos por ruta o capacidad.
- Separe las credenciales de los inquilinos y evite los tokens compartidos entre los clientes.
- Ejecute herramientas que no sean de confianza o de alto riesgo en entornos sandbox con restricciones de red y de sistema de archivos.
El hecho de que una herramienta esté expuesta a través de un protocolo estándar no la hace segura. La capa de gobernanza aún necesita privilegios mínimos, autorización explícita, control de versiones y auditabilidad.
Lista de verificación de implementación
Diseño de políticas
- Defina plantillas de funciones para usuarios de agentes comunes y cuentas de servicio.
- Cree ámbitos separados para llamadas de modelo y llamadas de herramientas.
- Clasifique las herramientas por sensibilidad de los datos, reversibilidad, impacto externo, impacto financiero y nivel de privilegio.
- Establezca un comportamiento de denegación predeterminado para herramientas desconocidas y ámbitos faltantes.
- Defina reglas de aprobación solo para acciones de alto riesgo.
Cumplimiento de la puerta de enlace
- Requerir que cada agente llame a las herramientas a través de la puerta de enlace o de un contenedor de políticas firmado.
- Compruebe el inquilino, el usuario, la clave, el agente, el modelo, la herramienta, el alcance, el presupuesto y el estado de aprobación antes de la ejecución.
- Haga cumplir la profundidad máxima de llamada de herramientas y el costo de ejecución acumulativo.
- Registrar la versión del registro de la herramienta y el hash del esquema para cada llamada.
- Error cerrado cuando el motor de políticas no puede llegar a una decisión.
Auditoría y operaciones
- Únase a llamadas de modelo y llamadas de herramientas bajo un solo ID de ejecución de agente o seguimiento.
- Redactar o hacer sensibles a hash las entradas de la herramienta de forma predeterminada.
- Conserve la evidencia de aprobación con el registro de ejecución final.
- Exponer el coste por herramienta y los análisis de límite de velocidad a los administradores.
- Propietarios de reversión de documentos para herramientas que mutan el estado.
Compensaciones que se pueden esperar
Coherencia frente a esfuerzo de integración. La gobernanza a nivel de puerta de enlace ofrece una aplicación coherente en todos los modelos, SDK y equipos. El costo es la adopción: los desarrolladores deben dirigir la ejecución de la herramienta a través de la ruta aprobada en lugar de llamar a las herramientas directamente desde el código de la aplicación.
Menores privilegios frente a complejidad de políticas. Los alcances detallados reducen el radio de explosión, pero requieren plantillas, convenciones de nomenclatura y una limpieza periódica. Sin plantillas, los equipos pueden conceder permisos en exceso para avanzar más rápido.
Aprobación versus autonomía. La aprobación humana reduce el riesgo de acciones irreversibles, pero añade latencia. Utilice aprobaciones para herramientas de alto riesgo, no para todas las consultas o búsquedas.
Auditabilidad versus exposición de datos. Los registros enriquecidos ayudan con la respuesta a incidentes y la depuración. El registro de carga útil sin procesar puede exponer secretos y datos personales. La redacción, el hash, la retención configurable y la revisión de acceso no son detalles opcionales.
Límites estrictos versus finalización de tareas. Los límites de costo por herramienta evitan que los agentes se descontrolen. También pueden interrumpir un trabajo legítimo de larga duración. Proporcione rutas de continuación, como aprobación para continuar, colas en segundo plano o resultados parciales resumidos.
Predicciones: hacia dónde se dirige este patrón
Predicción: la gobernanza de agentes se centrará más en la identidad. Los equipos preguntarán con menos frecuencia "¿qué modelo utilizó este?" y más a menudo "¿qué persona o servicio autenticado permitió la acción de esta herramienta?"
Predicción: los registros de herramientas serán tan normales como los registros de modelos. A medida que se multiplican los servidores MCP, las API internas y las herramientas alojadas, los equipos de producción necesitarán un inventario de capacidades, propietarios, esquemas y niveles de riesgo permitidos.
Predicción: la gestión de costes pasará de los informes simbólicos únicamente a los informes a nivel de acción. La parte más costosa de la ejecución de un agente puede ser la recuperación, la automatización del navegador, la ejecución de código o API de terceros en lugar de la llamada al modelo en sí.
Conclusión procesable
Comience con una regla: una clave de modelo no es una clave de herramienta. Luego construye hacia afuera. Cree un registro de herramientas aprobadas, asigne propietarios y niveles de riesgo, exija alcances explícitos, agregue aprobaciones solo cuando la acción tenga un radio de explosión significativo, aplique presupuestos por herramienta y una eventos de modelo y herramienta en un solo registro de auditoría.
El objetivo no es dejar a los agentes impotentes. El objetivo es hacer que su poder sea legible, con alcance, reversible cuando sea posible y responsable. Esa es la base práctica para la gobernanza de API en equipo a medida que los agentes pasan de responder preguntas a tomar acciones.