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). 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 tools, sob as mesmas permissões e o mesmo escopo do token. Com um token só de leitura, resources e completions continuam disponíveis, mas um prompt que escreve — como collect_overdue_invoices, que manda lembretes — não aparece.

Resources

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

URI	O que volta
kobana://billing/organization	A organização do token (JSON)
kobana://billing/schemas	O catálogo de recursos da API (JSON)
kobana://billing/schemas/{resource}	Os campos de um recurso: tipo, enum, significado, quais ordenam (JSON)
kobana://billing/customers/{id}	Um cliente (JSON)
kobana://billing/subscriptions/{id}	Uma assinatura (JSON)
kobana://billing/invoices/{id}	Uma fatura (JSON)
kobana://billing/invoices/{id}/pdf	O PDF da fatura
kobana://billing/nfes/{id}	Uma NF-e (JSON)
kobana://billing/nfes/{id}/pdf	O DANFE da NF-e
kobana://billing/nfes/{id}/xml	O XML autorizado da NF-e (texto)

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

• Permissões. Cada resource é lido pela tool correspondente (kobana://billing/invoices/{id} é billing_invoices_get). Ele só aparece, e só é lido, se você pode rodar essa tool.
• Binários. PDFs voltam em base64 (blob), até 10 MB. Diferente das tools, que só descrevem 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 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. Ele só aparece se você pode rodar todas as tools em que se apoia.

Prompt	Argumentos	O que faz
collect_overdue_invoices	customer_id (opcional)	Lista as faturas em aberto vencidas, mostra uma tabela e pergunta quais devem receber lembrete antes de enviar.
review_pending_nfes	—	Junta as faturas que ainda não têm NF-e e as NF-e rejeitadas, resume e sugere o próximo passo, sem emitir nada.
customer_overview	customer_id	O retrato de um cliente: dados, assinaturas, o que está em aberto e o que está vencido.
monthly_billing_summary	month (opcional, YYYY-MM)	O que foi faturado, recebido e ficou em aberto no mês.

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

Completions

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

• Ids (customer_id, o {id} de clientes, faturas e assinaturas): busca na listagem correspondente, sob a mesma permissão dela. Se você não pode listar, não há sugestão.
• {resource} de kobana://billing/schemas/{resource}: os nomes do catálogo, 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, anulam ou estornam são marcadas com destructiveHint, e a maioria dos clientes já pede confirmação por causa disso. Na era 2026-07-28, o servidor também pede:

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: a mesma tool, os mesmos argumentos, a mesma pessoa e organização, por 5 minutos. Uma resposta não pode ser reaproveitada para outra fatura ou outra ação; se algo não bater, o servidor simplesmente pergunta de novo.

O servidor só pergunta a clientes que declaram suporte a formulários de elicitation. Na era 2025, ou com um cliente sem esse suporte, a tool roda direto, e a confirmação fica a cargo do próprio cliente.