Las claves de agente necesitan presupuestos de riesgo

El repositorio shuriken-skills de Shuriken empaqueta instrucciones para Claude Code, Codex CLI, GitHub Copilot CLI, Gemini CLI, Cursor, OpenCode y agentes compatibles con AGENTS.md.¹ El repositorio también dirige a esos agentes hacia una plataforma donde las claves de agente pueden leer datos de mercado, inspeccionar billeteras, solicitar cotizaciones y ejecutar operaciones cuando el usuario concede esa capacidad.²

Lo importante no son las operaciones financieras. Lo importante es el patrón: los agentes ahora necesitan credenciales para herramientas que pueden producir efectos externos reales. Una clave de agente no debería comportarse como una clave API normal. Debería comportarse como un presupuesto de riesgo.

Una clave de agente es un objeto de autoridad limitada. Debe decir qué puede hacer el agente, qué no puede hacer, cuánto riesgo puede generar, cómo pueden los operadores inspeccionar sus acciones y con qué rapidez alguien puede pausarla, rotarla o revocarla. Las instrucciones de entrada ayudan, pero los límites del lado del servidor sostienen la frontera.

Resumen

MCP y las habilidades portátiles facilitan que los agentes se conecten a sistemas externos.³⁴ Esa portabilidad eleva la importancia de las credenciales. La documentación de Shuriken describe la forma correcta de controlar herramientas peligrosas: crear una clave de agente, conceder solo los permisos necesarios, aplicar límites del lado del servidor, registrar la actividad y revocar la clave cuando la integración ya no la necesite.²⁵⁶ La investigación reciente sobre privilegio mínimo apunta en la misma dirección: las habilidades pueden realizar acciones que exceden el alcance mínimo para una tarea específica, así que los permisos deben depender de la tarea en lugar de aplicarse a todo el paquete.⁹

La lección va más allá de las finanzas. Cualquier herramienta de agente que envíe dinero, publique contenido, cambie infraestructura, escriba a clientes o toque datos privados necesita una clave acotada con un presupuesto de riesgo. Ese presupuesto debe estar por debajo del modelo y por debajo del archivo de habilidad. El servidor debe rechazar acciones no autorizadas incluso cuando el agente las pida con seguridad.

Ideas clave

• Para quienes crean herramientas de agente: diseña las credenciales como presupuestos de capacidad, no como tokens portadores de uso general.
• Para equipos de seguridad: separa los alcances de lectura de los alcances de escritura o ejecución, y luego aplica límites de gasto, frecuencia y objeto en el lado de ejecución.
• Para equipos de producto: muestra los registros de actividad y los controles de revocación en la UI principal, no en una página de configuración escondida.
• Para quienes crean MCP: trata la distribución de herramientas y la autoridad de credenciales como planos distintos. Las habilidades pueden enseñar. Las claves deben restringir.
• Para operadores: empieza en modo de solo lectura, prueba la ruta de integración y agrega acceso de escritura solo cuando ya exista un plan de respuesta.

Las habilidades distribuyen instrucciones. Las claves distribuyen autoridad.

El repositorio shuriken-skills muestra el nuevo patrón de distribución. Un solo árbol de código fuente contiene Markdown de habilidades, manifiestos de plugin para Claude y Codex, un manifiesto de plugin para Cursor, un archivo de extensión para Gemini, un plugin de OpenCode, un crate de Rust y una ruta alternativa con AGENTS.md.¹⁷

Ese empaquetado importa porque las instrucciones de agente ahora viajan entre clientes. Un proveedor puede enseñar a Codex, Claude Code, Cursor, Gemini y otras herramientas cómo integrarse con la misma API. La documentación de MCP describe las habilidades de agente como conjuntos portátiles de instrucciones que dan conocimiento de dominio a los asistentes de programación, incluidas decisiones de diseño sobre el modelo de despliegue, los flujos de autenticación y los patrones de herramientas.⁴ Escribí sobre el lado de la distribución en Las habilidades de agente necesitan gestores de paquetes; el lado de seguridad empieza cuando esos paquetes piden autoridad real.

Las instrucciones portátiles resuelven un problema y crean otro. Ayudan a que un agente aprenda la ruta de integración correcta. No vuelven segura la acción resultante. Una habilidad puede decirle al modelo que use privilegio mínimo. Una instrucción de entrada puede decir “ten cuidado”. Un README puede explicar los alcances recomendados. Ninguno de esos controles detiene una solicitud autenticada después de que el modelo decide enviarla.

Esa tensión coincide con el problema más amplio de MCP en Los servidores MCP son la nueva superficie de ataque: el acceso a herramientas amplía la superficie de acción más rápido de lo que los viejos hábitos de aprobación pueden seguir. Las habilidades de agente vuelven portátil la ruta de instrucciones. El sistema de claves tiene que mantener estrecha la ruta de autoridad.

Por eso las credenciales necesitan su propio diseño. El archivo de habilidad vive en el plano de instrucciones. La clave de agente vive en el plano de autoridad. Mezclar esos planos crea un sistema frágil: el mismo texto que le enseña al agente qué hacer también intenta impedir que haga demasiado.

La frontera debe estar en el servidor.

El patrón de Shuriken es un presupuesto de riesgo

La documentación de Agent Kit de Shuriken describe una clave de agente como el objeto que controla lo que una herramienta de IA puede hacer, desde leer precios de tokens hasta ejecutar operaciones, con límites aplicados del lado del servidor antes de que el agente empiece a actuar.⁵ La página de permisos nombra seis categorías de permisos y afirma que las llamadas fuera del alcance concedido fallan con un error de autorización.⁶

Ese encuadre también evita un error común en las demos públicas de agentes: tratar el código abierto, las instrucciones visibles o un manifiesto de plugin legible como si fueran la frontera. La apertura puede ayudar a revisar, pero el código abierto no es una frontera de seguridad. La frontera vive donde las acciones no autorizadas fallan.

Ese patrón tiene cinco partes:

Esa es la forma correcta para herramientas de agente de alto riesgo. El diseño no depende de que el modelo se vuelva sabio. El diseño asume que el modelo puede equivocarse, actuar con exceso de confianza, quedar comprometido por una entrada o simplemente recibir una mala instrucción. El servidor sigue aplicando la clave.

Copiaría el patrón de control, no el dominio. Una clave de despliegue, una clave de publicación, una clave para mensajes a clientes, una clave para reembolsos de Stripe y una clave de operaciones financieras necesitan la misma pregunta: ¿cuál es el daño máximo que esta clave puede causar antes de que una persona lo note?

Los límites del servidor superan las promesas de las instrucciones

La documentación de OpenAI Agents SDK presenta las barreras de seguridad como verificaciones que pueden ejecutarse alrededor de un agente, incluidas barreras de entrada y salida con disparadores.⁸ Las barreras ayudan porque detectan riesgos antes o después de la ejecución del modelo. Aun así, ocupan una capa distinta de la autoridad de credenciales.

Una barrera de salida puede señalar una mala acción propuesta. Un límite de clave del lado del servidor puede rechazar la acción incluso si la barrera no la detecta. Esa diferencia importa cuando la acción deja de ser solo texto.

Piensa en una herramienta que puede publicar una entrada, enviar un correo, cambiar un registro DNS, fusionar un pull request o ejecutar una operación. Una regla de instrucciones puede decir “pide permiso primero”. Una barrera puede buscar texto de alto riesgo. Una clave del lado del servidor puede aplicar el límite real:

La regla de instrucciones puede fallar en silencio. La frontera a nivel de clave crea un rechazo observable. Ese rechazo se vuelve evidencia. El agente intentó exceder su alcance. El servidor se negó. El operador puede inspeccionar la solicitud fallida y decidir si la integración necesita una clave nueva, un flujo de trabajo más estrecho o un paso de aprobación humana.

Esa es la misma lógica detrás de La puerta de evidencia: la confianza debe venir de pruebas observables, no de seguridad retórica. Una respuesta final que dice “me mantuve dentro de los límites” vale menos que un registro del servidor que muestra qué límite se activó.

También convierte la respuesta final en algo más parecido a un paquete de revisión. Los paquetes de revisión son la nueva respuesta final sostiene que el trabajo serio con agentes necesita artefactos de evidencia. Los rechazos de credenciales, los registros de actividad y los cambios de claves acotadas son la versión de seguridad de ese artefacto.

La forma mínima de las credenciales de agente

Cualquier credencial de agente que pueda afectar el mundo exterior debería tener seis propiedades.

Las habilidades de Shuriken dicen lo mismo en lenguaje de integración: crea una clave por integración, concede el alcance mínimo, mantén las claves en secreto, rótalas después de una sospecha de compromiso y revoca integraciones retiradas.⁷ Su habilidad de definición de alcance también separa los alcances de lectura de los alcances de operación y advierte contra claves amplias “por si acaso”.⁷

El vocabulario de investigación está alcanzando al patrón de producto. El artículo de SkillScope describe el exceso de privilegios como algo condicionado por la tarea: la misma acción de una habilidad puede ser válida para una solicitud de usuario y excesiva para otra.⁹ Sus autores reportan 7.039 habilidades con comportamientos de privilegio excesivo validados y una reducción del 88,56 % en instancias activadas de acciones con privilegios excesivos después de restringir los privilegios mediante su marco.⁹ No necesitas copiar ese mecanismo exacto para aceptar la lección de producto. Las credenciales de agente deben reflejar el trabajo actual, no el trabajo más grande que la herramienta pueda imaginar.

Esa guía debería volverse diseño normal de productos con agentes. Las claves API amplias tenían sentido cuando un servicio backend poseía una ruta de código estrecha. Los agentes no se comportan como una sola ruta de código estrecha. Planifican, reintentan, combinan herramientas, resumen fallas, llaman scripts auxiliares y responden a entradas externas. La credencial debe asumir más variación de comportamiento que un token de servicio normal.

Esa variación explica por qué La búsqueda de código con agentes tiene un problema de presupuesto de tokens importa incluso en un artículo sobre credenciales. Los agentes suelen decidir con contexto parcial. Una clave estrecha le da al sistema una segunda oportunidad cuando la ventana de contexto no incluye el detalle peligroso.

Qué no copiar

No copies el optimismo de marketing.

La documentación pública de Shuriken usa un lenguaje fuerte sobre agentes que actúan mientras los usuarios están ausentes y capturan oportunidades.² Esa formulación puede encajar con su producto. No debería convertirse en la postura de seguridad predeterminada para herramientas de agente que producen efectos externos.

En acciones de alto riesgo, “mientras no estás” necesita un significado operativo más estrecho:

• el agente puede recopilar información mientras no estás;
• el agente puede preparar un borrador de acción mientras no estás;
• el agente puede ejecutar solo dentro de un presupuesto pequeño, explícito y aplicado por el servidor;
• el operador puede inspeccionar cada acción más tarde;
• el operador puede pausar o revocar la clave de inmediato.

Esa es la diferencia entre autonomía y abdicación. El usuario puede delegar acción. El sistema no puede delegar responsabilidad.

La misma cautela aplica a las habilidades y los manifiestos de plugin. Un repositorio puede soportar todos los clientes de agente y aun así necesitar un valor predeterminado conservador. El .codex-plugin/plugin.json que inspeccioné lista capacidad de lectura en los metadatos de la interfaz, mientras que la documentación explica que operar requiere permisos y límites habilitados de forma explícita.⁷ Esa es la dirección correcta: la distribución puede ser amplia mientras la autoridad empieza estrecha.

La regla de decisión

Cuando una nueva integración de agente pide una credencial, clasifica la clave antes de emitirla.

Esa tabla le da al agente una ruta utilizable sin fingir que el propio modelo sostiene la frontera. El flujo de trabajo todavía puede mejorar. La clave impide que la mejora se convierta en autoridad ilimitada. Las trazas de ejecución de agentes son el contrato del entorno de ejecución plantea lo mismo desde el lado de la auditoría: si el sistema no puede mostrar qué pasó, no puede demostrar que el agente actuó dentro del contrato previsto.

Escribí sobre la misma separación en La seguridad del entorno aislado de tu agente es una sugerencia: un modelo puede operar completamente dentro de los permisos concedidos y aun así producir un resultado inseguro. Las claves de agente necesitan presupuestos de riesgo porque permiso no es lo mismo que seguridad.

Preguntas frecuentes

¿Las claves de agente son simplemente claves API con otro nombre?

No. Una clave API normal suele conceder acceso amplio a un servicio. Una clave de agente debería conceder un conjunto limitado de capacidades para una integración, con límites del lado del servidor, registros de actividad y revocación que no afecte la sesión principal del usuario.

¿Por qué importa la aplicación del lado del servidor?

El servidor ve la solicitud final. Una instrucción del modelo, un archivo de habilidad o una barrera puede pasar por alto una mala acción. Una verificación de permisos del lado del servidor puede rechazar la solicitud cuando la clave no tiene el alcance necesario o excede un límite configurado.⁶

¿Todo agente debería empezar en modo de solo lectura?

Sí, cuando la herramienta tiene efectos externos importantes. Empieza con acceso de solo lectura, verifica la ruta de integración y agrega permisos de escritura o ejecución solo después de que el equipo sepa qué registros, límites, aprobaciones y pasos de rollback existen.

¿MCP vuelve más riesgosas las credenciales de agente?

MCP facilita conectar herramientas externas entre clientes.³ Esa comodidad aumenta la importancia del diseño de credenciales. El acceso portátil a herramientas debe venir con claves estrechas, no con confianza más amplia.

¿Qué deberían copiar los equipos de Shuriken?

Copia la separación entre distribución de instrucciones y autoridad del lado del servidor: las habilidades portátiles pueden enseñar la integración, mientras que las claves acotadas, los límites, los registros y la revocación restringen la acción. No copies comportamientos de operación específicos del dominio salvo que el producto y los controles legales y operativos lo justifiquen.

Referencias