Tools
O servidor expõe 53 tools sobre dez recursos. Cada uma espelha um endpoint de /v1 e despacha para ele in-process, então o comportamento — filtros, casamento de upsert, validação, soft-delete, isolamento por workspace — é idêntico ao da API REST.
Como ler estas páginas
Toda tool é documentada com a mesma linha de cabeçalho:
Leitura · escopo
inbox/emails· permissãoemails.show·GET /emails/{id}
| Campo | Significado |
|---|---|
| Leitura / Escrita / Destrutiva | A annotation que o cliente enxerga. Uma tool destrutiva exclui dados, envia algo para fora (teste ou reenvio de webhook, reprocessamento por um agente que pode responder ou agir), rotaciona um segredo ou muda quem pode enviar para uma inbox. Ela só roda depois de o servidor pedir confirmação ao usuário, o que exige o protocolo 2026-07-28 com elicitation; qualquer outro cliente recebe confirmation_required — veja Confirmação de tools destrutivas. |
| escopo | O que o token do cliente conectado precisa alcançar. Uma escrita exige o escopo do recurso e o verbo global write — ou o nível de acesso write/all, dentro dos recursos do token. Veja Escopos. |
| permissão | O que a pessoa por trás do token precisa ter na organização. |
O MÉTODO /path | O endpoint de /v1 para o qual a tool despacha, para conferência com a referência da API. |
Parâmetros marcados como obrigatório precisam estar presentes; todo o resto é opcional. Uma tool que você não pode executar sequer aparece em tools/list. As tools de leitura também sustentam os resources sob kobana://inbox/.
Parâmetros comuns
Estes aparecem em várias tools e significam sempre a mesma coisa.
| Parâmetro | Tipo | Descrição |
|---|---|---|
cursor | string | Cursor opaco de uma página anterior (meta.next_cursor). |
limit | integer | Tamanho da página, padrão 25, máximo 100. |
sort | string | Chaves de ordenação separadas por vírgula, prefixo - para descendente (p.ex. -created_at). |
idempotency_key | string | Proteção contra replay, 8–255 caracteres, enviada como X-Idempotency-Key. A mesma chave dentro de 24h retorna a resposta original. |
custom_metadata | object | JSON livre, seu; ecoado em toda leitura e em todo payload de webhook. |
<campo>_gte / <campo>_lte | string | Filtro de intervalo ISO 8601 sobre aquele campo. |
O catálogo
| Recurso | Tools | Escopo de leitura |
|---|---|---|
| Workspaces | 6 | inbox/workspaces |
| Inboxes | 8 | inbox/inboxes |
| E-mails | 5 | inbox/emails |
| Agentes | 8 | inbox/agents |
| Execuções e uso | 4 | inbox/agent_runs, inbox/usage |
| Webhooks | 11 | inbox/webhooks |
| Eventos de sistema | 2 | inbox/system_events |
| Secrets | 6 | inbox/secrets |
| Execuções de workflow | 2 | inbox/workflow_runs |
| Identidade | 1 | nenhum (qualquer token) |
| Tool | Recurso | Tipo |
|---|---|---|
me | Identidade | leitura |
workspaces_list workspaces_get | Workspaces | leitura |
workspaces_create workspaces_upsert workspaces_update | Workspaces | escrita |
workspaces_delete | Workspaces | destrutiva |
inboxes_list inboxes_get | Inboxes | leitura |
inboxes_create inboxes_upsert inboxes_update | Inboxes | escrita |
inboxes_delete inboxes_add_recipient inboxes_remove_recipient | Inboxes | destrutiva |
emails_list emails_get emails_download_eml | E-mails | leitura |
emails_reprocess emails_delete | E-mails | destrutiva |
agents_list agents_get agents_versions_list models_list | Agentes | leitura |
agents_create agents_upsert agents_update | Agentes | escrita |
agents_delete | Agentes | destrutiva |
agent_runs_list agent_runs_get usage_summary usage_cost | Execuções | leitura |
webhooks_list webhooks_get webhooks_deliveries_list webhooks_deliveries_get | Webhooks | leitura |
webhooks_create webhooks_upsert webhooks_update | Webhooks | escrita |
webhooks_delete webhooks_test webhooks_regenerate_secret webhooks_deliveries_replay | Webhooks | destrutiva |
system_events_list system_events_get | Eventos de sistema | leitura |