Ir al contenido
14 ago 2026·8 min de lectura

Las herramientas tipadas evitan los puntos ciegos de tu API

Las herramientas tipadas dan contratos de API, validación en el límite y aprobaciones que frenan escrituras erróneas o no deseadas.

Las herramientas tipadas evitan los puntos ciegos de tu API

Un agente debe decidir qué hacer. Nunca debe inventar cómo espera tu API que se haga. Esta división parece obvia hasta que un modelo envía customer_id donde el endpoint espera accountId, convierte una vista previa en una actualización o rellena un enum desconocido con una palabra plausible. La solicitud puede verse bien en la transcripción y aun así ser inválida, ambigua o peligrosa.

Las herramientas tipadas sacan esa ambigüedad del prompt y la llevan a un contrato exigible. El modelo recibe un conjunto limitado de operaciones, cada una con una forma de entrada verificable por máquina. Tu aplicación valida la llamada antes de que toque la lógica de negocio y después pide aprobación humana para cualquier operación que cambie el estado. El modelo sigue razonando sobre la intención. El código controla la sintaxis, la autoridad y la ejecución.

He visto equipos tratar un prompt de sistema detallado como si fuera una definición de interfaz. No lo es. La prosa puede explicar una política, pero no puede rechazar un campo adicional, imponer una unión discriminada, comparar un número de versión ni impedir que un reintento cobre dos veces. Si un agente puede llegar a una API de producción, esos controles pertenecen al código.

Un prompt describe la intención, un contrato define el permiso

Un prompt puede decirle a un agente que actualice a un cliente solo después de una confirmación. Un contrato de herramienta define con exactitud qué actualización existe, qué campos acepta y qué significa la confirmación. Esas tareas se solapan en una conversación, pero tienen modos de fallo distintos. La prosa falla por interpretación. Los contratos fallan de forma visible en la validación, el tipo de fallo que puedes probar y operar.

Supongamos que una API interna expone un endpoint amplio llamado execute_action. Sus argumentos son action, resource y payload, todos cadenas. El prompt enumera las acciones permitidas e incluye ejemplos. Este diseño parece flexible porque una acción nueva no exige cambiar el esquema. También crea un túnel alrededor de todas las restricciones que la API ya aprendió a aplicar. El modelo puede escribir mal una acción, enviar JSON serializado dentro de payload o combinar un recurso con una acción que nunca se pensó para él.

Una superficie tipada debe exponer operaciones estrechas como get_customer, preview_address_change y commit_address_change. Cada nombre contiene una capacidad. Cada esquema de entrada limita el modelo a los campos que esa operación puede usar. Si el modelo necesita una acción no admitida, la llamada debe fallar como no admitida. Una llamada rechazada es más segura que una inventada y muestra dónde necesita trabajo el catálogo de herramientas.

Aquí también es donde algunos equipos confunden la seguridad de tipos con el formato del prompt. Pedir al modelo que responda con JSON facilita el análisis. No hace que ese JSON sea válido para tu negocio. La sintaxis dice que las llaves coinciden. Un contrato dice que country usa un código permitido, que customer_id identifica el tipo correcto de registro y que una escritura requiere una propuesta aprobada. Necesitas ambas capas.

Conserva las descripciones, pero dales un trabajo menor. Una descripción explica cuándo usar una herramienta y qué significan sus términos. El esquema decide qué puede cruzar el límite. Cuando una restricción sigue importando después de que el modelo deja de generar texto, codifícala donde el ejecutor pueda comprobarla.

Los buenos esquemas dificultan expresar estados ilegales

Un esquema útil hace más que etiquetar campos como cadenas. Codifica las elecciones que cambian el comportamiento y rechaza combinaciones sin sentido. Si una API acepta una dirección de envío existente o una dirección nueva, modélalo como dos casos distintos. No aceptes doce campos opcionales esperando que el prompt explique cuáles seis van juntos.

Este fragmento de JSON Schema da al modelo una elección explícita y cierra el objeto ante campos inventados:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["customer_id", "destination"],
  "properties": {
    "customer_id": {"type": "string", "minLength": 1},
    "destination": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "address_id"],
          "properties": {
            "kind": {"const": "saved"},
            "address_id": {"type": "string"}
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "line1", "city", "country"],
          "properties": {
            "kind": {"const": "new"},
            "line1": {"type": "string"},
            "city": {"type": "string"},
            "country": {"type": "string", "pattern": "^[A-Z]{2}$"}
          }
        }
      ]
    }
  }
}

El campo kind es un discriminador. Impide que un identificador de dirección guardada se cuele en el caso de dirección nueva y da a los errores de validación una ubicación útil. additionalProperties: false importa porque los modelos suelen producir extras que parecen serviciales. Ignorar esos campos en silencio acostumbra a todos a aceptar una diferencia entre la transcripción y la acción que se ejecutó. Recházalos.

No codifiques como enums estáticos hechos que requieren datos actuales. Una lista de identificadores de almacén, usuario o plan vigente queda obsoleta. Pon vocabulario estable como draft, approved y cancelled en el esquema. Resuelve los identificadores cambiantes mediante una herramienta de lectura y después valídalos contra el sistema de registro durante la ejecución.

Las fechas, el dinero y las cantidades merecen representaciones explícitas. Usa una cadena de fecha ISO si la API se refiere a una fecha de calendario, no una marca temporal con una zona horaria implícita. Representa el dinero como un entero en la unidad mínima admitida más un código de moneda, salvo que el modelo de dominio existente dicte otra representación exacta. Añade mínimos, máximos, longitudes de cadena y patrones cuando el dominio los tenga. Cada límite omitido se convierte en un valor que el agente puede probar de forma razonable.

El versionado del esquema debe ser aburrido. Da a cada herramienta una versión en el registro, conserva las versiones antiguas mientras haya ejecuciones activas que aún puedan llamarlas y coloca los cambios incompatibles en una versión nueva. Convertir un campo opcional en obligatorio sin cambiar la versión puede transformar un reintento rutinario del agente en un error de validación misterioso.

Valida antes y después de la lógica de negocio

La validación en el límite necesita dos pasadas. Primero valida los argumentos del modelo contra el esquema publicado de la herramienta. Después valida los hechos del dominio dentro del servicio que los posee. La primera pasada detecta llamadas mal formadas. La segunda detecta llamadas bien formadas que ya no son ciertas.

Una solicitud con customer_id: "C-1842" puede satisfacer todas las reglas de JSON mientras apunta a un registro eliminado o a un cliente fuera del tenant del operador. Una quantity positiva puede superar las existencias disponibles. Una propuesta approved puede haber caducado. El adaptador de la herramienta no debe tratar el éxito del esquema como autorización ni como validez del dominio.

Devuelve los errores como resultados tipados, no como párrafos que el modelo tenga que reinterpretar. Un envoltorio de error estable da al planificador información suficiente para recuperarse sin exponer trazas de pila:

{
  "ok": false,
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Customer changed after the proposal was created",
    "retryable": false,
    "field": "expected_version"
  }
}

El código sirve para el flujo de control. El mensaje sirve para la transcripción y el operador. El indicador de reintento dice al entorno de ejecución si repetir la misma llamada podría ayudar. Mantén estos significados estables entre herramientas. Si cada adaptador inventa su propia prosa de error, el modelo acaba siendo tu analizador accidental de errores.

Valida también las salidas. Los autores de herramientas cambian código, las API anteriores devuelven datos parciales y los serializadores filtran campos. Un esquema de salida puede impedir que una herramienta devuelva credenciales, notas internas o un megabyte inesperado de texto al contexto del modelo. También detecta el caso desagradable en que la ejecución tuvo éxito, pero cambió la forma del resultado y el agente razona desde campos ausentes.

Registra el resultado de validación con el nombre de la herramienta, la versión del esquema, el ID de ejecución y el código de error. No registres por defecto los argumentos sin tratar. Las entradas de las herramientas suelen contener justo los datos personales u operativos que intentas controlar. Guarda hashes o campos seguros seleccionados cuando aporten prueba suficiente.

Las lecturas y escrituras necesitan capacidades distintas

Clasifica las herramientas por efecto antes de que el modelo las vea. Una lectura devuelve información sin cambiar un estado duradero. Una escritura crea, actualiza, elimina, envía, publica, paga, despliega o activa otro sistema que hace alguna de esas cosas. El verbo HTTP no es un clasificador fiable. Un endpoint GET puede marcar un mensaje como leído, y un endpoint POST puede hacer una búsqueda pura. Clasifica el efecto de negocio.

Da herramientas de lectura a los agentes exploratorios de forma predeterminada. Añade herramientas de escritura solo a la ejecución que las necesita, con una identidad que tenga permisos equivalentes en el servidor. Ocultar las herramientas de escritura en el prompt no controla permisos. Si el entorno aún puede despachar una llamada con nombre, una inyección de prompt o un error de planificación puede encontrarla. El despachador debe rechazar cualquier herramienta que no esté en el conjunto de capacidades de la ejecución.

Las escrituras también necesitan formas más estrechas. Una herramienta genérica update_record pide al agente que entienda todas las tablas y columnas mutables. Expón operaciones de negocio como suspend_invoice_delivery o change_shipping_address. Así el servicio puede imponer invariantes, producir una vista previa útil y asociar una política de aprobación a ese efecto exacto.

Algunas operaciones parecen reversibles, pero no lo son. Un correo enviado no se puede recuperar con fiabilidad. Publicar un evento puede iniciar varios trabajos posteriores. Eliminar un registro recién creado puede no deshacer la notificación que ya se envió sobre él. Trata la comunicación externa y los activadores posteriores como escrituras aunque tu base de datos local no cambie.

Para un flujo mixto, separa la planificación de la ejecución. El agente puede leer registros, calcular un cambio propuesto y pedir a una herramienta de vista previa que calcule su precio o lo valide. La herramienta de confirmación final acepta un identificador de propuesta, no una carga nueva de forma libre. Esa decisión evita que la operación aprobada cambie entre la pantalla y la escritura.

La aprobación debe vincularse a una escritura exacta

Mantén dentro el código regulado
CodeHero puede ejecutar modelos aislados en hardware dentro del perímetro del cliente.

Un botón de aprobación por sí solo ofrece poco control. El registro de aprobación debe decir quién aprobó qué, con qué versión del objetivo y hasta cuándo. De lo contrario, un modelo puede recibir aprobación para una carga y ejecutar otra, o ejecutar la carga aprobada después de que haya cambiado el registro subyacente.

Usa un objeto de propuesta creado por código de confianza. El agente entrega argumentos candidatos a una herramienta de vista previa. El servicio los valida, resuelve valores predeterminados, calcula consecuencias y devuelve una propuesta canónica. El usuario ve el efecto canónico, no el resumen conversacional del modelo. Un registro de aprobación práctico puede verse así:

{
  "proposal_id": "p_7f31",
  "tool": "commit_address_change.v2",
  "arguments_sha256": "8be7...a91c",
  "target": {"type": "customer", "id": "C-1842", "version": 17},
  "effect": "Replace the shipping address for customer C-1842",
  "expires_at": "2026-08-14T16:30:00Z",
  "approved_by": "user_291"
}

El endpoint de confirmación carga este registro, comprueba la autoridad de quien aprobó, revisa la caducidad, compara la versión del objetivo y vuelve a calcular el hash de los argumentos canónicos. No debe aceptar argumentos sustitutos del agente. Si algo difiere, la ejecución se detiene y el sistema crea una propuesta nueva.

La política de aprobación debe seguir la consecuencia, no el número de herramientas. Un borrador de bajo riesgo guardado en un espacio aislado quizá no necesite decisión humana. Enviar ese borrador a un cliente sí. Un cambio masivo, pago, borrado, rotación de credenciales, despliegue en producción o mensaje externo debe recibir un nivel de aprobación acorde con su alcance. Guarda la regla en una tabla de políticas que el entorno pueda evaluar. No la entierres entre prompts.

La pantalla de aprobación debe mostrar diferencias concretas: campos antes y después, destinatarios, importe y moneda, entorno, número de registros afectados y cualquier consecuencia irreversible. No pidas a alguien que apruebe run tool call. La fatiga de aprobación empieza cuando la pantalla oculta el efecto y obliga al operador a confiar en el resumen del agente.

Las aprobaciones deben caducar, y la mayoría debe ser de un solo uso. Registra también la denegación, incluida una razón breve que el agente pueda usar para replantear. Nunca conviertas el silencio, una pestaña cerrada o un tiempo agotado en consentimiento.

Un fallo de escritura puede parecer un éxito durante minutos

Piensa en un agente que cambia una dirección de envío. Lee la versión 17 del cliente, propone una dirección nueva y recibe aprobación. La solicitud de confirmación llega al servicio, que escribe la dirección y confirma la transacción. Antes de que la respuesta llegue al agente, se cae la conexión. El entorno ve un tiempo agotado. No sabe si la escritura ocurrió.

Un reintento ingenuo envía otra vez el mismo cambio lógico. Si el endpoint añade direcciones o emite un evento de tramitación, la segunda solicitud puede duplicar trabajo. Si el entorno informa del fallo, el operador puede repetir el cambio a mano. La transcripción dice que la herramienta falló aunque producción cambió. Este resultado ambiguo es un problema normal de sistemas distribuidos, no una rareza del modelo.

Cada llamada de escritura necesita una clave de idempotencia generada fuera del modelo. Vincúlala a la ejecución, la propuesta y la operación. Cuando sea posible, el servicio guarda la clave con el resultado final en el mismo límite transaccional que la escritura. Un reintento con la misma clave devuelve el resultado guardado. Una llamada que reutilice la clave con argumentos distintos debe fallar.

El entorno debe manejar el tiempo agotado con una secuencia fija:

  1. Consultar el estado de la operación mediante la clave de idempotencia.
  2. Si el servicio registró éxito, devolver ese resultado tipado al agente.
  3. Si el servicio registró un fallo terminal, devolver el error guardado.
  4. Si se desconoce el estado, pausar y escalar en lugar de inventar un resultado.

La concurrencia optimista cierra otro hueco. La propuesta anterior apunta a la versión 17. Si una persona cambia la dirección antes de la confirmación, la versión actual pasa a 18 y la confirmación falla con VERSION_CONFLICT. El agente debe leer el estado nuevo y crear una propuesta nueva. Reutilizar la aprobación anterior aplicaría una decisión tomada contra hechos que ya no existen.

Los reintentos automáticos son apropiados para lecturas que se declaran seguras y para escrituras protegidas por idempotencia con un protocolo de estado conocido. No dejes que una biblioteca genérica de reintentos decida esto solo a partir de errores de red. La definición de la herramienta debe publicar su clase de reintento y el ejecutor debe aplicarla.

Los resultados deben contener pruebas, no una frase triunfal

El comportamiento limita la aprobación
La prueba de paridad compara la reescritura con tráfico grabado antes de aceptar su comportamiento.

Una respuesta correcta necesita suficientes pruebas estructuradas para la siguiente decisión. Done no basta. Devuelve el identificador del recurso, su versión nueva, el ID de operación, los campos que cambiaron y cualquier estado siguiente del que dependa el flujo. Mantén el texto de presentación separado de los campos de control.

Para el cambio de dirección, un resultado útil podría ser:

{
  "ok": true,
  "operation_id": "op_a812",
  "customer_id": "C-1842",
  "previous_version": 17,
  "new_version": 18,
  "changed_fields": ["shipping_address"],
  "committed_at": "2026-08-14T16:22:11Z"
}

Esa respuesta permite al agente informar de lo que ocurrió sin inventarlo. También permite que un paso posterior pase new_version a otra propuesta. Si el servicio devuelve un mensaje legible, trátalo como texto de presentación, nunca como única prueba de éxito.

Limita el tamaño del resultado de forma deliberada. Una herramienta de búsqueda debe devolver una página acotada y un cursor, no todas las filas coincidentes. Una herramienta de archivos debe devolver metadatos y un identificador cuando el contenido supere lo que el modelo necesita para trabajar. Los resultados grandes y sin tipo aumentan el coste y dificultan aislar la inyección de prompts dentro de datos recuperados. Marca los datos de herramientas como contenido no fiable en el entorno, aunque vengan de tu propia base; el texto guardado pudo originarse en un atacante.

Redacta en el adaptador antes de que el resultado entre en el contexto del modelo. El permiso para llamar a get_customer no implica permiso para revelar todas las columnas del cliente. Define una vista de resultado para la tarea y deja fuera del esquema secretos, indicadores internos y datos personales ajenos. La validación de salida protege después esa vista frente a regresiones.

Para operaciones largas, devuelve un recurso de operación con un enum de estados finito como queued, running, succeeded, failed o cancelled. Consúltalo mediante una herramienta de lectura. No mantengas abierta una llamada al modelo mientras se ejecuta un despliegue o una migración, ni permitas que el agente deduzca el éxito por el tiempo transcurrido.

Reintentos, cancelación y concurrencia necesitan semántica declarada

Un registro de herramientas debe describir el comportamiento operativo junto con los esquemas de entrada y salida. Como mínimo, registra si la herramienta lee o escribe, si las llamadas idénticas son seguras al reintentar, si admite idempotencia, qué política de aprobación se aplica y cómo funciona la cancelación. Son reglas del ejecutor, no consejos en prosa para el modelo.

La cancelación requiere precisión. Cancelar una ejecución del agente puede detener llamadas futuras, pero no puede deshacer automáticamente una solicitud ya aceptada por otro servicio. Un endpoint de cancelación debe devolver si la operación se detuvo, ya había acabado o no puede interrumpirse. Si existe compensación, exponla como una escritura separada con su propia vista previa y aprobación. No llames rollback a una compensación que crea otro evento de negocio.

Los límites de concurrencia pertenecen a varios niveles. Limita las llamadas por ejecución para que un bucle de planificación no inunde una API. Limita las llamadas por tenant para que un flujo ocupado no deje sin recursos a los demás. Añade serialización por recurso cuando dos escrituras aprobadas sobre el mismo registro entrarían en conflicto. El servicio existente sigue siendo responsable de transacciones y bloqueos; el entorno del agente no sustituye la corrección de la base de datos.

Los tiempos de espera deben expresar el comportamiento de la herramienta. Una consulta de dos segundos y una conversión numérica larga no deben compartir un plazo arbitrario. La plataforma de agentes de CodeHero lee bases de código heredadas completas en paralelo mientras comprueba la paridad contra tráfico de producción grabado; esa carga requiere operaciones acotadas y estados explícitos de finalización, no conjeturas conversacionales.

Los errores de límite de tasa deben indicar cuándo puede funcionar otro intento, pero el entorno aún debe respetar el plazo de ejecución y la validez de la aprobación. Si una propuesta aprobada caduca durante la espera, la siguiente llamada debe fallar y pedir otra aprobación. La comodidad no prevalece sobre el límite del consentimiento.

Las pruebas de contrato detectan fallos que los prompts omiten

Lee todos los lenguajes juntos
Los árboles heredados mixtos se analizan en paralelo, no como proyectos separados por lenguaje.

La evaluación del prompt puede decir si el modelo suele elegir la herramienta correcta. Las pruebas de contrato demuestran que la llamada equivocada no puede ejecutarse. Necesitas ambas, pero el segundo conjunto protege producción cuando cambian el modelo, el prompt o la descripción de la herramienta.

Crea fixtures a partir de casos límite reales. Para cada herramienta, prueba la solicitud válida más pequeña, campos desconocidos, campos obligatorios ausentes, ramas de unión incorrectas, límites, versiones obsoletas, aprobación caducada, una persona sin autoridad, claves de idempotencia duplicadas y una clave válida reutilizada con argumentos diferentes. Comprueba con la misma disciplina la validación de salida y la redacción.

Una prueba de contrato compacta puede leerse así:

GIVEN proposal p_7f31 targets customer C-1842 version 17
AND the current customer version is 18
WHEN commit_address_change.v2 executes with idempotency key run9:p_7f31
THEN no address is changed
AND the result code is VERSION_CONFLICT
AND the proposal remains unconsumed

La última aserción importa. Si un conflicto consume la aprobación, el flujo necesita otra después de replantear, lo cual puede ser correcto. Si tu política permite que la misma aprobación sobreviva a un fallo transitorio del servicio, defínelo por separado. Las pruebas obligan al equipo a resolver la distinción en vez de descubrirla durante un incidente.

Prueba el despachador como un límite hostil. Solicita una herramienta no registrada, una herramienta de escritura en una ejecución de solo lectura, una versión de esquema antigua, un objeto de argumentos demasiado grande y cadenas con instrucciones dirigidas al entorno. El despachador debe analizar datos, imponer límites y llamar solo a un manejador registrado. Nunca debe evaluar código generado por el modelo ni construir un nombre de método de forma dinámica.

Conserva también un conjunto pequeño de trazas integrales. Registra el catálogo de herramientas, la solicitud del modelo, las llamadas propuestas, las decisiones de validación, las aprobaciones, los resultados del servicio y la respuesta final sin valores sensibles. Reproduce esas trazas después de cambiar esquemas. La redacción exacta puede variar, pero los efectos permitidos y las invariantes deben mantenerse.

Las pruebas de contrato también deben fijar el catálogo. Guarda una lista esperada de nombres de herramienta, versiones, clases de efecto y políticas de aprobación para cada rol del entorno. Una escritura recién registrada falla entonces en revisión si alguien olvida añadir una política, y un rol supuestamente de lectura falla si su catálogo gana una operación de confirmación. Esto detecta la deriva de permisos antes de que un prompt de evaluación elija la herramienta nueva.

Genera casos inválidos de manera sistemática, pero mantén el generador dentro de límites de esquema que entiendas. Para una cadena obligatoria, prueba su omisión, texto vacío, un valor demasiado grande y el tipo primitivo equivocado. Para una unión, combina campos de ambas ramas y aporta un discriminador desconocido. Para números, prueba los límites exactos y el valor más cercano fuera de cada uno. El objetivo es demostrar que cada límite declarado tiene una ruta de rechazo ejecutable.

La telemetría de producción debe responder preguntas concretas sin guardar cargas sensibles. Cuenta llamadas por herramienta y versión, fallos de validación por código y campo, decisiones de aprobación, conflictos, resultados ambiguos, reintentos por clase declarada y fallos de salida. Un aumento repentino de campos desconocidos suele indicar que un prompt o cliente adelantó al registro. Los conflictos repetidos pueden significar que las propuestas viven demasiado o que el flujo lee demasiado pronto. Esas señales indican si cambiar un esquema, una descripción o la secuencia.

Trata los errores de validación como información del producto, no como texto que deba parchearse automáticamente. Si el modelo entrega repetidamente email a una herramienta que solo acepta customer_id, decide si la búsqueda pertenece a otra herramienta de lectura o si la escritura debe aceptar un identificador alternativo estable. No añadas campos opcionales en silencio hasta que las llamadas pasen. Cada campo nuevo amplía la operación y necesita decisiones propias de autorización, redacción y pruebas.

Inyecta fallos alrededor del ejecutor. Corta la conexión después de que el servicio confirme, devuelve un cuerpo de éxito mal formado, retrasa una aprobación hasta que caduque, enfrenta dos propuestas sobre la misma versión y deja temporalmente inaccesible el endpoint de estado. Verifica que el entorno informa de un resultado desconocido cuando faltan pruebas. Una respuesta de éxito inventada puede parecer pulida en una evaluación, así que compara con el estado registrado del servicio, no solo con la frase final.

Por último, prueba que la pantalla de aprobación y la confirmación compartan la misma propuesta canónica. Muestra la aprobación desde datos canónicos guardados, apruébala y después modifica cada copia de argumentos controlada por el agente antes de confirmar. El efecto ejecutado debe ser idéntico al mostrado. Si cuesta escribir esa prueba, es probable que el límite de aprobación dependa del estado conversacional, justo donde no debe estar.

La opción segura es una superficie menor de herramientas

Empieza con el catálogo más estrecho que complete un flujo real. Una herramienta se gana su sitio cuando su entrada se puede acotar, su salida se puede validar, su efecto se puede clasificar y sus fallos se pueden representar sin pedir al modelo que adivine. Si no puedes definir esas partes, la API no está lista para convertirse en herramienta de un agente.

Resiste el consejo popular de exponer todos los endpoints internos y dejar que el modelo planifique libremente. A los equipos les gusta porque la primera demostración aparece rápido. En producción traslada la arqueología de la API, la elección de permisos y la interpretación de errores a un componente probabilístico. El modelo gasta tokens redescubriendo reglas que tus servicios ya conocen, y un error plausible puede cruzar un límite de escritura.

Un catálogo estrecho no hace al agente menos capaz. Hace explícita su capacidad. Añade una herramienta cuando los registros muestren una operación ausente, no cuando el prompt gane otro párrafo que explique cómo forzar una acción ajena por un endpoint genérico. Versiona el contrato, adjunta la política y da al ejecutor un resultado tipado.

El listón de una escritura es más alto. Exige una propuesta canónica, una aprobación vinculada a su hash y versión de objetivo, un protocolo de idempotencia y un resultado que demuestre qué cambió. Haz visibles al operador los resultados desconocidos. Un flujo pausado molesta; un agente que informa con seguridad del estado de producción equivocado sale caro.

Las herramientas tipadas son el punto en que un agente deja de ser una interfaz de chat alrededor de credenciales privilegiadas y se convierte en un componente de software controlable. Deja el razonamiento en el modelo. Mantén el permiso y la verdad en el límite.

Preguntas frecuentes

¿Qué es una herramienta tipada para un agente de IA?

Es una operación con nombre y esquemas de entrada y salida verificables por máquina. El agente elige la operación y aporta argumentos, mientras el código de la aplicación valida la llamada y ejecuta un manejador registrado.

¿Basta la salida JSON de un modelo para usar herramientas con seguridad?

No. Un JSON válido solo demuestra que el texto se puede analizar. Aún necesitas un contrato que rechace campos desconocidos y combinaciones inválidas, además de comprobaciones de permisos, versiones actuales e identificadores vivos.

¿Todas las herramientas de agente requieren aprobación humana?

No. Las operaciones de solo lectura y los borradores de bajo riesgo pueden ejecutarse sin aprobación si los permisos lo permiten. Las escrituras con efectos externos, financieros, de producción, masivos o irreversibles deben usar una política acorde con su consecuencia.

¿Qué debe contener un registro de aprobación?

Vincula la aprobación a una propuesta canónica, el hash de argumentos, la versión exacta de la herramienta, el identificador y la versión del objetivo, la persona que aprueba y la caducidad. La confirmación debe cargar ese registro y rechazar argumentos sustitutos.

¿Cómo debe reintentar un agente una escritura fallida?

Da a cada escritura una clave de idempotencia y consulta el estado de la operación tras un tiempo agotado. Reintenta solo cuando la semántica declarada y el estado guardado hagan segura la repetición; en otro caso, pausa para un operador.

¿Por qué conviene rechazar propiedades JSON adicionales?

Los campos extra pueden hacer que la transcripción prometa un efecto que el manejador ignora. Rechazarlos muestra la deriva del contrato e impide que invenciones plausibles del modelo crucen el límite.

¿Son iguales la validación del esquema y la autorización?

No. La validación del esquema comprueba la forma de la llamada. La autorización decide si esa identidad puede realizar la operación sobre ese recurso, y la validación del dominio decide si la operación sigue siendo válida.

¿Qué debe devolver una herramienta después de escribir con éxito?

Devuelve pruebas estructuradas como ID de operación y recurso, versiones anterior y nueva, campos modificados y hora de confirmación. Una simple frase de éxito deja demasiado espacio para que el agente invente detalles.

¿Cómo se gestionan las herramientas de larga duración?

Devuelve un recurso de operación con un enum de estado acotado y consúltalo con una herramienta de lectura. La cancelación debe informar si el trabajo se detuvo, terminó o no puede interrumpirse, sin fingir que toda escritura aceptada se puede deshacer.

¿Qué tamaño debe tener el catálogo de herramientas de un agente?

Conserva solo las operaciones que necesitan el flujo y la identidad actuales. Añade una herramienta cuando falte una capacidad real, y exige esquemas, clasificación del efecto, semántica de fallos y política antes de registrarla.