Pipeline de API: escribir una agenda para tus oráculos

Índice: Pipelines de API — índice

Objetivo: escribir una agenda —las instrucciones y la persona con las que trabajan tus oráculos y campañas— y leer una agenda pública.

Una agenda es una tarjeta que agrupa artículos de instrucciones, endpoints de API y secretos. Hay dos tipos:

• fwag (firmware, por defecto): se queda con una cuenta haga lo que haga: protocolo, identidad, habilidades y herramientas base. Puede apuntar a una agenda intercambiable para su tarea por defecto.
• swag (intercambiable): lo que una cuenta hace ahora mismo; la referencia una agenda firmware o la lleva una campaña.

Pasos

1. Escribe las instrucciones como artículos (pueden ser privados): Pipeline de API: escribir artículos y publicaciones

2. Crea la agenda.

POST /v0/my/agendas
Idempotency-Key: ag-93e0…
{"title": "Bakery front desk", "description": "Answers customers of Green Bakery.",
 "kind": "fwag", "project": "470000000000000001",
 "instructions": ["470000000000000042"], "api_endpoints": ["470000000000000420"], "secrets": ["470000000000000410"]}
→ {"app": {"nonce": "470000000000000500", "card_type": "agenda", "kind": "fwag",
           "lists": {"instructions": [{…tile…}], "api_endpoints": [{…}], "secrets": [{…}], "swag": []}, …}}

• Solo title es obligatorio. handle se guarda como ag.<handle>.
• instructions acepta artículos, api_endpoints tarjetas de endpoint, secrets secretos, o espacios que los contengan. Cada uno debe ser tuyo o estar compartido contigo con execute. Herramientas: Pipeline de API: dar herramientas a tu oráculo
• swag: una agenda intercambiable que posees o puedes ejecutar (solo agendas firmware).
• visibility, permissions, publicity, project como en cualquier tarjeta.

3. Ajusta el modelo.

PATCH /v0/my/agendas/470000000000000500
{"llm": {"model": "<model id>", "reasoning": "low"}}

• reasoning: off, low, medium, high. El modelo se fija solo con PATCH (no al crear).
• PATCH también acepta title, description, handle, kind, swag ("" lo vacía), las tres listas (cada una reemplaza la anterior) y los campos de visibilidad; una agenda intercambiable acepta además follow_ups {"enabled": true, "rungs": ["…"]}.

4. Revisa el prompt ensamblado.

GET /v0/graph/agendas/470000000000000500/prompt
→ 200 text/plain (ETag)       send If-None-Match: <etag> → 304 when unchanged

Requiere write sobre la agenda. Con If-None-Match: <etag> responde 304 si no ha cambiado.

5. Úsala. Asigna la agenda a un oráculo o a una campaña (campo agenda de esas tarjetas).

6. Leer, compartir, eliminar. Las tuyas: GET /v0/my/agendas, GET /v0/my/agendas/{nonce|@handle}. Una agenda pública: GET /v0/graph/agendas/{nonce|@handle} (sus listas solo las ven los editores). DELETE /v0/my/agendas/{ident}. Una agenda puede reclamar un enlace de acceso compartido con ella: POST /v0/my/agendas/{ident}/claim {"token": "<token>"} (ver «Compartir con enlaces» en el índice).

7. Quién puede ejecutar tu agenda. Quien ejecuta una agenda usa IA pagada por su dueño, así que solo tú ejecutas tus agendas, más las personas y agendas con las que compartas una para ejecutarla: un enlace de acceso con ejecución que ellas reclaman, o una concesión tuya (Pipeline de API: compartir tarjetas con enlaces de acceso). El permiso de ejecución de la propia tarjeta de la agenda no deja ejecutarla a nadie más, sea cual sea su visibilidad. La lectura sigue la visibilidad de la tarjeta, como siempre.

8. Ver qué tiene tu agenda.

GET /v0/my/agendas/470000000000000500/access
→ {"agenda": "470000000000000500", "total": 1,
   "access": [{"tile": {"card_type": "room", "nonce": "470000000000000300", …},
               "active": true, "private": false,
               "rights": {"read": true, "write": false, "execute": false},
               "grants": [{"kind": "link", "issuer": "<card owner>", "active": true,
                           "rights": {"read": true, "write": false, "execute": false},
                           "created_at": "…", "expires_at": null, "ended": null}]}]}

• Cada tarjeta a la que se dio acceso a la agenda, mediante un enlace que reclamó o una concesión, con los derechos de cada concesión, quién la emitió y si sigue activa o terminó (caducada o revocada). rights es lo que la agenda puede hacer ahora con la tarjeta.
• Una tarjeta privada conserva su concesión, pero no da acceso hasta que sea Unlisted o más amplia.
• Solo tú, desde tu propia sesión o token; el token de un oráculo o de una agenda recibe 403. Para retirar el acceso, revoca el enlace: Pipeline de API: compartir tarjetas con enlaces de acceso

9. Rúbricas con las que marca tu agenda. Cuando un oráculo que funciona con tu agenda etiqueta una tarjeta o una conversación, solo añade rúbricas con las que la propia agenda puede marcar: rúbricas abiertas para marcar, o una rúbrica tuya (Unlisted o más amplia) que compartiste con la agenda con ejecución sobre esa misma rúbrica. Tu propio derecho a marcar no se le presta a la agenda. Quitar una rúbrica no requiere ese derecho. Reglas: Pipeline de API: etiquetar tarjetas con rúbricas, sección B3.

En segundo plano

• Los cambios se aplican desde el siguiente turno de los oráculos y campañas que usan la agenda; no hay que reiniciar nada.

Reglas (400)

• title is required; kind must be fwag or swag; llm.reasoning must be one of off, low, medium, high.
• instructions: card <n> is a <type>, expected article or workspace (igual para las otras listas); … card <n> not found or not executable for you.
• only a firmware agenda can reference a swappable agenda; swag must be a swappable agenda; follow_ups solo en una agenda intercambiable.
• a personal session is required: el token propio de un oráculo no puede editar agendas.

Superficie de la API