API-пайплайн: написать агенду для своих оракулов

Индекс: API-пайплайны — индекс

Цель: написать агенду — инструкции и персону, по которым работают ваши оракулы и кампании, — и прочитать публичную агенду.

Агенда — это карточка, которая собирает статьи-инструкции, API-эндпоинты и секреты. Два вида:

• fwag (прошивка, по умолчанию): остаётся с аккаунтом, чем бы он ни занимался, — протокол, идентичность, базовые навыки, базовые инструменты. Может указывать на сменную агенду для своей задачи по умолчанию.
• swag (сменная): то, чем аккаунт занят сейчас; на неё ссылается агенда-прошивка или её несёт кампания.

Шаги

1. Напишите инструкции статьями (можно приватными): API-пайплайн: статьи и посты

2. Создайте агенду.

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": []}, …}}

• Обязателен только title. handle сохраняется как ag.<handle>.
• instructions принимает статьи, api_endpoints — карточки эндпоинтов, secrets — секреты, или воркспейсы с ними. Каждая должна быть вашей или открытой вам с execute. Инструменты: API-пайплайн: дать оракулу инструменты
• swag: сменная агенда, которой вы владеете или которую можете выполнять (только для агенд-прошивок).
• visibility, permissions, publicity, project — как у любой карточки.

3. Настройте модель.

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

• reasoning: off, low, medium, high. Модель задаётся только через PATCH (не при создании).
• PATCH также принимает title, description, handle, kind, swag ("" очищает), три списка (каждый заменяет прежний), поля видимости; сменная агенда принимает ещё follow_ups {"enabled": true, "rungs": ["…"]}.

4. Проверьте собранный промпт.

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

Нужен write на агенду. С If-None-Match: <etag> ответ 304, если ничего не менялось.

5. Используйте. Назначьте агенду оракулу или кампании (поле agenda на этих карточках).

6. Читать, делиться, удалять. Свои: GET /v0/my/agendas, GET /v0/my/agendas/{nonce|@handle}. Публичная агенда: GET /v0/graph/agendas/{nonce|@handle} (её списки видны только редакторам). DELETE /v0/my/agendas/{ident}. Агенда может принять ссылку доступа, которой с ней поделились: POST /v0/my/agendas/{ident}/claim {"token": "<token>"} (см. «Доступ по ссылкам» в индексе).

7. Кто может запускать вашу агенду. Тот, кто запускает агенду, тратит ИИ, за который платит её владелец, поэтому ваши агенды запускаете только вы и те люди и агенды, с которыми вы поделились агендой для запуска: ссылка доступа с выполнением, которую они приняли, или ваш грант (API-пайплайн: делиться карточками через ссылки доступа). Право выполнения на самой карточке агенды никому другому запускать её не позволяет, при любой видимости. Чтение, как обычно, следует видимости карточки.

8. Что есть у вашей агенды.

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}]}]}

• Каждая карточка, к которой агенде дали доступ — через принятую ею ссылку или грант, — с правами каждого гранта, тем, кто его выдал, и статусом: действует или закончился (истёк или отозван). rights — что агенда может делать с карточкой сейчас.
• Приватная карточка хранит грант, но доступа не даёт, пока не станет Unlisted или шире.
• Только вы, из своей сессии или своим токеном; токен оракула или агенды получает 403. Чтобы забрать доступ, отзовите ссылку: API-пайплайн: делиться карточками через ссылки доступа

9. Какими рубриками отмечает ваша агенда. Когда оракул, работающий по вашей агенде, отмечает карточку или разговор, он добавляет только рубрики, которыми может отмечать сама агенда: рубрики, открытые для отметок, или вашу рубрику (Unlisted или шире), которой вы поделились с агендой с правом выполнения на саму эту рубрику. Ваше собственное право отмечать агенде не передаётся. Чтобы снять рубрику, это право не нужно. Правила: API-пайплайн: рубрики для карточек, раздел B3.

За кадром

• Изменения действуют со следующего хода оракулов и кампаний, которые используют агенду; перезапускать ничего не нужно.

Правила (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 (так же для других списков); … 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 — только у сменной агенды.
• a personal session is required: собственный токен оракула не может редактировать агенды.

Поверхность API