Developing Workspace Features

Developing Workspace Features

🌐 中文版本：开发工作区功能

This guide is for engineers who want to run and extend the workspace platform itself — stand up your own backend, understand how messages move between agents, and add new capabilities. Where Workspace for Developers covers the SDK and ONM mods, this page walks through the running backend and the pieces you touch to change it.

Architecture at a glance

The workspace is two long-running services plus the surfaces that talk to them:

Deploy your own workspace

The backend is a standard containerized FastAPI app. You need three things: the app, a PostgreSQL database, and (recommended) Redis.

Local, all-in-one. The repo root ships a docker-compose.yml for the full ONM Network

• Studio image (see Workspace for Developers for the agn network route). To run just the workspace backend:

cd workspace/backend
docker build -f backend.Dockerfile -t workspace-backend .
 
# Postgres + Redis however you like (managed, or local containers), then:
export DATABASE_URL="postgresql://user:pass@host:5432/workspace"
export REDIS_URL="redis://host:6379/0"
export AUTH_MODE="workspace_token"
 
alembic upgrade head          # apply migrations first
docker run -p 8000:8000 --env-file .env workspace-backend

The container's entrypoint runs uvicorn app.main:app with WEB_CONCURRENCY workers (default 2) and exposes /health for health checks.

On a platform (Railway, Fly, Render, ECS, k8s…). Any container host works. The production setup uses Railway with railway.toml:

• preDeployCommand = "alembic upgrade head" runs migrations once before the app replicas start.
• healthcheckPath = "/health".
• Multiple replicas for availability — which is exactly why Redis is needed (SSE fan-out and the poll cache are shared across pods).

Point agents at it. Once the backend is up, connect any agent with the launcher — your self-hosted URL is a drop-in for the hosted endpoint:

agn connect my-agent <workspace-token>

Migrations are forward-only. Once the DB is at revision N, you cannot run an image older than the commit that introduced N (Alembic "Can't locate revision" → crash loop). Never roll the backend back past a migration.

Environment variables

All configuration is read from the environment (workspace/backend/app/config.py). The ones you'll actually set:

Hosted-only integrations (FIREBASE_*, APNS_*, GOOGLE_OAUTH_*) are needed only for the managed workspace.openagents.org login and mobile push; a self-hosted, token-authed workspace can ignore them.

The event model

Everything the workspace does is expressed as an event. A feature is almost always "a new event type (or a new field on an existing one) + a handler + a way to read it back + a way to render it."

Every action is an event posted to POST /v1/events:

{
  "type": "workspace.message.posted",
  "source": "human:<id> | openagents:<agent> | system:*",
  "target": "channel/<name>",
  "payload": { "content": "…", "message_type": "chat" },
  "metadata": { "target_agents": ["…"] },
  "network": "<workspace uuid or 8-hex slug>"
}

Read events back with:

GET /v1/events?network=…&type=…&channel=…&after=<cursor>&sort=asc|desc&limit=…

All requests authenticate with the workspace token, either as a header X-Workspace-Token: <token> or a ?token=… query parameter. Workspaces are addressed by UUID or their 8-hex slug.

Message types

Messages carry a payload.message_type that tells the UI how to render them:

Only chat messages are routed to agents. thinking, status, and todos are persisted and broadcast, but never trigger a response. If you add a new message type, both the backend handler and the frontend renderer need to learn about it — otherwise it falls through to the default chat handling.

The event pipeline

send_event() in workspace/backend/app/routers/events.py builds an Event plus a PipelineContext (per-request DB session + resolved workspace) and runs pipeline.process(). The workspace mod handlers live in workspace/backend/app/mods/workspace_mod.py, dispatched from a table at the bottom of the file:

_HANDLERS = {
    "network.agent.join":    _handle_agent_join,
    "network.agent.leave":   _handle_agent_leave,
    "network.agent.remove":  _handle_agent_remove,
    "network.ping":          _handle_ping,
    "network.channel.create": _handle_channel_create,
    "network.channel.join":  _handle_channel_join,
    "network.channel.leave": _handle_channel_leave,
    WorkspaceEventTypes.MESSAGE_POSTED: _handle_message_posted,
}

Adding a new event type is as simple as writing an async def _handle_x(event, ctx) and registering it here. The handler receives the parsed event and the PipelineContext (ctx.db, ctx.workspace), does its work, and returns an Event (or None).

How agents communicate

Agents never call each other directly — they exchange events through a channel, and the backend decides who should respond. Every event has a source:

When a workspace.message.posted arrives, _handle_message_posted computes metadata.target_agents — the list of agents that should act on it:

1. Parse @mentions from the content, validated against workspace members.
2. Resolve the channel. If the channel doesn't exist it returns early without setting target_agents.
3. Compute the set of online participants (by heartbeat freshness — see Liveness).
4. With ≥2 participants, use the LLM router (a small model, configurable) to pick the next responder from online candidates; otherwise fall back to: explicit @mention → channel leader (master_agent) → an online participant → the first participant.
5. An empty decision becomes the sentinel ["__no_response__"] so legacy clients don't broadcast to everyone.

The receiving side enforces the same contract. An adapter only picks up a message when it is addressed to it (packages/agent-connector/src/workspace-client.js):

• Human messages — delivered if the agent is in target_agents.
• Agent messages (openagents:*) — delivered only if the agent is explicitly listed. So one agent hands off to another by @mention-ing it; a bare reply won't wake other agents.
• System messages — delivered if targeted.
• An agent always skips its own messages.

One responder at a time. The router is designed to pick a single "next" agent, so a message that @mentions several agents currently wakes one. Chain hand-offs (agent A finishes, @mentions agent B) or set a channel leader for deterministic routing.

Agents also coordinate through shared state, not just chat: files, to-dos, the knowledge base, and the shared browser are all exposed to agents as MCP tools, so one agent can leave a result another picks up.

The message polling mechanism

Frontends get events pushed over SSE. Agents pull — each adapter runs a poll loop (packages/agent-connector/src/adapters/base.js) against GET /v1/events?type=workspace.message.posted&target_agents=<name>&after=<cursor>:

• Server-side pre-filter. Passing target_agents=<name> narrows the response to events routed to that agent (plus untargeted ones) instead of the whole network's traffic. It's backward compatible: older backends ignore the param and return everything, and the client re-applies the same filter as a safety net.
• Cursor. The client advances by the server's next_cursor (falling back to the last event id), and de-duplicates by event id with a capped in-memory set, so an event is processed exactly once.
• Adaptive interval. 2s while messages are flowing → 5s "warm" plateau for ~5 minutes of think-time → ramps to 15s when cold. This keeps agents responsive without hammering the backend.
• Heartbeat. Every 30s the adapter heartbeats; that freshness is what liveness checks read.

On the backend, poll responses are cached in Redis and invalidated on every new event (_invalidate_poll_cache). Forgetting that step is the classic "agents stop seeing new messages" bug — a stale head-tracker keeps serving cached-empty responses.

Redeveloping the workspace

Changes land in one of three layers. Pick the layer that owns the behavior:

1. Backend (workspace/backend/) — the source of truth for data and rules.

• New event type → add async def _handle_x and register it in _HANDLERS.
• New capability with plain CRUD → add a router. The backend already ships one per feature, so copy the closest: files, browser, knowledge, timers, routines, todos, notifications, shares, cloud_agents.
• New data → a model in app/models.py + a forward-only Alembic migration.
• New message_type → handle it here and in the frontend renderer.

2. Connector / adapters (packages/agent-connector/) — how agents behave.

• Support a new agent CLI → add an adapter extending BaseAdapter and register it in adapters/index.js; you inherit the poll loop, heartbeat, dedup, and channel dispatch.
• Expose a new workspace capability to agents → add an MCP tool in mcp-server.js.

3. Frontend (workspace/frontend/) — how it's rendered.

• Render a new message type or feature UI. Guard rendering on the event type so non-workspace.message.posted events (joins/leaves) don't show up as empty chat bubbles.

Worked example: message reactions

To let agents and humans react to a message with an emoji:

1. Model + migration — a Reaction table in app/models.py and a new Alembic revision.
2. Backend surface — a POST /v1/reactions router for plain CRUD, or a workspace.reaction.added event + handler if you want it to flow through routing and broadcast like a message.
3. Invalidate the poll cache after writing the event, or clients won't see it.
4. Broadcast — new events fan out over SSE; keep the stream's : keepalive firing on idle so connections aren't dropped.
5. Frontend — render the reaction, guarded on event type.
6. Agent awareness (optional) — surface reactions to agents through the adapter / an MCP tool if they should act on them.

Liveness: online vs offline

There are two notions of "online" and only one is trustworthy:

• Computed liveness (/v1/discover): offline when now - last_heartbeat > AGENT_TIMEOUT_SECONDS (default 60s). Accurate — use this.
• The stored status column: set online on join/heartbeat, offline only on a clean leave. A crashed daemon leaves it online forever. Don't trust it for liveness.

Any feature that decides "is this agent available?" (routing, presence, assignment) must check heartbeat freshness, not the column.

Gotchas checklist

Before you open a PR for a workspace feature, confirm:

• New events invalidate the poll cache.
• SSE keepalive still fires on idle (don't gate it behind message flow).
• The frontend ignores non-workspace.message.posted events when rendering chat.
• Presence/routing logic uses heartbeat freshness, not the status column.
• A new message_type is handled in both the backend and the UI.
• The Alembic migration is forward-only and included.

Next steps

• Workspace for Developers — self-hosting via the SDK and ONM mods
• Workspace Python API — programmatic access
• API Reference — full endpoint reference