synops/docs/infra/agent_api.md

Agent API — Claude sitt strukturerte grensesnitt mot maskinrommet

Bakgrunn

I dag snakker Claude med systemet via claude -p med hele konteksten bakt inn som en tekststreng. Det fungerer for enkle chat-svar, men skalerer ikke:

• Prompten blir enorm når spec + historikk + graf-kontekst skal med
• Claude kan ikke hente mer info underveis — alt må være i prompten
• Claude kan ikke gjøre handlinger (oppdatere spec, søke, sjekke status)
• Ingen struktur — alt er fritekst, ingen validering

Konsept

Et sett med maskinrommet-endepunkter designet for agenten — ikke for brukere. Autentisert med agent-token (samme som i agent_identities). Gir Claude strukturert tilgang til grafen, spesifikasjoner og handlinger.

Endepunkter

Lesing (kontekst)

GET /agent/context

Hent alt Claude trenger for å svare i en samtale.

GET /agent/context?communication_id=<uuid>

Returnerer:

{
  "communication": { "id": "...", "title": "..." },
  "participants": [{ "id": "...", "title": "...", "node_kind": "..." }],
  "messages": [{ "id": "...", "content": "...", "sender": "...", "timestamp": "..." }],
  "spec": { "id": "...", "content": "...", "feature_key": "..." } | null,
  "related_nodes": [{ "id": "...", "title": "...", "edge_type": "..." }]
}

Fordel over dagens løsning: én request, strukturert, med spec og relaterte noder inkludert. Maskinrommet bestemmer hva som er relevant.

GET /agent/node

Hent en spesifikk node med edges.

GET /agent/node?id=<uuid>&depth=1

Returnerer noden med edges i angitt dybde. Nyttig når Claude trenger mer kontekst enn det som var i context-svaret.

GET /agent/search

Søk i grafen.

GET /agent/search?q=<tekst>&node_kind=content&limit=10

PG fulltekstsøk over nodes.content + nodes.title. Filtrering på node_kind, visibility, samling. Returnerer noder med relevans-score.

GET /agent/feature_status

Sjekk implementeringsstatus for en feature.

GET /agent/feature_status?key=lydstudio

Returnerer:

{
  "feature_key": "lydstudio",
  "spec_node_id": "...",
  "tasks": [
    { "id": "17.1", "description": "...", "status": "done" },
    { "id": "17.2", "description": "...", "status": "todo" }
  ],
  "recent_commits": ["..."],
  "feedback_summary": "3 brukere har gitt feedback, 1 ubesvart"
}

Henter fra tasks.md (parser markdown), git log, og feedback-chat.

GET /agent/tasks

Hent gjeldende oppgavestatus.

GET /agent/tasks?phase=14&status=todo

Parser tasks.md og returnerer strukturert. Filtrer på fase og status.

Skriving (handlinger)

POST /agent/update_spec

Oppdater en spec-node.

{
  "node_id": "...",
  "content": "oppdatert markdown...",
  "reason": "Integrert feedback fra bruker X om Y"
}

Oppdaterer noden i PG. Logger endringen i ai_usage_log med job_type: 'spec_update'. Oppretter revision-node med forrige versjon for historikk.

POST /agent/respond

Send et svar i en samtale (erstatter dagens direkte STDB-skriving).

{
  "communication_id": "...",
  "content": "svarteksten",
  "metadata": { "confidence": 0.9, "sources": ["node_id_1"] }
}

Maskinrommet håndterer node-opprettelse og edges. Metadata kan inkludere kildereferanser som frontend kan vise.

POST /agent/suggest_edges

Foreslå nye edges basert på innholdsanalyse.

{
  "source_id": "...",
  "suggestions": [
    { "target_id": "...", "edge_type": "mentions", "confidence": 0.85 },
    { "target_id": "...", "edge_type": "related_to", "confidence": 0.7 }
  ]
}

Lagres som forslag (metadata.suggested: true) — bruker eller admin godkjenner. Over en viss confidence-terskel kan de auto-godkjennes.

Autentisering

Agent-endepunktene bruker agent-token fra agent_identities-tabellen. Header:

Authorization: Bearer <agent_token>

Maskinrommet validerer at tokenet tilhører en aktiv agent (is_active = true). Agentens node_id brukes som created_by for alle handlinger.

Integrasjon med claude -p

Dagens agent_respond-jobb kaller claude -p med en tekstprompt. Med Agent API endres flyten:

Før (nåværende)

melding → agent_respond-jobb → bygg prompt (SQL) → claude -p → parse svar → skriv PG

Etter (med Agent API)

melding → agent_respond-jobb → GET /agent/context → claude -p med tool-definisjon → claude bruker tools → POST /agent/respond

Claude får tool-definisjoner i prompten og kan kalle Agent API via tool-use i JSON-output. Maskinrommet parser tool-calls og utfører dem.

Alternativt: Claude Code har allerede tool-bruk via Bash. Agent API kan eksponeres som curl-kommandoer som Claude kaller direkte.

Prioritering

Fase 1 (umiddelbar verdi)

• GET /agent/context — erstatter SQL-i-prompten, gir spec-kontekst
• POST /agent/respond — strukturert svar med metadata

Fase 2 (bedre feedback-løkke)

• GET /agent/feature_status — Claude kan gi informerte statussvar
• POST /agent/update_spec — Claude kan integrere feedback direkte
• GET /agent/search — Claude kan finne relevant kontekst selv

Fase 3 (proaktiv agent)

• POST /agent/suggest_edges — automatisk grafbygging
• GET /agent/tasks — Claude kan rapportere på fremdrift
• Periodiske jobber: digest, spec-synk, feedback-oppsummering

Bygger på

• Agent-infrastruktur (docs/infra/claude_agent.md)
• Feature feedback (docs/features/feature_feedback.md)
• Jobbkø (docs/infra/jobbkø.md)
• AI Gateway (docs/infra/ai_gateway.md)