Resources y prompts

Además de las tools, el servidor ofrece tres cosas que el cliente usa por su cuenta: resources (documentos que el usuario adjunta a la conversación), prompts (guiones listos que el usuario elige) y completions (autocompletado de sus argumentos). En la era 2026-07-28 también pide confirmación antes de ejecutar una tool destructiva.

Nada de esto abre un camino nuevo hacia tus datos: todo pasa por las mismas tools, con los mismos permisos y el mismo alcance del token. Con un token solo de lectura, los resources y las completions siguen disponibles, pero un prompt que escribe — como collect_overdue_invoices, que envía recordatorios — no aparece.

Resources

Un resource es un documento identificado por una URI. El usuario elige, por ejemplo, una factura, y el cliente lee el documento y lo pone en el contexto, sin que el modelo tenga que llamar a una tool.

URI	Qué vuelve
kobana://billing/organization	La organización del token (JSON)
kobana://billing/schemas	El catálogo de recursos de la API (JSON)
kobana://billing/schemas/{resource}	Los campos de un recurso: tipo, enum, significado, cuáles ordenan (JSON)
kobana://billing/customers/{id}	Un cliente (JSON)
kobana://billing/subscriptions/{id}	Una suscripción (JSON)
kobana://billing/invoices/{id}	Una factura (JSON)
kobana://billing/invoices/{id}/pdf	El PDF de la factura
kobana://billing/nfes/{id}	Una NF-e (JSON)
kobana://billing/nfes/{id}/pdf	El DANFE de la NF-e
kobana://billing/nfes/{id}/xml	El XML autorizado de la NF-e (texto)

resources/list trae las URIs fijas y resources/templates/list las plantillas con {id}.

• Permisos. Cada resource se lee con la tool correspondiente (kobana://billing/invoices/{id} es billing_invoices_get). Solo aparece, y solo se lee, si puedes ejecutar esa tool.
• Binarios. Los PDF vuelven en base64 (blob), hasta 10 MB. A diferencia de las tools, que solo describen el archivo, aquí el documento es la respuesta: lo pidió el cliente.
• No encontrado. Una URI desconocida, o un registro que no existe en esta organización, es -32002 en la era 2025 y -32602 en la 2026-07-28 — ve Errores.
• Sin suscripción a cambios. El servidor es stateless: no hay resources/subscribe ni aviso de lista cambiada.

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.

Prompt	Argumentos	Qué hace
collect_overdue_invoices	customer_id (opcional)	Lista las facturas abiertas vencidas, muestra una tabla y pregunta cuáles deben recibir recordatorio antes de enviar.
review_pending_nfes	—	Junta las facturas que aún no tienen NF-e y las NF-e rechazadas, las resume y sugiere el próximo paso, sin emitir nada.
customer_overview	customer_id	El retrato de un cliente: datos, suscripciones, lo que está abierto y lo que está vencido.
monthly_billing_summary	month (opcional, YYYY-MM)	Lo que se facturó, se cobró y quedó abierto en el mes.

Un argumento obligatorio ausente, o un month mal formado, es -32602.

Completions

completion/complete sugiere valores mientras escribes un argumento:

• Ids (customer_id, y el {id} de clientes, facturas y suscripciones): busca en el listado correspondiente, con su mismo permiso. Si no puedes listar, no hay sugerencia.
• {resource} de kobana://billing/schemas/{resource}: los nombres del catálogo, 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, anulan o reembolsan llevan destructiveHint, y la mayoría de los clientes ya piden confirmación por eso. En la era 2026-07-28 el servidor también pregunta:

1. El primer tools/call no ejecuta nada. Vuelve con resultType: "input_required" y un formulario de una pregunta: ¿ejecutar esta acción, con estos argumentos?
2. El cliente muestra la pregunta y reenvía la misma llamada con tu respuesta.
3. Solo un sí explícito la ejecuta. Rechazar o cancelar devuelve un resultado isError con USER_DECLINED, y nada cambia.

La confirmación vale solo para esa llamada: la misma tool, los mismos argumentos, la misma persona y organización, durante 5 minutos. Una respuesta no puede reutilizarse para otra factura u otra acción; si algo no coincide, el servidor simplemente vuelve a preguntar.

El servidor solo pregunta a clientes que declaran soporte para formularios de elicitation. En la era 2025, o con un cliente sin ese soporte, la tool se ejecuta directo y la confirmación queda a cargo del propio cliente.