Overview

The Agent Platform is layered. From bottom to top:

1. The substrate. NATS-typed actors, registry, catalog, identity, federation, capability tokens (target state), audit ledger. Every conversational artefact — a session, a tool call, a memory record, a plan step — is produced and observed via NATS subjects on the same authority root. Identity comes from transport metadata; payload is untrusted. The substrate is what @open-matrix/docs-matrix documents.
2. The cognitive vertical (system.agents). The @open-matrix/agents package mounts AgentsRoot at system.agents, with MemoryActor at system.agents.memory and EmbeddingService at system.agents.embeddings. AgentsRoot is exempt from the $prompt seal (isPromptRouter = true) so it can route prompts through to per-target child agents.
3. The capability layer (system.inference). Drivers, credentials, model routing, and quotas. The agents package consumes inference through @open-matrix/inference-catalog. The rename to @open-matrix/system-inference is target state (P1.5-system-inference-normalization).
4. Cognitive applications. Director, Chat (ConversationSurface), Smithers (SmithersSupervisor) — each targets system.agents as the backend mount.

The five canonical surfaces

The agent platform exposes exactly five surfaces. Use these names; they are load-bearing in the actor schemas, the trace formats, and the harness contracts.

Surface	What it is	Substrate primitive	Key file
Sessions	Durable record of one conversation between a caller and a (targetKey, profileKey) pair	A row in sessions SQLite table; child rows in session_messages, session_state	schema.sql:146-184, AgentsStore.ts:455-580
Tools	Functions the LLM may call mid-loop, resolved to bus invocations	MatrixToolProjection mapping a tool name to (target, op)	tools/ToolContextSpec.ts, runtime/AgentEnvironmentSpec.ts
Memory	Long-lived knowledge attached to a Space, project, or session	MemoryActor with FTS5 hybrid keyword + vector search	MemoryActor.ts, EmbeddingService.ts
Traces	Normalized activity-frame stream emitted on every cognitive step	ActivityFrame records, replayable	IAgentSessionStore.ts:85-103, activity/NormalizedActivityEvent.ts
Harnesses	Constraint orchestrators that run an agent against a workload and decide promotion	HarnessProtocol, HarnessRun	harness/HarnessProtocol.ts (and @open-matrix/smithers)

These are the canonical agent vocabulary. Don't substitute "thread" for Session, "function" for Tool, "context" for Memory, "log" for Trace, or "agent runner" for Harness.

How a turn flows

A user prompt to a target produces this loop:

caller ($prompt) -> system.agents
  AgentsRoot routes by (targetKey, profileKey) -> AgentActor
  AgentActor checks/creates Session in SQLite
  Oracle assembles system prompt (profile + skill + target snapshot)
  Oracle resolves Tools from agency profile + skills (ToolContextResolver)
  Oracle resolves Memory (short-term + project + session-scoped)
  Oracle calls inference (system.inference / @open-matrix/inference-catalog)
  Model emits 0..N tool_use events
    Each tool_use -> IToolDelegate -> RequestReply.execute(target, op, args) on the bus
    Each result fed back to the model as a tool_result turn
  Model emits final response
  Every step emits an ActivityFrame to activityTo[] sinks and to the session store

The ActivityFrame stream is the canonical trace format. The session SQLite tables are the durable record. The bus invocations are the tool-call audit trail. All three are queryable through system.agents ops.

Pages in this section

• What is the agent platform? — package, mounts, accepts.
• Agents vs Director — what each layer does and why they are different.
• Agents vs Chat — how Chat consumes system.agents through ConversationSurface.
• Sessions — what an agent session IS.
• Tools — how the oracle loop calls back into the bus.
• Memory — what is and is not stored.
• Traces — activity frames, the canonical trace format.

See also

• Sessions section, Tools section, Memory section, Harnesses section, UI surfaces
• Reference: agent actor ops
• Agent platform landing for the substrate-vs-vertical framing and the MCP integration directions.

Source: package manifest at projects/matrix-3/packages/agents/matrix.json; orchestration root at AgentsRoot.ts; oracle loop at oracle/executeActorOracle.ts.