Resources e prompts
Além das tools, o servidor oferece três coisas que o cliente usa por conta própria: resources (registros 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.
Nada disso abre um caminho novo até os seus dados: tudo passa pelas mesmas barreiras das tools, com o mesmo escopo do token e as mesmas permissões.
Resources
Um resource é um registro identificado por uma URI. Você escolhe, por exemplo, um boleto, e o cliente lê o registro e o põe no contexto sem que o modelo precise chamar uma tool. As URIs seguem a forma kobana://banking/<família>/<recurso>/{uid}.
- Permissões. Cada resource é lido pela tool de leitura correspondente:
kobana://banking/charge/bank_billets/{uid}ébanking_charge_bank_billet_get. Ele só aparece emresources/templates/list, e só é lido, se você pode rodar essa tool. resources/listtraz as URIs dos 20 registros mais recentes de cada tipo que você pode listar e ler. Alguns tipos, como os eventos, ficam fora dessa lista e só são lidos pela URI.- Formato. O conteúdo é o JSON do registro, no mesmo formato da API, sem id numérico.
- Não encontrado. URI desconhecida, ou registro que não existe nesta conta, é
-32002nas versões de 2025 e-32602na2026-07-28. Um template que você não pode ler responde com a recusa (insufficient_scope,insufficient_permission), não com "não encontrado". - Sem assinatura de mudanças. O servidor é stateless: não há
resources/subscribenem aviso de lista alterada.
Os 60 templates de resource
| URI | O que é | Lido pela tool |
|---|---|---|
kobana://banking/charge/bank_billets/{uid} | Charge bank billet | banking_charge_bank_billet_get |
kobana://banking/charge/pix/{uid} | Charge Pix | banking_charge_pix_get |
kobana://banking/charge/bank_billet_accounts/{uid} | Charge bank billet account | banking_charge_bank_billet_account_get |
kobana://banking/charge/bank_billet_payments/{uid} | Charge bank billet payment | banking_charge_bank_billet_payment_get |
kobana://banking/charge/bank_billet_registrations/{uid} | Charge bank billet registration | banking_charge_bank_billet_registration_get |
kobana://banking/charge/bank_billet_remittances/{uid} | Charge bank billet remittance | banking_charge_bank_billet_remittance_get |
kobana://banking/charge/bank_billet_discharges/{uid} | Charge bank billet discharge | banking_charge_bank_billet_discharge_get |
kobana://banking/charge/customer_subscriptions/{uid} | Charge customer subscription | banking_charge_customer_subscription_get |
kobana://banking/charge/discharges/{uid} | Charge discharge | banking_charge_discharge_get |
kobana://banking/charge/installments/{uid} | Charge installment plan | banking_charge_installment_get |
kobana://banking/charge/payments/{uid} | Charge payment | banking_charge_payment_get |
kobana://banking/charge/pix_accounts/{uid} | Charge Pix account | banking_charge_pix_account_get |
kobana://banking/charge/remittances/{uid} | Charge remittance | banking_charge_remittance_get |
kobana://banking/charge/automatic_pix/accounts/{uid} | Charge Pix Automático account | banking_charge_automatic_pix_account_get |
kobana://banking/charge/automatic_pix/locations/{uid} | Charge Pix Automático location | banking_charge_automatic_pix_location_get |
kobana://banking/charge/automatic_pix/pix/{uid} | Charge Pix Automático charge | banking_charge_automatic_pix_pix_get |
kobana://banking/charge/automatic_pix/recurrences/{uid} | Charge Pix Automático recurrence | banking_charge_automatic_pix_recurrence_get |
kobana://banking/charge/automatic_pix/requests/{uid} | Charge Pix Automático request | banking_charge_automatic_pix_request_get |
kobana://banking/payment/payments/{uid} | Payment | banking_payment_payment_get |
kobana://banking/payment/bank_billets/{uid} | Bank billet payment | banking_payment_bank_billet_get |
kobana://banking/payment/pix/{uid} | Pix payment | banking_payment_pix_get |
kobana://banking/payment/batches/{uid} | Payment batch | banking_payment_batch_get |
kobana://banking/payment/payment_accounts/{uid} | Payment account | banking_payment_payment_account_get |
kobana://banking/payment/darfs/{uid} | DARF payment | banking_payment_darf_get |
kobana://banking/payment/taxes/{uid} | Tax payment | banking_payment_tax_get |
kobana://banking/payment/utilities/{uid} | Utility payment | banking_payment_utility_get |
kobana://banking/payment/dda_accounts/{uid} | DDA account | banking_payment_dda_account_get |
kobana://banking/payment/dda_bank_billets/{uid} | DDA bank billet | banking_payment_dda_bank_billet_get |
kobana://banking/transfer/transfers/{uid} | Transfer | banking_transfer_transfer_get |
kobana://banking/transfer/ted/{uid} | TED transfer | banking_transfer_ted_get |
kobana://banking/transfer/pix/{uid} | Pix transfer | banking_transfer_pix_get |
kobana://banking/transfer/internal/{uid} | Internal transfer | banking_transfer_internal_get |
kobana://banking/transfer/batches/{uid} | Transfer batch | banking_transfer_batch_get |
kobana://banking/transfer/transfer_accounts/{uid} | Transfer account | banking_transfer_transfer_account_get |
kobana://banking/financial/accounts/{uid} | Financial account | banking_financial_account_get |
kobana://banking/financial/balances/{uid} | Financial account balance | banking_financial_balance_get |
kobana://banking/financial/statement_transaction_imports/{uid} | Statement import | banking_financial_statement_transaction_import_get |
kobana://banking/financial/statement_transaction_syncs/{uid} | Statement sync | banking_financial_statement_transaction_sync_get |
kobana://banking/data/customers/{uid} | Customer | banking_data_customer_get |
kobana://banking/data/people/{uid} | Person | banking_data_person_get |
kobana://banking/data/events/{uid} | Event | banking_data_event_get |
kobana://banking/data/imports/{uid} | Import | banking_data_import_get |
kobana://banking/data/email_deliveries/{uid} | E-mail delivery | banking_data_email_delivery_get |
kobana://banking/data/webhooks/{uid} | Webhook | banking_data_webhook_get |
kobana://banking/data/bank_billet_queries/{uid} | Bank billet query | banking_data_bank_billet_query_get |
kobana://banking/automation/email_accounts/{uid} | E-mail account | banking_automation_email_account_get |
kobana://banking/admin/commands/{uid} | Command | banking_admin_command_get |
kobana://banking/admin/connections/{uid} | Bank connection | banking_admin_connection_get |
kobana://banking/admin/subaccounts/{uid} | Subaccount | banking_admin_subaccount_get |
kobana://banking/admin/transactions/{uid} | Billing transaction | banking_admin_transaction_get |
kobana://banking/edi/edi_boxes/{uid} | EDI box | banking_edi_edi_box_get |
kobana://banking/remittance/payments/{uid} | Payment remittance | banking_remittance_payment_get |
kobana://banking/data/pix_qrcode_queries/{uid} | Pix QR code query | banking_data_pix_qrcode_query_get |
kobana://banking/mailbox/entries/{uid} | Mailbox entry | banking_mailbox_entry_get |
kobana://banking/mailbox/files/{uid} | Mailbox file | banking_mailbox_file_get |
kobana://banking/mailbox/channels/email/{uid} | Mailbox e-mail channel | banking_mailbox_channels_email_get |
kobana://banking/mailbox/channels/s3/{uid} | Mailbox S3 channel | banking_mailbox_channels_s3_get |
kobana://banking/mailbox/channels/sftp/{uid} | Mailbox SFTP channel | banking_mailbox_channels_sftp_get |
kobana://banking/mailbox/channels/syncthing/{uid} | Mailbox Syncthing channel | banking_mailbox_channels_syncthing_get |
kobana://banking/mailbox/channels/whatsapp/{uid} | Mailbox WhatsApp channel | banking_mailbox_channels_whatsapp_get |
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.
| Prompt | Argumentos | O que faz | Escreve? |
|---|---|---|---|
banking_charge_overdue_bank_billets_review | due_before (opcional, YYYY-MM-DD; padrão, hoje) | Lista os boletos vencidos e não pagos e resume por pagador | Não |
banking_charge_explain_bank_billet | bank_billet_uid | Explica a situação de um boleto, o registro no banco, os pagamentos e o que ainda dá para fazer com ele | Não |
banking_charge_collect_overdue_bank_billets | due_before (opcional) | Mostra os boletos vencidos e envia lembrete por e-mail aos pagadores que você escolher, depois de perguntar | Sim |
O roteiro entrega datas já calculadas, nunca "antes de hoje". Argumento obrigatório ausente, ou data fora de YYYY-MM-DD, é -32602. Pedir pelo nome um prompt que você não pode usar também é -32602.
Completions
completion/complete sugere valores enquanto você digita um argumento:
| Argumento | Sugestões |
|---|---|
bank_billet_uid (prompt) e o {uid} de um template de resource | Os uids dos 100 boletos mais recentes que começam com o que você digitou, se você pode listar boletos. Hoje a sugestão é de boletos em qualquer template |
due_before (prompt) | Hoje e o primeiro dia de cada um dos últimos 12 meses |
| qualquer outro argumento | Lista vazia |
As sugestões vêm dos registros mais recentes, e não de uma busca por texto, porque prefixo de identificador não é uma consulta barata nas tabelas de boleto.
Confirmação de tools destrutivas
São marcadas com destructiveHint, entre outras:
- as tools que cancelam, protestam, dão baixa, registram pagamento, pagam, transferem, aprovam, tiram da remessa ou excluem;
- as que mudam para onde dado ou dinheiro sai da conta: criar ou alterar webhook, canal da caixa postal (e-mail, WhatsApp, Syncthing, S3, SFTP), conta financeira (os dados bancários), conta Pix (a chave), conta de e-mail (o endereço de resposta), conta DDA e caixa EDI (quem assina a carta), e os dados de um favorecido salvo;
- a criação de subconta, que pode criar um usuário master para o e-mail informado.
A marca de cada tool está no catálogo, na coluna Tipo. Nem todo envio é destrutivo: mandar um boleto ao pagador por e-mail ou SMS (banking_charge_bank_billet_send_email, banking_charge_bank_billet_send_sms) não é.
O critério da segunda e da terceira lista é que um endereço plantado num dado que o agente leu não chegue a terceiro sem você ver.
Na era 2026-07-28, o servidor pergunta
Com um cliente que declara suporte a formulário de elicitation (clientCapabilities.elicitation), o servidor pede a confirmação, sem depender do cliente:
- O primeiro
tools/callnão roda nada. Ele voltaresultType: "input_required"com uma pergunta de sim ou não, que mostra a tool e os argumentos que o modelo escolheu. - 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
isErrorcomuser_declined, e nada muda.
A confirmação vale só para aquela chamada: a mesma tool, os mesmos argumentos, a mesma pessoa e a mesma conta, por 5 minutos. E ela é de uso único: reenviar uma chamada já confirmada, como faz um cliente que tenta de novo depois de um timeout, não roda a tool de novo. Você é perguntado outra vez, com o aviso de que aquela aprovação já foi usada e pode já ter executado a ação.
Nas versões de 2025, quem pergunta é o cliente
Nas versões de 2025 do protocolo, ou com um cliente que não declara formulário de elicitation, o servidor não tem como perguntar no meio da chamada: a tool roda direto. Vale a confirmação que o próprio cliente pede ao ver o destructiveHint, e um cliente pode não pedir nenhuma: um script seu, por exemplo. Use cliente na revisão 2026-07-28 com elicitation, ou um token só de leitura, quando quiser a garantia do lado do servidor.