Resources e prompts
Além das tools, o servidor oferece três coisas que o cliente usa por conta própria: resources (documentos que você anexa à conversa), prompts (roteiros prontos que você escolhe) e completions (autocompletar para os argumentos de ambos). Na era 2026-07-28, ele também pede confirmação antes de executar uma tool destrutiva.
Nada disso abre um caminho novo até os seus dados: tudo passa pelas mesmas tools, sob as mesmas permissões e os mesmos escopos. Todo resource e todo prompt daqui só lê, então um token somente-leitura alcança todos eles — desde que a pessoa possa executar as tools por trás deles.
Resources
Um resource é um documento identificado por uma URI. Você escolhe, por exemplo, um e-mail, e o cliente lê o registro e o coloca no contexto, sem que o modelo precise chamar uma tool. As URIs ficam sob kobana://inbox/, então convivem com as de outros produtos Kobana no mesmo cliente.
| URI | O que volta |
|---|---|
kobana://inbox/models | Os modelos de LLM em que um agente pode rodar, com seus preços (JSON) |
kobana://inbox/usage | E-mails processados, execuções, tokens e custo do workspace nos últimos 30 dias (JSON) |
kobana://inbox/workspaces/{id} | Um workspace, com seus limites (JSON) |
kobana://inbox/inboxes/{id} | Uma inbox: endereço, agente, remetentes, filtros e regras de anexo (JSON) |
kobana://inbox/emails/{id} | Um e-mail recebido: headers, corpo, anexos e status de processamento (JSON) |
kobana://inbox/emails/{id}/eml | Uma URL assinada de vida curta para baixar o .eml bruto (JSON) |
kobana://inbox/agents/{id} | Um agente de IA: modelo, mensagem de sistema e skills (JSON) |
kobana://inbox/agent-runs/{id} | Uma execução de agente: status, saída, tokens e custo (JSON) |
kobana://inbox/workflow-runs/{id} | Uma execução de workflow: os passos e o resultado de cada um (JSON) |
kobana://inbox/webhooks/{id} | Um webhook de saída: URL, eventos e status (JSON) |
kobana://inbox/system-events/{id} | Uma entrada do log de eventos, com seu payload (JSON) |
resources/list devolve as URIs fixas e resources/templates/list os templates parametrizados.
- Permissões. Cada resource é lido pela tool correspondente (
kobana://inbox/emails/{id}éemails_get). Ele só é listado, e só é lido, se você pode executar essa tool. - Secrets. Não há resource de secret — nem dos metadados. Use as tools
secrets_*. - Não encontrado. Uma URI desconhecida, ou um registro que não existe neste workspace, é
-32002na era 2025 e-32602no2026-07-28— veja Erros. - Sem assinatura de mudanças. O servidor é stateless: não há
resources/subscribenem aviso de lista alterada.
Prompts
Um prompt é uma instrução pronta que você escolhe no cliente e que vira a primeira mensagem da conversa. Ele só é listado se você pode executar todas as tools em que ele se apoia. Nenhum deles escreve: reprocessar um e-mail ou excluir qualquer coisa fica para você pedir explicitamente.
| Prompt | Argumentos | O que faz |
|---|---|---|
review_failed_runs | since (opcional, YYYY-MM-DD; padrão: últimos 7 dias), agent_id (opcional) | Encontra as execuções de agente que falharam, agrupa por causa e aponta os e-mails por trás delas. |
inbox_overview | inbox_id | O retrato de uma inbox: sua configuração, os e-mails mais recentes e como o agente dela está indo. |
webhook_health | — | Quais webhooks de saída estão falhando nas entregas, e desde quando. |
usage_report | month (opcional, YYYY-MM) | O que o workspace processou e gastou no mês, por modelo. |
Um argumento obrigatório ausente, ou since/month fora do formato, é -32602.
Completions
completion/complete sugere valores enquanto você digita um argumento:
- Ids (
inbox_id,agent_ide o parâmetro dos templates de registro): os registros mais recentes da listagem correspondente, pelo prefixo digitado, sob a mesma permissão. Se você não pode listar, não há sugestão. month: os últimos doze meses.
Sem fonte de sugestões, a resposta é uma lista vazia, e você continua digitando.
Confirmação de tools destrutivas
Tools que excluem, enviam algo para fora (webhooks_test, webhooks_deliveries_replay, emails_reprocess — o agente pode responder ou agir), rotacionam o segredo de um webhook ou mudam quem pode enviar para uma inbox (inboxes_add_recipient, inboxes_remove_recipient) são marcadas com destructiveHint. O servidor confirma cada uma delas com o usuário antes de executá-la:
- A primeira
tools/callnão executa nada. Ela volta comresultType: "input_required"e um formulário de uma pergunta: executar esta ação, com estes argumentos? - O cliente mostra a pergunta e envia a mesma chamada de novo com a sua resposta.
- Só um sim explícito a executa. Recusar ou cancelar volta como resultado
isErrorcomuser_declined, e nada muda.
A confirmação vale só para aquela chamada, e uma única vez: a mesma tool, os mesmos argumentos, a mesma pessoa, organização e workspace, por 5 minutos, e executa a ação uma só vez. Uma resposta não pode ser reaproveitada para outro registro ou outra ação — se algo não bater, o servidor simplesmente pergunta de novo — e enviar a mesma chamada confirmada uma segunda vez responde confirmation_replayed sem executar nada. Para executar de novo, chame a tool sem requestState e responda à nova pergunta.
Perguntar exige o protocolo 2026-07-28 e um cliente que declare suporte a formulários de elicitation. Nenhum outro cliente consegue executar uma tool destrutiva: na era 2025, ou sem esse suporte, a chamada responde confirmation_required e nada é executado. Se o servidor não conseguir registrar a confirmação naquele momento, a chamada responde confirmation_unavailable, também sem executar nada — tente de novo mais tarde.