# Mastra Harness The Mastra Harness is [[Mastra AI]]'s session-controller layer for building interactive, long-running agent applications. It sits around the agent loop, "the Harness is a shared host; the Session is the conversation running inside it", and handles the runtime concerns (threads, state, modes, approvals, events) that you'd otherwise wire up by hand. It was extracted from MastraCode, Mastra's internal TUI coding agent, and shipped in `@mastra/[email protected]` (June 18, 2026). It is Mastra's concrete take on the [[AI Agent Harness]] pattern. ## Core Concepts - **Session**: a single conversation's runtime state: active mode, selected model, thread binding, permission grants, token usage. One Harness hosts many concurrent sessions (multi-user). - **Modes**: distinct agent "personalities" (e.g. Plan vs Execute) with their own instructions, tools, and models, switchable mid-conversation without losing context - **Threads & State**: persistent threads (create, switch, rename, delete, clone) that resume exactly where the user left off across restarts - **Subagents**: isolated subagents with independent context, or forked subagents that inherit parent state via warm prompt caching - **Tool approvals**: session-level, category-based permissions; manual approval via `tool_approval_required` events, plus YOLO (auto-approve) and deny policies - **`ask_user` tool**: lets the agent pause and request input mid-execution ## Event System & State The Harness emits ~35 signals under a `display_state_changed` event type (agent lifecycle, tool deltas, suspensions) that collapse into a unified `HarnessDisplayState` object consumable by web, mobile, or TUI UIs. Tracked state includes running tools, token usage, pending approvals, subagent activity, and memory progress. Storage is composable via `MastraCompositeStore` (LibSQL, PostgreSQL, ClickHouse backends per data domain). ## Relationship to Agents The Harness builds atop Mastra's Agent class, adding opinionated defaults for collaborative, multi-mode, persistent sessions. Use the Agent class for full control of the loop; use the Harness when you need long-running, colleague-like agents with UI integration. It integrates observational [[Mastra Memory|memory]] for long autonomous runs. ## When to use it Long-running/autonomous tasks, colleague-like conversations, work extending beyond a few minutes, or code-writing loops. ## References - https://mastra.ai/blog/announcing-agent-harness - https://mastra.ai/docs/harness/overview ## Related - [[Mastra AI]] - [[AI Agent Harness]] - [[Mastra Agents]] - [[Mastra Memory]] - [[Durable Execution]] - [[AI Agents]] - [[Agentic Engineering]]