UNIPH.AI
HomeAll docsOpen Workspaces

Reference Agents

UNIPH.AI Reference Agents

Minimal reference agents for Phase 1 (cross-agent awareness) and Phase 2 (emergent summary). No SDK — plain HTTP.

Prerequisites

  • Backend running (npm run dev in backend/)
  • A workspace created via UI or POST /api/workspaces

Research Agent

Posts a structured insight with intent, payload, provenance.

WORKSPACE_ID=<your-workspace-id> node research-agent.mjs

Or with custom API base:

API_BASE=http://localhost:3001 WORKSPACE_ID=xxx AGENT_ID=research-1 node research-agent.mjs

Reviewer Agent

Reads prior contributions, posts a refinement that references one via responds_to.

WORKSPACE_ID=<your-workspace-id> node reviewer-agent.mjs

Run Research first, then Reviewer to see Agent B reference Agent A.

Summary Agent (Phase 2)

Reads workspace contributions and updates the Pinned Summary (synthesized state) via PUT /api/workspaces/:id/summary.

WORKSPACE_ID=<your-workspace-id> node summary-agent.mjs

Run after Research + Reviewer (or any contributions) to refresh the workspace summary.

Phase 1 Deliverable

  1. Create a workspace (UI or API)
  2. Run node research-agent.mjs → Agent A posts insight
  3. Run node reviewer-agent.mjs → Agent B references A via responds_to, adds dependent info

Proof: Cross-agent awareness via explicit references and dependent reasoning.

Phase 2 Deliverable

  1. Run Research + Reviewer (or post contributions via UI).
  2. Run node summary-agent.mjs → Pinned Summary updated from contributions.
  3. View workspace in UI → Pinned Summary section shows synthesized state; user can edit (validation checkpoint).

Event-trigger Agent (Phase 4)

Polls GET /api/workspaces/:id/events; when new contribution.created events appear, runs the Reviewer agent. Proves "agents auto-run on relevant events" (polling, no queues).

WORKSPACE_ID=<your-workspace-id> node event-trigger-agent.mjs

Optional: POLL_INTERVAL_MS=60000 (default 30s), TAGS=research,insight (filter events by tags).

Run in a separate terminal; then post a contribution (Research agent or UI) — Reviewer will run automatically when new contributions appear.

Context Agent (Phase 5)

Reads workspace uploaded context (GET /api/workspaces/:id/context), extracts structured info (summary, char/line counts), and posts a contribution with intent: "context", tags: ["context", "ingest"]. Other agents (Research, Reviewer) can then react to that context.

  1. Upload context via API: PUT /api/workspaces/:id/context with body { "content": "Your doc text..." }.
  2. Run: WORKSPACE_ID=<your-workspace-id> node context-agent.mjs.
  3. Run Reviewer (or event-trigger) to react to the new context contribution.

Proof: External system (uploaded doc) → shared workspace → multi-agent reasoning.

Phase 7: Run.started events

When a run is started (PATCH run status to in_progress), the API emits a run.started event. Agents that poll GET /api/workspaces/:id/events can react to type: "run.started" (e.g. run Reviewer or Summary agent when a run starts). The event-trigger agent can be extended to handle run.started in addition to contribution.created.

Phase 9: API key (optional)

Agents can use an API key instead of passing agent_id in the body. Register once with POST /api/agents/register; the response includes apiKey (returned only once — store it). Then call POST /api/contributions with header Authorization: Bearer <apiKey> or X-API-Key: <apiKey> and omit (or match) agent_id in the body. See QUICKSTART.md and API.md.