Resources y prompts
Además de las tools, el servidor ofrece tres cosas que el cliente usa por su cuenta: resources (documentos que adjuntas a la conversación), prompts (guiones listos que eliges) y completions (autocompletado para los argumentos de ambos). En la era 2026-07-28, también pide confirmación antes de ejecutar una tool destructiva.
Nada de esto abre un camino nuevo hacia tus datos: todo pasa por las mismas tools, con los mismos permisos y los mismos scopes. Todos los resources y prompts de aquí solo leen, así que un token de solo lectura los alcanza todos — siempre que la persona pueda ejecutar las tools que hay detrás.
Resources
Un resource es un documento identificado por una URI. Eliges, por ejemplo, un correo, y el cliente lee el registro y lo pone en el contexto, sin que el modelo tenga que llamar a una tool. Las URIs viven bajo kobana://inbox/, así que conviven con las de otros productos de Kobana en el mismo cliente.
| URI | Qué devuelve |
|---|---|
kobana://inbox/models | Los modelos LLM con los que puede correr un agente, con sus precios (JSON) |
kobana://inbox/usage | Correos procesados, ejecuciones, tokens y coste del workspace en los últimos 30 días (JSON) |
kobana://inbox/workspaces/{id} | Un workspace, con sus límites (JSON) |
kobana://inbox/inboxes/{id} | Un inbox: dirección, agente, destinatarios, filtros y reglas de adjuntos (JSON) |
kobana://inbox/emails/{id} | Un correo recibido: headers, cuerpo, adjuntos y estado de procesamiento (JSON) |
kobana://inbox/emails/{id}/eml | Una URL firmada de corta duración para descargar el .eml original (JSON) |
kobana://inbox/agents/{id} | Un agente de IA: modelo, mensaje de sistema y skills (JSON) |
kobana://inbox/agent-runs/{id} | Una ejecución de agente: estado, salida, tokens y coste (JSON) |
kobana://inbox/workflow-runs/{id} | Una ejecución de workflow: los pasos y su resultado (JSON) |
kobana://inbox/webhooks/{id} | Un webhook saliente: URL, eventos y estado (JSON) |
kobana://inbox/system-events/{id} | Una entrada del registro de eventos, con su payload (JSON) |
resources/list devuelve las URIs fijas y resources/templates/list las plantillas con parámetros.
- Permisos. Cada resource lo lee la tool correspondiente (
kobana://inbox/emails/{id}esemails_get). Solo se lista, y solo se lee, si puedes ejecutar esa tool. - Secrets. No hay resource de secret — ni siquiera los metadatos. Usa las tools
secrets_*. - No encontrado. Una URI desconocida, o un registro que no existe en este workspace, es
-32002en la era 2025 y-32602en2026-07-28— ver Errores. - Sin suscripciones a cambios. El servidor es stateless: no hay
resources/subscribeni aviso de cambio en la lista.
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. Solo se lista si puedes ejecutar todas las tools en las que se apoya. Ninguno escribe: reprocesar un correo o eliminar cualquier cosa queda para que lo pidas explícitamente.
| Prompt | Argumentos | Qué hace |
|---|---|---|
review_failed_runs | since (opcional, YYYY-MM-DD; por defecto: últimos 7 días), agent_id (opcional) | Busca las ejecuciones de agente fallidas, las agrupa por causa y señala los correos que las originaron. |
inbox_overview | inbox_id | El panorama de un inbox: su configuración, los últimos correos y cómo le va a su agente. |
webhook_health | — | Qué webhooks salientes están fallando al entregar, y desde cuándo. |
usage_report | month (opcional, YYYY-MM) | Lo que el workspace procesó y gastó en el mes, por modelo. |
Un argumento obligatorio ausente, o since/month fuera de formato, es -32602.
Completions
completion/complete sugiere valores mientras escribes un argumento:
- Ids (
inbox_id,agent_idy el parámetro de las plantillas de registro): los registros más recientes del listado correspondiente, por el prefijo escrito, con el mismo permiso. Si no puedes listar, no hay sugerencia. month: los últimos doce meses.
Sin fuente de sugerencias, la respuesta es una lista vacía, y sigues escribiendo.
Confirmación de tools destructivas
Las tools que eliminan, envían algo hacia fuera (webhooks_test, webhooks_deliveries_replay, emails_reprocess — el agente puede responder o actuar), rotan el secreto de un webhook o cambian quién puede enviar a una inbox (inboxes_add_recipient, inboxes_remove_recipient) están marcadas con destructiveHint. El servidor confirma cada una con el usuario antes de ejecutarla:
- El primer
tools/callno ejecuta nada. Vuelve conresultType: "input_required"y un formulario de una sola pregunta: ¿ejecutar esta acción, con estos argumentos? - El cliente muestra la pregunta y envía la misma llamada de nuevo con tu respuesta.
- Solo un sí explícito la ejecuta. Rechazar o cancelar vuelve como resultado
isErrorconuser_declined, y nada cambia.
La confirmación vale solo para esa llamada, y una sola vez: la misma tool, los mismos argumentos, la misma persona, organización y workspace, durante 5 minutos, y ejecuta la acción una única vez. Una respuesta no puede reutilizarse para otro registro u otra acción — si algo no coincide, el servidor simplemente vuelve a preguntar — y enviar la misma llamada confirmada una segunda vez responde confirmation_replayed sin ejecutar nada. Para ejecutarla de nuevo, llama a la tool sin requestState y responde la nueva pregunta.
Preguntar exige el protocolo 2026-07-28 y un cliente que declare soporte para formularios de elicitation. Ningún otro cliente puede ejecutar una tool destructiva: en la era 2025, o sin ese soporte, la llamada responde confirmation_required y no se ejecuta nada. Si el servidor no puede registrar la confirmación en ese momento, la llamada responde confirmation_unavailable, también sin ejecutar nada — inténtalo de nuevo más tarde.