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 (autocomplete dos argumentos dos dois). Na era 2026-07-28, ele também pede confirmação antes de rodar uma tool destrutiva — inclusive as que movem dinheiro.

Nada disso abre um caminho novo até os seus dados: tudo passa pelas mesmas tools, sob as mesmas permissões e o mesmo nível de acesso. Todo resource e todo prompt daqui só lê, então um token read alcança todos eles — desde que a pessoa possa rodar as tools por trás.

Resources

Um resource é um documento identificado por uma URI. Você escolhe, por exemplo, uma conta a pagar, e o cliente lê o registro e o põe no contexto, sem que o modelo precise chamar uma tool. As URIs ficam sob kobana://finance/, então convivem com as de outros produtos Kobana no mesmo cliente.

URI	O que volta
kobana://finance/schemas	O catálogo de schemas do contrato da API (JSON)
kobana://finance/schemas/{schema}	Um schema: os campos que uma tool devolve ou aceita (JSON)
kobana://finance/payables/{id}	Uma conta a pagar (JSON)
kobana://finance/receivables/{id}	Uma conta a receber (JSON)
kobana://finance/financial-transactions/{id}	Um lançamento (JSON)
kobana://finance/financial-accounts/{account_id}	Uma conta financeira (JSON)
kobana://finance/financial-accounts/{account_id}/balances/latest	O saldo registrado mais recente da conta (JSON)
kobana://finance/people/{id}	Uma pessoa — fornecedor, cliente ou os dois (JSON)
kobana://finance/companies/{id}	Uma empresa do workspace (JSON)
kobana://finance/fiscal-documents/{id}	Um documento fiscal recebido (JSON)
kobana://finance/attachments/{attachment_id}	Os dados de um anexo e a que ele está vinculado (JSON)
kobana://finance/attachments/{attachment_id}/download	O arquivo do anexo — comprovante, boleto, XML

resources/list traz as URIs fixas e resources/templates/list os templates com parâmetro.

• Permissões. Cada resource é lido pela tool correspondente (kobana://finance/payables/{id} é finance_payables_get). Ele só aparece, e só é lido, se você pode rodar essa tool.
• Arquivos. O arquivo de um anexo volta como bytes em base64 (blob), ou como texto quando é texto (um XML), até 10 MB. Diferente da tool, que só descreve o arquivo, aqui o documento é a resposta: foi o cliente que pediu por ele.
• Não encontrado. URI desconhecida, ou registro que não existe neste workspace, é -32002 na era 2025 e -32602 na 2026-07-28 — veja Erros.
• Workspace. A URI não carrega workspace: o resource é lido no workspace padrão da conexão. Sem padrão — a pessoa alcança vários workspaces e a conexão não fixou um —, ler um resource de registro falha com workspace_required; use as tools, que aceitam workspace_id. O catálogo de schemas não depende de workspace.
• 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. Ele só aparece se você pode rodar todas as tools em que se apoia. Nenhum deles move dinheiro, edita ou apaga: mandar ao banco ou cobrar fica para você pedir explicitamente.

Prompt	Argumentos	O que faz
overdue_payables	company_id (opcional)	Lista as contas a pagar vencidas e ainda em aberto, da mais antiga, com o total devido.
overdue_receivables	person_id (opcional)	Lista as contas a receber vencidas e agrupa por cliente, maiores totais primeiro.
cash_flow_outlook	until (opcional, YYYY-MM-DD; padrão: 90 dias)	O saldo de hoje e para onde o caixa vai, semana a semana, com o ponto mais baixo.
monthly_summary	month (opcional, YYYY-MM)	O que foi pago, recebido e ficou em aberto no mês.
person_overview	person_id	Um fornecedor ou cliente: os dados e o que está em aberto de cada lado.

Argumento obrigatório ausente, ou month/until fora do formato, é -32602.

Completions

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

• Ids (person_id, company_id, account_id e o parâmetro dos templates de registro): os registros mais recentes da listagem correspondente, pelo prefixo digitado, sob a mesma permissão dela. Se você não pode listar, não há sugestão. Os registros saem do workspace padrão da conexão; sem padrão, a lista volta vazia.
• {schema} de kobana://finance/schemas/{schema}: os nomes do contrato, pelo prefixo.
• month: os últimos doze meses.

Sem fonte de sugestão, a resposta é uma lista vazia, e você continua digitando.

Confirmação de tools destrutivas

Tools que apagam, cancelam, mandam pagamento ao banco, cobram, transferem entre contas, conciliam ou ajustam saldo são marcadas com destructiveHint. O cliente pode ou não pedir confirmação por causa disso — então o servidor pede, e uma tool destrutiva só roda com a confirmação dele:

1. 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?
2. O cliente mostra a pergunta e reenvia a mesma chamada com a sua resposta.
3. 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 e uma vez só: a mesma tool, os mesmos argumentos, a mesma pessoa, organização e workspace, por 5 minutos. Uma resposta não pode ser reaproveitada para outro título ou outra ação; se algo não bater, o servidor simplesmente pergunta de novo. Reenviar uma confirmação que já rodou a tool volta confirmation_replayed — para repetir a ação, chame a tool de novo sem requestState e confirme outra vez.

Sem confirmação possível, a tool não roda. O servidor só consegue perguntar na era 2026-07-28, a clientes que declaram suporte a formulários de elicitation (elicitation: {} ou elicitation: { form: {} } nas clientCapabilities). Na era 2025, ou com um cliente sem esse suporte, um tools/call de tool destrutiva volta isError com confirmation_required e nada é alterado — leituras e escritas comuns continuam rodando. Se o próprio servidor não puder garantir a confirmação naquele momento, a resposta é confirmation_unavailable, também sem alterar nada.