Qué documentación debe acompañar las herramientas de un agente
Cada herramienta necesita un contrato que permita entender qué hace, qué efectos puede causar y cómo confirmar el resultado.
Equipo enginerIT· 2 min de lectura
Cada herramienta necesita un contrato que permita entender qué hace, qué efectos puede causar y cómo confirmar el resultado. La descripción que ve el modelo es solo una parte de la documentación para operar y mantener la integración.
Especifica entradas y significado
Describe campos, formatos, unidades, valores permitidos y cómo resolver el identificador del registro. Incluye ejemplos válidos y rechazados con datos ficticios. Un esquema puede limitar la forma de los argumentos, pero no demuestra que el pedido pertenezca al usuario o que un importe esté autorizado. Explica qué validaciones realiza la aplicación y cuáles exige el sistema destino.
Declara autoridad y efectos
Separa consulta, preparación, escritura y envío. Identifica identidad técnica, alcance de recursos y aprobación requerida. Una función con nombre “buscar cliente” no debería ocultar que además actualiza su ficha. Si el producto agrupa capacidades, documenta cuáles quedan expuestas y cómo se restringen. Evita dar permisos administrativos para resolver una falta de documentación o un error de acceso.
Describe estados y recuperación
Indica qué significa éxito, aceptación pendiente, rechazo y resultado desconocido. Documenta límites, tiempos de espera y comportamiento ante reintentos según el conector real. Si existe idempotencia, explica su alcance y cómo se identifica la operación; si no, especifica el procedimiento de comprobación antes de repetir. Incluye quién reconcilia una escritura cuyo resultado no puede confirmarse y dónde consulta la evidencia.
Mantén dos vistas coherentes
La descripción para el modelo debe ayudarle a elegir y preparar una llamada sin esconder restricciones. El manual de operación añade diagnóstico, propietario, versiones, pruebas y retirada. Contrasta ambos con una ejecución de ensayo: llamada propuesta, petición efectiva y resultado. La documentación de function calling diferencia propuesta y ejecución por la aplicación; aprovecha esa frontera para validar autorización. Actualiza ejemplos y pruebas cuando cambie el contrato, y conserva la versión anterior para interpretar ejecuciones históricas.
Añade una referencia de contacto para cambios del contrato y un ejemplo de error deliberado. El mantenedor debe poder comprobar una denegación sin tocar datos reales. Una respuesta de error documentada ayuda a detectar incompatibilidades antes de que el modelo intente interpretarlas libremente.
Comprobaciones para cerrar la tarea
- ✓ Entradas documentadas con unidades e identidad.
- ✓ Efectos y aprobaciones explícitos.
- ✓ Resultado desconocido tiene procedimiento de conciliación.
- ✓ Descripción del modelo coincide con contrato ejecutado.
Fuentes y documentación
- OpenAI — Function calling — El modelo propone llamadas; la aplicación ejecuta el código de las herramientas.
- OWASP — Excessive Agency — Distingue funcionalidad, permisos y autonomía excesivos.
Aplicarlo en tu empresa
Podemos revisar el entorno y acordar qué actuaciones, validaciones y mantenimiento necesitas.
Conocer el servicio relacionado →