errores y estados

Lo que devuelve, y qué hacer con eso

Tres respuestas se leen mal la primera vez. Ninguna de las tres es un fallo del sistema: una dice que falta configurar algo, otra que hay una persona en el medio y la tercera que parte salió y parte no.

errorcaso 1 de 3

La primera llamada falla si no hay vinculación

El agente nombró una acción y un destino que nada autoriza. El servidor responde nombrando el par exacto que faltó, y no ejecuta nada.

qué significa

No es un fallo del sistema: falta configurar algo. Es el primer error que ve todo el mundo, casi siempre antes que la primera respuesta correcta. La credencial anda —si no anduviera, la respuesta sería un 401 y no esto.

qué hacer

Creá en la consola una vinculación para ese par exacto de acción y destino.
Si ya existe una, revisá que sea del mismo agente: la clave y la vinculación tienen que pertenecer al mismo.
Volvé a pedirle lo mismo al agente. No hace falta reconectar el cliente.
Para ver qué tiene autorizado sin adivinar, leé el recurso loomen://scope con la misma clave.

tools/call · respuesta

1{
2  "jsonrpc": "2.0",
3  "id": 2,
4  "result": {
5    "content": [
6      {
7        "type": "text",
8        "text": "binding: no active binding authorizes this action for this destination: notificar → humano"
9      }
10    ],
11    "isError": true
12  }
13}

El mensaje siempre nombra el par. Si tu agente registra errores, ese texto alcanza para saber qué vinculación crear.

pendingcaso 2 de 3

Una ejecución puede quedar esperando una firma humana

La vinculación cae bajo una política que frena la ejecución. El agente recibe pending y un id de solicitud, no un error.

qué significa

La llamada no fracasó: hay una persona en el medio y la ejecución está detenida hasta que firme. Todavía no hay entregas que mostrar, porque la acción no se creó: se crea cuando alguien firma.

qué hacer

No reintentes. Un reintento sin idempotency_key abre una segunda invocación y una segunda espera.
Si tu agente necesita saber cómo terminó, repetí la llamada con el mismo idempotency_key: devuelve el estado actual de la invocación original sin volver a ejecutar.
Que el agente le diga a quien le habló que la acción quedó pendiente de firma. Es información, no un error.
Si nadie firma, la solicitud vence a las cuatro horas y queda cerrada con su línea en el registro. Un agente que sigue esperando ahí debería escalar.

respuesta.json

1{
2  "invocation_id": "inv_01a0a6c3-a57a-7e21-a604-330cfae424eb",
3  "status": "pending",
4  "approval_id": "01a0a6c3-a58a-7b00-860f-11dff1cdf333",
5  "deliveries": []
6}

Qué política la frenó y con qué umbral no vuelve al agente, a propósito: un agente que aprende la regla puede tantear su contexto alrededor de ella. Eso queda en el registro, para quien audita.

partialcaso 3 de 3

Una invocación puede salir por dos canales y fallar en uno

El par tenía dos vinculaciones. Una entrega salió y la otra fue rechazada por el receptor. El estado de la invocación es partial y el detalle viene por entrega.

qué significa

El aviso llegó: alguien lo vio. Tratar partial como un fracaso total lleva a repetir la notificación por el canal que sí funcionó.

qué hacer

Leé deliveries antes de decidir nada: el estado de arriba es el resumen, no el veredicto.
No reintentes la invocación entera sin idempotency_key: duplicarías la entrega que salió bien.
failure_reason trae lo que dijo el proveedor. Si es un certificado o una credencial, reintentar no va a cambiar nada hasta que se arregle del otro lado.

respuesta.json

1{
2  "invocation_id": "inv_01a0c0e5-d105-7b23-b802-cc71ef406afc",
3  "status": "partial",
4  "deliveries": [
5    {
6      "action_id": "01a0c0e5-d10a-7f3b-9e41-2c7a55de1b08",
7      "binding_id": "01a0c0e5-cfe2-7a11-8b34-6d9e0f2a7c55",
8      "channel": "email",
9      "status": "delivered",
10      "provider_reference": "0f3b2c19a7d84e6f@core-api.loomen.dev"
11    },
12    {
13      "action_id": "01a0c0e5-d10c-7d92-a7c8-41b0e5f3d219",
14      "binding_id": "01a0c0e5-d001-7c63-9f20-88ab31c7e4d6",
15      "channel": "webhook",
16      "status": "failed",
17      "failure_reason": "webhook: request failed: tls: failed to verify certificate"
18    }
19  ]
20}

Consultar una invocación desde el agente

No hay una herramienta de consulta, y no lo escondemos: la superficie del agente es deliberadamente una sola herramienta, y agregar una segunda está en discusión. Hasta que se resuelva, hay dos caminos.

Repetir la misma llamada con el mismo idempotency_key. No vuelve a ejecutar: devuelve el estado actual de la invocación original.
Mirar Auditoría en la consola, donde la llamada se lee como un recorrido: cada entrega con su canal, su resultado y su motivo.