Core Concepts

One action, three surfaces

The platform's entire capability surface is a single source of truth: the action registry. Every action is defined once with a name, a description, a Zod input schema, an HTTP method, and whether it mutates state. From that one definition, the action is exposed three ways:

Surface	How it appears	Example
🤖 AI tool	The agent calls it by name; dots become underscores.	`missions_create`
🔌 HTTP endpoint	A request to the universal dispatcher.	`POST /api/invoke/missions.create`
🖥️ UI page	A page/component invokes the same action.	the `/missions` page

Because all three run the same handler with the same validation, they can never drift apart. A capability the agent has is a capability the API has is a capability the UI has.

action registry

(name + Zod schema + handler + mutating flag)

one definition

🤖 AI tool

missions_create

🔌 /api/invoke

missions.create

🖥️ UI page

/missions

same handler · same validation

Anatomy of an action

Each action declares:

name — the canonical id, e.g. missions.create. The AI tool name is the same with dots replaced by underscores (missions_create).
description + optional llmHints — human- and agent-readable; the hints tell the agent when to reach for it.
input — a Zod schema. The HTTP dispatcher validates request bodies with it; the AI SDK validates tool arguments with the same schema.
method — GET for reads, POST/PATCH/DELETE for writes.
mutating — whether it changes state. Drives approval queueing for supervised agents and refresh hints for the UI.
requiresRole (optional) — workspace/org roles allowed to call it.

The Reference renders all of this for every action, straight from the registry.

Autonomy and approvals

Agents have an autonomy level. A supervised agent doesn't execute mutating actions directly — it files a Decision for a human to approve or reject. The same mutating flag that the API uses for safety drives this queue, so the human-in-the-loop is consistent no matter which surface initiated the work.

Workspaces

Almost everything is workspace-scoped. The action handlers narrow every read and write to the caller's active workspace, so members can freely operate within their workspace without being able to reach across to others. See Authentication & Access.

Extending the surface

Extensions add to this same model — contributing their own actions, HTTP endpoints, agent tools (via MCP), UI panels, and data — under enforced per-extension permissions. See Extensions.