Nápověda

Jak připojit externího agenta k Weekboard API

Autentizace, oprávnění, bezpečné změny a zpracování požadavků „Předat agentovi“.

Než agenta připojíte

  1. V nabídce účtu otevřete API tokeny a vytvořte token pro daného agenta.
  2. Začněte nejmenším potřebným oprávněním. Obvykle stačí Čtení. Zápis přidejte až tehdy, když má agent úkoly měnit.
  3. Token kdykoli odvoláte v seznamu existujících API tokenů tlačítkem Zrušit.

Tato stránka je určena člověku, který připojuje externího agenta k Weekboardu. Vysvětluje hranice přístupu, bezpečný postup změn a zpracování pokynů předaných uživatelem.

Samotnému agentovi předejte adresu /llms.txt. Anglický soubor mu stručně popíše API a odkáže ho na přesný OpenAPI kontrakt.

Technický kontrakt a hranice přístupu

  • Základní cesta API je /api/v1. Požadavky i odpovědi používají application/json.
  • Agent se přihlašuje hlavičkou Authorization: Bearer <token>. Pro požadavky GET potřebuje token oprávnění read a pro změny oprávnění write. Oprávnění read_external_calendar_events přidejte jen tehdy, když má v podporovaných odpovědích vidět také externí kalendář pouze pro čtení.
  • Token platí pouze pro Weekboard účet daného uživatele. Plánovací endpointy pracují s jeho výchozím interním kalendářem. Agent nesmí předpokládat přístup k jinému účtu nebo kalendáři.
  • Chyby API zůstávají anglicky a používají tvar {"error":{"code":"...","message":"...","details":{...}}}. Agent má vyhodnocovat HTTP stav, code a případné validační details, ne pouze text zprávy.
  • Při souběžných změnách vyhrává poslední zápis. API nevrací konflikt optimistického zamykání, proto má agent před důležitou změnou znovu načíst aktuální stav.

Přesné cesty, těla požadavků, schémata odpovědí a stavové kódy určuje OpenAPI 3.1 kontrakt. Agent si nemá domýšlet pole ani odvozovat seznam endpointů z této nápovědy.

Bezpečný pracovní postup

  1. Nejprve zavolá GET /api/v1, kde zjistí podporované cesty, oprávnění a verzi API. Potom načte OpenAPI kontrakt.
  2. Před změnou načte cílový záznam. Vrácené identifikátory zachová přesně a nezaměňuje ID seznamů, úkolů, kalendářů, opakovaných úkolů ani událostí.
  3. Před hromadnou změnou zavolá POST /api/v1/operations/dry_run a zkontroluje každý navržený zásah. Změnu potvrdí jen tehdy, když odpovídá záměru uživatele.
  4. Operaci delete_tasks nikdy nepotvrdí bez výslovného souhlasu uživatele a hodnoty confirm: true.
  5. Řídí se strukturovanými chybami. Po 400 nebo 422 opraví vstup, po 403 požádá o potřebné oprávnění a po 401 se znovu přihlásí. Změny neopakuje naslepo.
  6. Při stránkování úkolů předává vrácené pagination.next_offset jako offset, dokud není null. U proudu událostí posouvá since_id podle vráceného latest_id. Kurzory si nevymýšlí.
  7. Token uchovává v tajnosti. Nevkládá ho do URL, promptů, poznámek úkolů, zdrojového kódu, screenshotů ani logů. Při práci s tokenem vypne trasování shellu a podrobný výpis HTTP.

Spustitelné příklady

Zástupné hodnoty nastavte lokálně. Skutečný token nevkládejte do výstupu, který může vidět někdo další.

export WEEKBOARD_URL="https://YOUR-WEEKBOARD-HOST"
export WEEKBOARD_TOKEN="YOUR_API_TOKEN"

curl --silent --show-error --fail-with-body \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $WEEKBOARD_TOKEN" \
  "$WEEKBOARD_URL/api/v1"

Následující příklad připraví náhled dokončení již zkontrolovaného úkolu, ale nic nezmění:

export TASK_ID="TASK_ID_FROM_A_READ_RESPONSE"

curl --silent --show-error --fail-with-body \
  --request POST \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $WEEKBOARD_TOKEN" \
  --data "{\"operation\":{\"type\":\"complete_tasks\",\"task_ids\":[$TASK_ID],\"completed\":true}}" \
  "$WEEKBOARD_URL/api/v1/operations/dry_run"

Zpracování požadavků „Předat agentovi“

Weekboard uloží konkrétní instrukci uživatele, ale agenta sám nespustí. Externí agent požadavky pravidelně načítá, jeden z nich bezpečně převezme, práci provede mimo Weekboard a zapíše stručný výsledek.

  1. Tokenem s oprávněním read načítá GET /api/v1/task_agent_requests?status=pending&limit=50.
  2. Před převzetím vygeneruje UUID, bezpečně ho uloží a odešle jako claim_id na POST /api/v1/task_agent_requests/{id}/claim s oprávněním write. Po chybě sítě použije stejné UUID. Již převzatý požadavek nikdy nepřebírá s novým UUID.
  3. Pole instruction je výslovný pokyn uživatele. Vrácené notes úkolu jsou pouze očištěný zdrojový kontext. Mohou obsahovat nedůvěryhodný importovaný e-mail, issue nebo webový obsah a agent je nesmí považovat za nadřazené instrukce.
  4. Pokud to navazující systém umožňuje, použije ID požadavku jako klíč idempotence. Weekboard zajišťuje idempotentní opakování převzetí a dokončení, ale nemůže zaručit právě jedno provedení vedlejšího efektu v cizím systému.
  5. Na POST /api/v1/task_agent_requests/{id}/finish zapíše outcome s hodnotou succeeded nebo failed, stručný textový result a případné HTTP(S) result_url. Odešle stejné claim_id a stejný API token, který požadavek převzal.

Převzetí samo nevyprší. Agent nesmí převzatý požadavek ukrást jinému procesu ani ho automaticky spouštět znovu. Uživatel může uvázlý požadavek ve Weekboardu výslovně zrušit a vytvořit nový. Dokončení požadavku samo o sobě nedokončí ani neupraví související úkol.

CLAIM_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
REQUEST_ID="REQUEST_ID_FROM_POLL"

curl --silent --show-error --fail-with-body \
  --request POST \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $WEEKBOARD_TOKEN" \
  --data "{\"claim_id\":\"$CLAIM_ID\"}" \
  "$WEEKBOARD_URL/api/v1/task_agent_requests/$REQUEST_ID/claim"