Audita las herramientas y habilidades de tu agente y conviértelas en un contrato de capacidades digno de confianza
Convierte las herramientas ocultas, los permisos y los modos de fallo de tu agente en un contrato inspeccionable que los usuarios puedan verificar de verdad.
| Autor | Prompt & Product — Redacción |
|---|---|
| Publicado | 8 septiembre 2026 |
| Lectura | 4 MIN |
La caja mágica es un fallo de UX
La UX del agente muere cuando el producto pide a los usuarios que confíen en una caja negra. El modelo puede ser capaz, pero la interfaz sigue ocultando lo que el agente puede hacer, lo que puede cambiar y qué ocurre cuando no puede terminar. No es, ante todo, un problema de modelo. Es un problema de contrato.
El patrón útil es sencillo: hacer explícitas las capacidades, los permisos y los modos de fallo como contratos inspeccionables. Un agente digno de confianza no se anuncia como poderoso. Muestra su alcance, sus límites y la evidencia de que se mantuvo dentro de ellos.
No diseñes un agente como una promesa. Diseña el agente como un comprobante.
Los usuarios no piden más magia. Piden una forma de verificar que el agente hizo lo que dijo que podía hacer. Ese es el núcleo de la divulgación de capacidades en los productos de agente.
Lo que la referencia hace bien
Una referencia de herramientas ofrece un modelo útil para este tipo de divulgación. Distingue las herramientas de las habilidades, definiendo las herramientas como puntos finales invocables y las habilidades como paquetes de instrucciones reutilizables.
La referencia conserva las descripciones expuestas de las herramientas y las declaraciones de TypeScript, dejando constancia de lo que se expone.
La disponibilidad puede cambiar según la configuración de la sesión, los permisos, las aplicaciones conectadas y los plugins instalados, por lo que es una condición variable.
Estas divulgaciones necesitan un lugar en la documentación pública del producto.
Cada habilidad disponible tiene su propia página con una copia literal de su definición principal, lo que permite comprobar la definición.
Audita tu agente y conviértelo en un contrato de capacidades
Usa la referencia como una lista de verificación, no como una plantilla. Tu producto puede tener herramientas distintas, habilidades distintas y niveles de riesgo distintos. El objetivo es convertir la arquitectura oculta en un contrato que los usuarios puedan inspeccionar y que tu equipo pueda mantener.
- Clasifica herramientas y habilidades. Enumera cada acción directa que el agente puede invocar como herramienta. Enumera cada conjunto reutilizable de instrucciones como habilidad. Si una capacidad es a la vez una función y una política, divídela. El usuario debe poder ver lo que el agente puede invocar y cómo le está permitido usarlo.
- Expone declaraciones y descripciones. Para cada herramienta, publica la descripción, la estructura de entrada, la estructura de salida y cualquier información de tipos relevante. Para cada habilidad, publica las instrucciones centrales en lenguaje claro. Si la declaración cambia, la copia visible para el usuario también debería cambiar.
- Indica las condiciones de disponibilidad. No muestres una herramienta como disponible a menos que esté disponible en el contexto actual. Haz explícitas las condiciones: lo que el usuario debe habilitar, conectar o configurar. Si una herramienta no está disponible, indica por qué y qué la haría disponible.
- Documenta los modos de fallo. Para cada capacidad de alto riesgo, describe qué ocurre cuando la solicitud se deniega, la salida es incompleta, la herramienta agota el tiempo de espera o la habilidad no se puede aplicar. Un modo de fallo no es un mensaje de error. Es un resultado diseñado.
- Expone comprobantes visibles para el usuario. Después de que el agente actúe, muestra lo que se invocó, qué permiso se usó, qué se cambió y qué se dejó intacto. El comprobante debe ser lo bastante breve para leerse de un vistazo y lo bastante detallado para verificarlo.
El contrato debe estar donde los usuarios puedan encontrarlo, no enterrado en una página de configuración. Debe ser legible para un diseñador de producto, un agente de soporte y un usuario escéptico. Si el contrato solo es útil para ingenieros, aún no es una superficie de confianza.
Empieza con las capacidades que pueden causar más daño o más confusión. Una herramienta que edita archivos, envía mensajes, gasta dinero o modifica permisos necesita un contrato más fuerte que una herramienta que resume texto. Cuanto más irreversible sea la acción, más explícita debe ser la divulgación.
Termina con una prueba simple: ¿puede un usuario consultar el contrato de capacidades del agente y predecir qué hará a continuación? Si la respuesta es que no, la interfaz sigue pidiendo fe. Si la respuesta es que sí, has pasado de una caja mágica a un producto digno de confianza.
