Agent Platform

The Agent Platform is Vertical E in the product thesis. It is not the substrate — it is one of the verticals that sits on top of the substrate. It is also the day-1 distribution wedge: the v0.5 MCP bridge (forward direction) is what lets every existing AI agent tool (Cursor, Claude Code, Cline, Continue, Aider, Claude Desktop) consume Matrix actors as MCP tools without their users having to switch products.

The substrate (typed actors on a federated bus, registry, catalog, identity, federation, metering) is general-purpose. This vertical specializes the substrate for cognitive workloads: long-running LLM-driven sessions, structured tool calls back into the bus, persistent memory, and trace-replay-ready observability.

Motivation

The agent platform exists because AI agents are the lighthouse consumer of a typed actor substrate. Agents need tools that are typed, addressable, gated by capabilities, and scoped to the user's actual context — which Space they are working in, which Device is running, which runtime owns the call. Five canonical surfaces — Sessions, Tools, Memory, Traces, and Harnesses — give agents that structure without forcing every integrator to reinvent it. Two MCP integration paths matter in practice: one where Matrix consumes external MCP servers as tools, and one where external MCP-aware tools (Cursor, Claude Desktop, Continue, Cline) consume Matrix actors. Read this if you are integrating an AI agent with Matrix, building an agent loop of your own, or wiring tools into an existing agent product.

What this package documents

• The @open-matrix/agents package — AgentsRoot, AgentActor, MemoryActor, EmbeddingService, the oracle loop, runtime adapters, agency profiles, skills, tool contexts.
• The system.agents mount surface — accepts/emits, session lifecycle, tracing, the prompt-router exemption.
• The MCP integration on both sides — mcp-hub (Matrix consumes external MCP servers; landed) and mcp-bridge (external MCP clients consume Matrix actors as MCP tools; v0.5 target).
• The harness layer — HarnessProtocol, HarnessRun, agency-invoke tools.
• The UI integrations — Director, Chat (ConversationSurface), Smithers, Admin.

What it does NOT document

• The substrate itself. See @open-matrix/docs-matrix.
• The HiveCast Host wrapper. See @open-matrix/docs-hivecast.
• The Lisp REPL that AgentActor optionally embeds for $eval. See @open-matrix/docs-omega.
• The webapp shells (Matrix Web, Matrix Edge) that host Director, Chat, Smithers. See their owning packages.
• Capability tokens, policy presets, audit, Factotum credential discipline. See @open-matrix/docs-security.

The canonical agent vocabulary

Term	Meaning
Session	The durable record of one conversation between a caller and a (targetKey, profileKey) pair. Persisted in SQLite.
Tool	A function the LLM may call mid-loop that resolves to a Matrix actor invocation, an observability lookup, or an SDK-private filesystem/shell call.
Memory	Long-lived knowledge attached to a Space, project, or session. Hybrid keyword + vector search.
Trace	A stream of normalized activity frames emitted on every cognitive step. Replayable.
Harness	A constraint orchestrator that runs an agent loop against a workload (coding, evaluation, prompt-and-tool evolution) and decides whether the result earns promotion.

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

Five-minute orientation

You are	Read first
Building a Matrix package that wants to expose an agent surface	Overview / What is the agent platform? and Tools / Tool registry
Wiring an external MCP-aware tool (Cursor, Claude Desktop, Continue) into a HiveCast Host	MCP integration below — mcp-bridge is target state for v0.5
Operating Director / Chat / Smithers as the user surface for the agent platform	UI Surfaces
Auditing what an agent did	Overview / Traces and Reference / Trace schema

Where this fits in the whole

The agent platform is one vertical on the substrate. The substrate decides:

• What can the LLM call? Bus actors with declared accepts. The agent platform's MatrixToolProjection is sugar over RequestReply.execute(target, op, args).
• What is the LLM authorized to do? The substrate's policy engine and (target-state) capability tokens. The agent's ISecurityDelegate is the seam.
• Where do the credentials live? Factotum, on the Device. The agent never touches raw OAuth tokens.
• How are calls audited? The substrate's audit ledger, plus the agent platform's activity-frame trace stream.

When a vertical needs new substrate behavior, the right answer is to extend the substrate, not to re-implement the substrate piece inside the vertical. The agent platform follows that rule.

MCP integration (two directions)

The Model Context Protocol (MCP) integration has two distinct directions. Vocabulary matters:

mcp-hub — Matrix consumes external MCP servers (LANDED)

@open-matrix/mcp-hub is mounted at system.mcp and spawns external MCP server subprocesses (filesystem, github, postgres, slack, playwright, etc.). It exposes their tools through bus ops:

• mcp.list-servers, mcp.list-tools, mcp.call-tool, mcp.server-status, mcp.reconnect — all declared in mcp-hub/matrix.json.

This direction lets a Matrix agent call MCP tools that other people published. It is in the codebase today and deployable.

Status: target state — v0.5. AgentActor does not yet call mcp.list-tools on prompt setup, so external MCP tools are not yet automatically available to the in-Chat agent loop. system.mcp does not yet project tool entries as virtual mounts in system.registry. Tracked as P1.39-mcp-hub-substrate-wiring.md.

mcp-bridge — external MCP clients consume Matrix actors as MCP tools (TARGET STATE, v0.5)

mcp-bridge is a planned package that exposes any Matrix actor's accepts schema as an MCP tool. It ships as a stdio binary the user points Cursor / Claude Desktop / Continue / Cline at. Tool invocations route through the same authorization / policy gate Chat and Director use; no privilege escalation by going through MCP.

This is the v0.5 distribution wedge described in thesis Part 5 Vertical E and Part 6 Wedge 2. Distribution is solved: the user already has the agent tool. They install HiveCast to get more tools. They never had to adopt a new chat product.

Status: target state — v0.5. Not yet shipped. v0.5 acceptance criteria: schema translation per declared op, same authorization / policy gate as Chat and Director, one-command install snippets for Claude Desktop / Claude Code / Cursor / Continue / Cline, active-Space and active-runtime context respected, useful seed package set.

A separate thing: system.tools.mcpBridge (internal session-scoped projection)

McpBridgeActor (@open-matrix/agents/src/tools/McpBridgeActor.ts) is internal substrate plumbing — a session-scoped Matrix tool bridge used by SDK workers like Claude Code and Codex to consume Matrix tools in their own native tool format. It is not the v0.5 forward mcp-bridge package. Don't confuse the two.

Sections

• Overview — the conceptual model and how the parts fit (Sessions, Tools, Memory, Traces).
• Sessions — creating, resuming, and persisting agent sessions.
• Tools — the tool registry, permissions, invocation, traces, and testing.
• Memory — short-term context, artifact memory, project memory, retrieval, governance.
• Harnesses — coding/evaluation harnesses, prompt-and-tool evolution, trace replay, frontier promotion.
• UI Surfaces — Director, Smithers, Chat, Admin.
• Reference — actor ops, session/tool/trace/evaluation schemas.

Status

The inference plumbing, memory store, embedding service, oracle loop, and per-target session creation are wired and exercised in production code paths (backendMount: 'system.agents' in Director and Chat). Substantial pieces of the surrounding workstream — the cognitive readiness panel (P1.12), the cognitive product proof (P1.11), and the minimal capability-declaration set (P1.15) — are filed as TODO in WORKSTREAMS/loose-ends/items/. Where a page describes a target rather than present-state behavior, it is marked clearly.

Source: projects/matrix-3/packages/agents/matrix.json declares the system.agents package. The orchestration root is in AgentsRoot.ts. The agent loop runtime is in AgentActor.ts. The supersedes-and-targets list for the broader workstream is in WORKSTREAMS/loose-ends/items/P1.6-cognitive-stack-workstream.md. The MCP integration directions are spelled out in thesis Part 5 Vertical E.