Resources y prompts

Además de las tools, el servidor ofrece tres cosas que el cliente usa por su cuenta: resources (documentos que el usuario adjunta a la conversación), prompts (guiones listos que el usuario elige) y completions (autocompletado de los argumentos de ambos). Y, antes de ejecutar una tool destructiva, pide tu confirmación.

Nada de esto abre un camino nuevo hacia tus datos: todo pasa por las mismas tools, bajo el mismo alcance del token y el mismo rol de la persona. Un resource o un prompt que se apoya en una tool que no puedes ejecutar simplemente no aparece.

Resources

Un resource es un documento identificado por una URI. El usuario elige, por ejemplo, una ejecución, y el cliente lee el documento y lo pone en el contexto, sin que el modelo tenga que llamar a una tool. Todos vuelven en JSON.

URI	Qué vuelve	Tool que lo lee
kobana://kadu/me	La persona, la organización y los alcances de la conexión	kadu_me_get
kobana://kadu/repository	El Kadu Playbook de la organización y su catálogo de skills	kadu_repository_get
kobana://kadu/operation_approvals	Tus aprobaciones por enlace, de la más reciente a la más antigua	kadu_operation_approvals_list
kobana://kadu/operation_approvals/{id}	Una aprobación: lo que se pidió, la decisión y el resultado	kadu_operation_approvals_get
kobana://kadu/workspaces/{id}	Un workspace	kadu_workspaces_get
kobana://kadu/activities/{id}	Una actividad	kadu_activities_get
kobana://kadu/tasks/{id}	Una tarea y el esquema de sus parámetros	kadu_tasks_get
kobana://kadu/executions/{id}	Una ejecución	kadu_executions_get
kobana://kadu/executions/{id}/events	Los eventos que el agente reportó en la ejecución	kadu_executions_events_list
kobana://kadu/executions/{id}/logs	Los logs de la ejecución	kadu_executions_logs_list
kobana://kadu/executions/{id}/todos	Los pendientes que abrió la ejecución	kadu_executions_todos_list
kobana://kadu/memories/{id}	Una memoria del agente	kadu_memories_get
kobana://kadu/environments/{id}	Un entorno	kadu_environments_get
kobana://kadu/schedules/{id}	Una programación	kadu_schedules_get

resources/list trae las URIs fijas y resources/templates/list las plantillas con {id}.

• Permisos. Cada resource se lee con la tool de la última columna. Solo aparece, y solo se lee, si puedes ejecutar esa tool; si no, la lectura devuelve -32602 con data.code: "insufficient_permission".
• Sin binarios. El contenido de un archivo nunca viene como resource: se descarga por la URL prefirmada de kadu_files_download.
• No encontrado. Una URI desconocida, o un registro que no existe en esta organización, es -32002 en la era 2025 y -32602 en la 2026-07-28 — mira Errores.
• Sin suscripción a cambios. El servidor es stateless: no hay resources/subscribe ni aviso de lista modificada.

Prompts

Un prompt es una instrucción lista que eliges en el cliente y que se convierte en el primer mensaje de la conversación. En Kadu, todos solo leen: lanzar, cancelar o cambiar la configuración es siempre algo que pides tú, explícitamente. Un prompt solo aparece si puedes ejecutar todas las tools en las que se apoya.

Prompt	Argumentos	Qué hace
review_failed_executions	since (opcional, AAAA-MM-DD; por defecto: hace siete días)	Lista las ejecuciones que fallaron desde la fecha y explica qué salió mal en cada una, agrupando causas repetidas, sin ejecutar, cancelar ni continuar nada.
explain_execution	execution_id	Explica, paso a paso, qué hizo el agente en una ejecución: los sistemas que tocó, el resultado y los pendientes que quedaron para una persona.
monthly_usage_report	month (AAAA-MM)	Resume uso y costo de las ejecuciones del mes, por tarea y por workspace, y señala las tareas que más costaron.
check_task_readiness	task_id, environment_id	Dice si la tarea puede correr ahora en ese entorno y, si no, exactamente qué falta (plan, tope de costo, secrets, repositorio), sin lanzar nada.

El guion llega con las fechas ya calculadas. Un argumento obligatorio ausente, o since y month fuera de formato, es -32602.

Completions

completion/complete sugiere valores mientras escribes un argumento:

• Ids (execution_id, task_id, environment_id y el {id} de las plantillas): los ids recientes del listado correspondiente, filtrados por lo que ya escribiste, bajo el mismo permiso de ese listado. Si no puedes listar, no hay sugerencia.
• month: los últimos doce meses.

Como máximo 100 valores. Sin fuente de sugerencias, la respuesta es una lista vacía, y sigues escribiendo.

Confirmación de tools destructivas

Las tools destructivas están marcadas con destructiveHint:

• toda tool de eliminación (*_delete, incluido deshabilitar el endpoint de disparo de una tarea);
• kadu_tasks_run y kadu_executions_continue, que ejecutan el agente financiero — y él actúa en banco, ERP y facturas;
• kadu_executions_cancel;
• kadu_webhook_deliveries_replay y kadu_webhooks_rotate_secret;
• kadu_tasks_endpoint_update, que cambia quién puede lanzar el agente;
• kadu_webhooks_create, y kadu_webhooks_update cuando cambia la url — adónde van los datos de la organización.

El servidor no confía solo en el cliente: él mismo exige la confirmación, de una de dos formas, según el cliente.

Confirmación en el chat (era 2026-07-28)

Cuando el cliente habla la era 2026-07-28 y declara soporte de formularios de elicitation:

1. El primer tools/call no ejecuta nada. Devuelve resultType: "input_required" con un formulario de una pregunta: ¿ejecutar esta acción, con estos argumentos?
2. El cliente muestra la pregunta y reenvía la misma llamada con tu respuesta.
3. Solo un sí explícito la ejecuta. Rechazar o cancelar devuelve un resultado isError con USER_DECLINED, y nada cambia.

La confirmación vale solo para esa llamada: la misma tool, los mismos argumentos, la misma persona y organización, durante 5 minutos. Una respuesta no puede reutilizarse para otra tarea u otra acción; si algo no coincide, el servidor simplemente pregunta de nuevo. Y es de un solo uso: reenviar una llamada ya confirmada devuelve isError con confirmation_replayed, sin ejecutar nada — para repetir la acción, llama a la tool de nuevo y confirma otra vez.

Cliente sin formulario de confirmación: aprobación por enlace

Un cliente que no puede confirmar en el chat — en la era 2025, o en la 2026-07-28 sin declarar formularios de elicitation — también usa las tools destructivas, pero mediante un enlace de aprobación. La llamada no ejecuta nada: el servidor guarda la operación como pendiente y responde con éxito (sin isError), en un único texto JSON:

{
  "status": "approval_required",
  "approval": {
    "id": "6f0c2d1e-…",
    "status": "pending",
    "url": "https://app.kadu.ia.br/approvals/…",
    "expires_at": "2026-10-31T12:15:00.000Z",
    "resource_uri": "kobana://kadu/operation_approvals/6f0c2d1e-…",
    "check_with": { "tool": "kadu_operation_approvals_get", "arguments": { "id": "6f0c2d1e-…" } }
  },
  "message": "… Show this URL to the user … Do not call the tool again …"
}

1. El asistente muestra la URL. No llames a la tool de nuevo: eso crearía otra aprobación.
2. Abres el enlace con tu sesión de Kadu iniciada (sin sesión, pasa por el inicio de sesión y vuelve al enlace). La pantalla muestra lo que va a pasar ("Ejecutar la tarea", "Eliminar el entorno"), quién lo pidió, cuándo, por qué cliente, los datos actuales de lo que afecta la operación y todos los argumentos que se van a ejecutar.
3. Continuar ejecuta la operación en el momento, con los permisos que tienes ahora: si perdiste el permiso o el vínculo con la organización desde el pedido, o si el token que la pidió fue revocado, la ejecución falla y nada cambia. Cancelar termina sin ejecutar nada.

El enlace vale 15 minutos y decide una sola vez: dos clics en Continuar ejecutan una vez, y un enlace vencido o cancelado no ejecuta. Solo tú — la persona detrás del token que hizo la llamada — abres el enlace: para cualquier otra persona, incluso de tu organización, no existe.

Si lo que afecta la operación cambia entre que abres la pantalla y haces clic en Continuar (un webhook que cambió de URL, una tarea modificada), nada se ejecuta (subject_changed): pide la operación de nuevo y revisa el nuevo enlace.

Tus aprobaciones quedan en Configuración › Aprobaciones en la consola, con pestañas por estado (Pendientes, Ejecutadas, Canceladas, Con falla, Expiradas); hacer clic en una fila abre la aprobación solo para lectura — una pendiente se decide por el enlace que mostró el asistente.

Seguir la aprobación

El propio asistente sigue la aprobación que pidió: con el id de la respuesta, kadu_operation_approvals_get (o el resource kobana://kadu/operation_approvals/{id}) muestra el estado — pending, después executed, failed, declined o expired — y lo que devolvió la operación. El check_with solo viene en la respuesta cuando el llamador puede ejecutar esa lectura (alcance kadu/system_events y permiso agent.operation_approvals.read). El asistente debe consultar cuando digas que decidiste, no en bucle.

La lectura nunca decide: no hay tool ni ruta de la API que continúe o cancele una aprobación. Si la hubiera, quien pidió la operación también podría aprobarla.

Un secreto en el resultado — el nuevo secreto de firma de kadu_webhooks_rotate_secret — aparece en claro una vez, en la pantalla, justo después de Continuar; la tool de lectura y la pantalla recargada lo muestran enmascarado.

Cuando la confirmación no es posible

Un token sin una persona de la organización que pueda abrir el enlace devuelve isError con confirmation_required. Si el servidor no puede registrar la confirmación o la aprobación en ese momento, la tool se rechaza con confirmation_unavailable; inténtalo de nuevo más tarde. En los dos casos no se ejecuta nada, y las demás tools siguen funcionando con normalidad.