Resources y prompts
Además de las tools, el servidor ofrece tres cosas que el cliente usa por su cuenta: resources (documentos que adjuntas a la conversación), prompts (guiones listos que eliges) y completions (autocompletado de los argumentos de ambos). En la era 2026-07-28, también pide confirmación antes de ejecutar una tool destructiva — incluidas las que mueven dinero.
Nada de esto abre un camino nuevo hasta tus datos: todo pasa por las mismas tools, bajo los mismos permisos y el mismo nivel de acceso. Todo resource y todo prompt de aquí solo lee, así que un token read los alcanza a todos — siempre que la persona pueda ejecutar las tools que hay detrás.
Resources
Un resource es un documento identificado por una URI. Eliges, por ejemplo, una cuenta por pagar, y el cliente lee el registro y lo pone en el contexto, sin que el modelo tenga que llamar una tool. Las URIs quedan bajo kobana://finance/, así que conviven con las de otros productos Kobana en el mismo cliente.
| URI | Qué vuelve |
|---|---|
kobana://finance/schemas | El catálogo de schemas del contrato de la API (JSON) |
kobana://finance/schemas/{schema} | Un schema: los campos que una tool devuelve o acepta (JSON) |
kobana://finance/payables/{id} | Una cuenta por pagar (JSON) |
kobana://finance/receivables/{id} | Una cuenta por cobrar (JSON) |
kobana://finance/financial-transactions/{id} | Un movimiento (JSON) |
kobana://finance/financial-accounts/{account_id} | Una cuenta financiera (JSON) |
kobana://finance/financial-accounts/{account_id}/balances/latest | El saldo registrado más reciente de la cuenta (JSON) |
kobana://finance/people/{id} | Una persona — proveedor, cliente o ambos (JSON) |
kobana://finance/companies/{id} | Una empresa del workspace (JSON) |
kobana://finance/fiscal-documents/{id} | Un documento fiscal recibido (JSON) |
kobana://finance/attachments/{attachment_id} | Los datos de un adjunto y a qué está vinculado (JSON) |
kobana://finance/attachments/{attachment_id}/download | El archivo del adjunto — comprobante, boleto, XML |
resources/list trae las URIs fijas y resources/templates/list los templates con parámetro.
- Permisos. Cada resource se lee con la tool correspondiente (
kobana://finance/payables/{id}esfinance_payables_get). Solo aparece, y solo se lee, si puedes ejecutar esa tool. - Archivos. El archivo de un adjunto vuelve como bytes en base64 (
blob), o como texto cuando es texto (un XML), hasta 10 MB. A diferencia de la tool, que solo describe el archivo, aquí el documento es la respuesta: fue el cliente quien lo pidió. - No encontrado. Una URI desconocida, o un registro que no existe en este workspace, es
-32002en la era 2025 y-32602en la2026-07-28— ver Errores. - Workspace. La URI no lleva workspace: el resource se lee en el workspace predeterminado de la conexión. Sin predeterminado — la persona alcanza varios workspaces y la conexión no fijó uno —, leer un resource de registro falla con
workspace_required; usa las tools, que aceptanworkspace_id. El catálogo de schemas no depende de un workspace. - Sin suscripción a cambios. El servidor es stateless: no hay
resources/subscribeni aviso de lista modificada.
Prompts
Un prompt es una instrucción lista que eliges en el cliente y que se convierte en el primer mensaje de la conversación. Solo aparece si puedes ejecutar todas las tools en las que se apoya. Ninguno mueve dinero, edita ni borra: enviar al banco o cobrar queda para que lo pidas explícitamente.
| Prompt | Argumentos | Qué hace |
|---|---|---|
overdue_payables | company_id (opcional) | Lista las cuentas por pagar vencidas y todavía abiertas, de la más antigua, con el total adeudado. |
overdue_receivables | person_id (opcional) | Lista las cuentas por cobrar vencidas y las agrupa por cliente, mayores totales primero. |
cash_flow_outlook | until (opcional, YYYY-MM-DD; por defecto: 90 días) | El saldo de hoy y hacia dónde va la caja, semana a semana, con el punto más bajo. |
monthly_summary | month (opcional, YYYY-MM) | Lo que se pagó, se cobró y quedó abierto en el mes. |
person_overview | person_id | Un proveedor o cliente: sus datos y lo que está abierto de cada lado. |
Un argumento obligatorio ausente, o month/until fuera de formato, es -32602.
Completions
completion/complete sugiere valores mientras escribes un argumento:
- Ids (
person_id,company_id,account_idy el parámetro de los templates de registro): los registros más recientes del listado correspondiente, por el prefijo escrito, bajo el mismo permiso de ese listado. Si no puedes listar, no hay sugerencia. Los registros salen del workspace predeterminado de la conexión; sin él, la lista vuelve vacía. {schema}dekobana://finance/schemas/{schema}: los nombres del contrato, por prefijo.month: los últimos doce meses.
Sin fuente de sugerencias, la respuesta es una lista vacía, y sigues escribiendo.
Confirmación de tools destructivas
Las tools que borran, cancelan, envían un pago al banco, cobran, transfieren entre cuentas, concilian o ajustan un saldo están marcadas con destructiveHint. El cliente puede o no pedir confirmación por eso — así que el servidor la pide, y una tool destructiva solo se ejecuta con su confirmación:
- El primer
tools/callno ejecuta nada. VuelveresultType: "input_required"con un formulario de una pregunta: ¿ejecutar esta acción, con estos argumentos? - El cliente muestra la pregunta y reenvía la misma llamada con tu respuesta.
- Solo un sí explícito ejecuta. Rechazar o cancelar devuelve un resultado
isErrorconUSER_DECLINED, y nada cambia.
La confirmación vale solo para esa llamada y una sola vez: la misma tool, los mismos argumentos, la misma persona, organización y workspace, durante 5 minutos. Una respuesta no puede reutilizarse para otro título u otra acción; si algo no coincide, el servidor simplemente vuelve a preguntar. Reenviar una confirmación que ya ejecutó la tool devuelve confirmation_replayed — para repetir la acción, llama la tool de nuevo sin requestState y confirma otra vez.
Sin confirmación posible, la tool no se ejecuta. El servidor solo puede preguntar en la era 2026-07-28, a clientes que declaran soporte a formularios de elicitation (elicitation: {} o elicitation: { form: {} } en clientCapabilities). En la era 2025, o con un cliente sin ese soporte, un tools/call de una tool destructiva devuelve isError con confirmation_required y nada cambia — las lecturas y escrituras comunes siguen ejecutándose. Si el propio servidor no puede garantizar la confirmación en ese momento, la respuesta es confirmation_unavailable, tampoco cambia nada.