Tools
El servidor expone 53 tools sobre diez recursos. Cada una refleja un endpoint de /v1 y despacha a él in-process, así que el comportamiento — filtros, emparejamiento de upsert, validación, soft-delete, aislamiento por workspace — es idéntico al de la API REST.
Cómo leer estas páginas
Cada tool está documentada con la misma línea de encabezado:
Lectura · scope
inbox/emails· permisoemails.show·GET /emails/{id}
| Campo | Significado |
|---|---|
| Lectura / Escritura / Destructiva | La annotation que ve el cliente. Una tool destructiva elimina datos, envía algo hacia fuera (prueba o reenvío de webhook, reprocesamiento por un agente que puede responder o actuar), rota un secreto o cambia quién puede enviar a una inbox. Solo se ejecuta después de que el servidor pida confirmación al usuario, lo que exige el protocolo 2026-07-28 con elicitation; cualquier otro cliente recibe confirmation_required — ver Confirmación de tools destructivas. |
| scope | Lo que debe alcanzar el token del cliente conectado. Una escritura exige el scope del recurso y el verbo global write — o el nivel de acceso write/all, dentro de los recursos del token. Ver Scopes. |
| permiso | Lo que la persona detrás del token debe tener en la organización. |
El MÉTODO /path | El endpoint de /v1 al que despacha la tool, para cotejar con la referencia de la API. |
Los parámetros marcados como obligatorio deben estar presentes; todo lo demás es opcional. Una tool que no puedes ejecutar ni siquiera aparece en tools/list. Las tools de lectura también respaldan los resources bajo kobana://inbox/.
Parámetros comunes
Estos aparecen en varias tools y significan siempre lo mismo.
| Parámetro | Tipo | Descripción |
|---|---|---|
cursor | string | Cursor opaco de una página anterior (meta.next_cursor). |
limit | integer | Tamaño de página, por defecto 25, máximo 100. |
sort | string | Claves de ordenación separadas por coma, prefijo - para descendente (p.ej. -created_at). |
idempotency_key | string | Protección contra repeticiones, 8–255 caracteres, enviada como X-Idempotency-Key. La misma clave dentro de 24h devuelve la respuesta original. |
custom_metadata | object | JSON libre, tuyo; devuelto en cada lectura y en cada payload de webhook. |
<campo>_gte / <campo>_lte | string | Filtro de rango ISO 8601 sobre ese campo. |
El catálogo
| Recurso | Tools | Scope de lectura |
|---|---|---|
| Workspaces | 6 | inbox/workspaces |
| Inboxes | 8 | inbox/inboxes |
| Correos | 5 | inbox/emails |
| Agentes | 8 | inbox/agents |
| Ejecuciones y uso | 4 | inbox/agent_runs, inbox/usage |
| Webhooks | 11 | inbox/webhooks |
| Eventos de sistema | 2 | inbox/system_events |
| Secrets | 6 | inbox/secrets |
| Ejecuciones de workflow | 2 | inbox/workflow_runs |
| Identidad | 1 | ninguno (cualquier token) |
| Tool | Recurso | Tipo |
|---|---|---|
me | Identidad | lectura |
workspaces_list workspaces_get | Workspaces | lectura |
workspaces_create workspaces_upsert workspaces_update | Workspaces | escritura |
workspaces_delete | Workspaces | destructiva |
inboxes_list inboxes_get | Inboxes | lectura |
inboxes_create inboxes_upsert inboxes_update | Inboxes | escritura |
inboxes_delete inboxes_add_recipient inboxes_remove_recipient | Inboxes | destructiva |
emails_list emails_get emails_download_eml | Correos | lectura |
emails_reprocess emails_delete | Correos | destructiva |
agents_list agents_get agents_versions_list models_list | Agentes | lectura |
agents_create agents_upsert agents_update | Agentes | escritura |
agents_delete | Agentes | destructiva |
agent_runs_list agent_runs_get usage_summary usage_cost | Ejecuciones | lectura |
webhooks_list webhooks_get webhooks_deliveries_list webhooks_deliveries_get | Webhooks | lectura |
webhooks_create webhooks_upsert webhooks_update | Webhooks | escritura |
webhooks_delete webhooks_test webhooks_regenerate_secret webhooks_deliveries_replay | Webhooks | destructiva |
system_events_list system_events_get | Eventos de sistema | lectura |