Resources e prompts

Além das tools, o servidor oferece três coisas que o cliente usa por conta própria: resources (documentos que o usuário anexa à conversa), prompts (roteiros prontos que o usuário escolhe) e completions (autocomplete dos argumentos dos dois). E, antes de rodar uma tool destrutiva, ele pede a sua confirmação.

Nada disso abre um caminho novo até os seus dados: tudo passa pelas mesmas tools, sob o mesmo escopo do token e o mesmo papel da pessoa. Um resource ou um prompt que se apoia numa tool que você não pode rodar simplesmente não aparece.

Resources

Um resource é um documento identificado por uma URI. O usuário escolhe, por exemplo, uma execução, e o cliente lê o documento e o põe no contexto, sem que o modelo precise chamar uma tool. Todos voltam em JSON.

URI	O que volta	Tool que lê
`kobana://kadu/me`	A pessoa, a organização e os escopos da conexão	`kadu_me_get`
`kobana://kadu/repository`	O Kadu Playbook da organização e o catálogo de skills	`kadu_repository_get`
`kobana://kadu/operation_approvals`	As suas aprovações por link, das mais recentes para as mais antigas	`kadu_operation_approvals_list`
`kobana://kadu/operation_approvals/{id}`	Uma aprovação: o que foi pedido, a decisão e o resultado	`kadu_operation_approvals_get`
`kobana://kadu/workspaces/{id}`	Um workspace	`kadu_workspaces_get`
`kobana://kadu/activities/{id}`	Uma atividade	`kadu_activities_get`
`kobana://kadu/tasks/{id}`	Uma tarefa e o esquema dos parâmetros dela	`kadu_tasks_get`
`kobana://kadu/executions/{id}`	Uma execução	`kadu_executions_get`
`kobana://kadu/executions/{id}/events`	Os eventos que o agente reportou na execução	`kadu_executions_events_list`
`kobana://kadu/executions/{id}/logs`	Os logs da execução	`kadu_executions_logs_list`
`kobana://kadu/executions/{id}/todos`	As pendências que a execução abriu	`kadu_executions_todos_list`
`kobana://kadu/memories/{id}`	Uma memória do agente	`kadu_memories_get`
`kobana://kadu/environments/{id}`	Um ambiente	`kadu_environments_get`
`kobana://kadu/schedules/{id}`	Um agendamento	`kadu_schedules_get`

resources/list traz as URIs fixas e resources/templates/list os templates com {id}.

Permissões. Cada resource é lido pela tool da última coluna. Ele só aparece, e só é lido, se você pode rodar essa tool; senão a leitura volta -32602 com data.code: "insufficient_permission".
Sem binários. O conteúdo de um arquivo nunca vem como resource: ele é baixado pela URL pré-assinada de kadu_files_download.
Não encontrado. URI desconhecida, ou registro que não existe nesta organização, é -32002 na era 2025 e -32602 na 2026-07-28 — veja Erros.
Sem assinatura de mudanças. O servidor é stateless: não há resources/subscribe nem aviso de lista alterada.

Prompts

Um prompt é uma instrução pronta que você escolhe no cliente e que vira a primeira mensagem da conversa. No Kadu, todos só leem: disparar, cancelar ou mudar configuração é sempre você quem pede, explicitamente. Um prompt só aparece se você pode rodar todas as tools em que se apoia.

Prompt	Argumentos	O que faz
`review_failed_executions`	`since` (opcional, `AAAA-MM-DD`; padrão: sete dias atrás)	Lista as execuções que falharam desde a data e explica o que deu errado em cada uma, agrupando causas repetidas, sem rodar, cancelar ou continuar nada.
`explain_execution`	`execution_id`	Explica, passo a passo, o que o agente fez numa execução: os sistemas que tocou, o resultado e as pendências que ficaram para uma pessoa.
`monthly_usage_report`	`month` (`AAAA-MM`)	Resume uso e custo das execuções do mês, por tarefa e por workspace, e aponta as tarefas que mais custaram.
`check_task_readiness`	`task_id`, `environment_id`	Diz se a tarefa pode rodar agora naquele ambiente e, se não, exatamente o que falta (plano, teto de custo, secrets, repositório), sem disparar nada.

O roteiro já chega com as datas calculadas. Argumento obrigatório ausente, ou since e month fora do formato, é -32602.

Completions

completion/complete sugere valores enquanto você digita um argumento:

Ids (execution_id, task_id, environment_id e o {id} dos templates): os ids recentes da listagem correspondente, filtrados pelo que você já digitou, sob a mesma permissão dela. Se você não pode listar, não há sugestão.
month: os últimos doze meses.

No máximo 100 valores. Sem fonte de sugestão, a resposta é uma lista vazia, e você continua digitando.

Confirmação de tools destrutivas

Tools destrutivas são marcadas com destructiveHint:

toda tool de exclusão (*_delete, inclusive desabilitar o endpoint de disparo de uma tarefa);
kadu_tasks_run e kadu_executions_continue, que rodam o agente financeiro — e ele age em banco, ERP e notas fiscais;
kadu_executions_cancel;
kadu_webhook_deliveries_replay e kadu_webhooks_rotate_secret;
kadu_tasks_endpoint_update, que muda quem pode disparar o agente;
kadu_webhooks_create, e kadu_webhooks_update quando muda a url — para onde vão os dados da organização.

O servidor não confia só no cliente: ele mesmo exige a confirmação, de um de dois jeitos, conforme o cliente.

Confirmação no chat (era `2026-07-28`)

Quando o cliente fala a era 2026-07-28 e declara suporte a formulários de elicitation:

O primeiro tools/call não roda nada. Ele volta resultType: "input_required" com um formulário de uma pergunta: rodar esta ação, com estes argumentos?
O cliente mostra a pergunta e reenvia a mesma chamada com a sua resposta.
Só um sim explícito executa. Recusar ou cancelar volta um resultado isError com USER_DECLINED, e nada muda.

A confirmação vale só para aquela chamada: a mesma tool, os mesmos argumentos, a mesma pessoa e organização, por 5 minutos. Uma resposta não pode ser reaproveitada para outra tarefa ou outra ação; se algo não bater, o servidor simplesmente pergunta de novo. E ela é de uso único: reenviar uma chamada já confirmada volta isError com confirmation_replayed, sem executar nada — para repetir a ação, chame a tool de novo e confirme outra vez.

Cliente sem formulário de confirmação: aprovação por link

Um cliente que não consegue confirmar no chat — na era 2025, ou na 2026-07-28 sem declarar formulários de elicitation — também usa as tools destrutivas, mas por um link de aprovação. A chamada não executa nada: o servidor guarda a operação como pendente e responde com sucesso (sem isError), num ú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 …"
}

O assistente mostra a URL. Não chame a tool de novo: isso criaria outra aprovação.
Você abre o link logado no Kadu (sem sessão, ele passa pelo login e volta ao link). A tela mostra o que vai acontecer ("Executar a tarefa", "Excluir o ambiente"), quem pediu, quando, por qual cliente, os dados atuais do que a operação afeta e todos os argumentos que vão rodar.
Continuar executa a operação na hora, com as permissões que você tem agora: se perdeu a permissão ou o vínculo com a organização desde o pedido, ou se o token que pediu foi revogado, a execução falha e nada muda. Cancelar encerra sem executar nada.

O link vale 15 minutos e decide uma vez só: dois cliques em Continuar executam uma vez, e um link vencido ou cancelado não executa. Só você — a pessoa por trás do token que fez a chamada — abre o link: para qualquer outra pessoa, mesmo da sua organização, ele não existe.

Se o que a operação afeta mudar entre a abertura da tela e o Continuar (um webhook que trocou de URL, uma tarefa alterada), nada executa (subject_changed): peça a operação de novo e revise o novo link.

Suas aprovações ficam em Configurações › Aprovações no console, com abas por situação (Pendentes, Executadas, Canceladas, Com falha, Expiradas); clicar numa linha abre a aprovação só para leitura — uma pendente se decide pelo link que o assistente mostrou.

Acompanhar a aprovação

O próprio assistente acompanha a aprovação que pediu: com o id da resposta, kadu_operation_approvals_get (ou o resource kobana://kadu/operation_approvals/{id}) mostra a situação — pending, depois executed, failed, declined ou expired — e o que a operação retornou. O check_with só vem na resposta quando o chamador pode rodar essa leitura (escopo kadu/system_events e permissão agent.operation_approvals.read). O assistente deve consultar quando você disser que decidiu, não em laço.

A leitura nunca decide: não há tool nem rota da API que continue ou cancele uma aprovação. Se pudesse, quem pediu a operação também a aprovaria.

Um segredo no resultado — o novo segredo de assinatura de kadu_webhooks_rotate_secret — aparece em claro uma vez, na tela, logo depois do Continuar; a tool de leitura e a tela recarregada o mostram mascarado.

Quando a confirmação não é possível

Um token sem uma pessoa da organização que possa abrir o link volta isError com confirmation_required. Se o servidor não consegue registrar a confirmação ou a aprovação naquele momento, a tool é recusada com confirmation_unavailable; tente de novo depois. Nos dois casos nada é executado, e as demais tools seguem funcionando normalmente.

Resources​

Prompts​

Completions​

Confirmação de tools destrutivas​

Confirmação no chat (era 2026-07-28)​

Cliente sem formulário de confirmação: aprovação por link​

Acompanhar a aprovação​

Quando a confirmação não é possível​