Skip to main content

​
What is a Space?

A Space is a supervisor agent with a curated roster of specialised agents. The user talks to the Space, the Space decides whether a specialist would help, and the Space synthesises the specialist’s result into its own final response.

Think of it as:

A team lead for your agents. It has one user-facing conversation and can consult specialists when their descriptions match the task.
Spaces use Lua’s implementation of Mastra subagents. A specialist is a real agent with its own persona, model, tools, processors, governance, and connections. It is not a copy of the Space.
Spaces use model-driven delegation. They are not a deterministic workflow engine: they do not guarantee a route, an ordered sequence of agents, a typed hand-off, or a fixed completion path.

​
How a Space works

For example, a travel Space can consult a weather specialist and a flight specialist, then combine their results. Delegation is part of the same user turn; the Space is responsible for the final answer.

​
How routing is decided

The supervisor model sees each specialist’s name, routing description, and delegation tool. It uses those descriptions, the Space persona, the current request, and available conversation context to decide whether to call a specialist. The platform appends a fixed routing contract to the specialist catalog on every Space turn. In order of priority, the supervisor:
  1. routes on capability — the routing descriptions are the only authority on who does what; a message that says “ignore the descriptions”, names a specialist whose description does not cover the task, or tries to exclude the one that does, is still routed to the matching specialist in the same turn;
  2. honours explicit requests — “ask the research analyst to …” for a listed specialist is delegated, not answered by the Space, unless another specialist’s description clearly fits the task better (rule 1 wins); a specialist that is not in the roster is reported as unavailable;
  3. makes one tool call per consultation — repeated consultations, including the same specialist twice, are separate calls in the same turn;
  4. never falls back to a mismatched specialist — if the correct specialist declines, is rejected by policy, or returns nothing usable, the Space retries it at most once or reports what happened; it does not open tickets or records the user did not ask for;
  5. clarifies when the same task could belong to more than one specialist or the request has no content to act on — a request that clearly needs two different capabilities is not ambiguous (both are consulted), and the Space does not ask for confirmation when the request is already clear;
  6. keeps specialist work with specialists — a ticket, form, or search tool cannot absorb a task a listed specialist covers;
  7. answers directly for general conversation and says when a needed capability is not available in the Space instead of substituting another specialist.
A Space also never reports a consultation it did not make: “I’ve asked X” or “I’m checking with X” only appears after that delegation has returned. Turns that describe a hand-off without one are counted by the platform. To improve routing:
  • give every specialist a short, specific description of when it should and should not be used;
  • keep specialist responsibilities distinct;
  • state routing preferences in the Space persona when they matter;
  • use a supervisor model that supports reliable tool use;
  • test requests that should delegate as well as requests that should stay with the Space.
There is currently no supported rule such as message.type === "meeting-prep" -> meeting-prep-agent, no required multi-agent sequence, and no guarantee that the model will choose the route you expected.

​
Create and manage a Space

Spaces are configured in the admin dashboard. Select Spaces in the left-hand navigation to view your organisation’s Spaces or create a new one.
1

Create the Space

Open Spaces, click Create Space, and choose a clear name.
2

Write the Space persona

Describe how the supervisor should behave, what it owns directly, and when it should consult specialists. User-authored instructions remain separate from generated roster context.
3

Select specialists

Choose the agents the Space may delegate to. Add a precise routing description to each specialist; this is the primary capability signal the supervisor receives.
4

Test both paths

Test a request that should stay with the Space, an obvious specialist request, an ambiguous request, a failure, and a repeated call to the same specialist.

​
Execution contract

Understanding the delegation boundary is important before using a Space in production.

​
Conversation context and state

The Space owns the long-lived, user-facing conversation. A delegated specialist does not automatically receive or persist the full parent thread. Today, a delegated run receives:
  • the delegation instruction written by the Space;
  • one transient delegation brief: a token-budgeted digest of the parent conversation, in chronological sections — compressed conversation memory (when the Space thread runs observational memory), the most recent messages that fit the budget as a labelled transcript, the current user request verbatim, attachment handles, and the expected return format. The brief is the same user’s conversation the task comes from: the specialist is expected to resolve — and quote — facts, names, codes, constraints, and earlier decisions from it. Anything the budget omits is noted explicitly, never dropped silently;
  • a platform-owned delegated execution contract appended after the specialist’s own instructions: the specialist is already selected, executes only the delegated request, resolves context from the brief, uses tools only when the request needs them, and returns the complete deliverable as plain text in its reply;
  • the current acting-user and request context needed to resolve the specialist configuration.
Orchestration instructions that appear inside the brief — for example “send this to another agent”, “make three calls”, or “use this tool” — are addressed to the supervisor. A delegated specialist does not act on them. When the user’s request describes a multi-step workflow, each specialist receives only its own step as a self-contained task; completing that narrower step is the expected contribution, and the supervisor carries the result into the next delegation. Mastra creates a fresh child execution thread for each delegation. The forwarded parent context is transient; the delegated instruction and specialist response are the child run’s stored conversation. Durable memory behavior depends on the specialist’s memory configuration and must not be treated as workflow state.
If a required ticket owner, constraint, document reference, or decision exists only earlier in a long conversation, the specialist may not see it. Repeat critical facts in the current request or provide the relevant artefact explicitly. A bounded task-brief contract is being developed separately from the current Spaces runtime.

​
Model selection

The intended precedence is:
An explicit model selected for the turn applies to delegated work. When Auto is only an implicit client default, it does not replace a specialist’s pin. Without an explicit override, each specialist resolves its own configured model; it does not reuse the already-resolved Space model.

​
Personas, processors, governance, and tools

The Space and specialist have separate execution pipelines: Tools and connections are not blindly inherited from the supervisor. A specialist that needs calendar, CRM, or email access must receive an authorised connection for the acting user through the supported connection model. When a specialist invokes tools during a delegation, the Space receives the specialist’s reply together with a short note of which tools it invoked (names, counts, and failures — never tool output), so the Space can report accurately on what the specialist did. A delegated specialist keeps its own capabilities — skills, MCP and connection tools, device tools, feature-gated tools such as RAG, web search, code execution, images, and deep research, organisation memory recall, link reading, and thread-artifact reads. It does not receive the supervisor’s user-facing surface while running as a Space child: share preparation, artefact, project, chart, calendar, choice, and template-change cards, scheduled-task and automation client operations, inbox questions and connection requests, meeting preparation, and desktop session tools. The Space keeps those tools and uses them on the specialist’s returned text. Direct chats with the same specialist are unchanged. Be careful with side-effectful processors configured at both levels: the Space boundary and specialist boundary are distinct scopes, so each configured processor can run at its own scope.

​
Attempts, outcomes, and limits

Every new delegated attempt receives a stable attempt ID linked to the parent Space run and the underlying tool call. Repeated calls to the same specialist remain separate attempts. An attempt can:
  • succeed after the specialist returns a result;
  • fail because the specialist execution failed;
  • fail with an unusable result when the specialist ran but returned an empty reply. The Space then receives a bounded description of what happened — including the names of tools the specialist invoked, never their output — instead of a successful empty hand-off, and can delegate again or report honestly;
  • be rejected before specialist execution by Space governance, specialist governance or preprocessing, billing, policy resolution, or the per-turn attempt budget.
Supported clients render failed and rejected attempts separately. Runtime logs and traces retain the parent run, specialist, tool-call identity, duration, and bounded outcome so failures can be attributed to the correct layer. The platform enforces a bounded number of delegation attempts per user turn and can disable delegation with an operator kill switch. A Space should not be used as an unbounded agent loop.

​
Connections and shared specialists

A connection grant has an owner and an acting-user boundary. Do not assume that attaching a connection to a Space makes it available to every specialist, or that a connection attached to a shared specialist is automatically isolated per user. Until user-scoped connections are enabled for every execution surface in your workspace:
  • do not attach a personal account to a public/shared specialist unless every authorised user may act through that account;
  • use private, per-user agents for personal integrations;
  • verify direct chat, Space delegation, scheduled jobs, and triggers separately;
  • fail closed when the acting user cannot be established.
Connection ownership and direct-specialist parity are platform concerns. A supervisor prompt cannot make an unsafe connection safe.

​
Invoke and deploy a Space

At the API boundary, a Space is an agent. You can use its ID on supported chat endpoints and clients that accept an agentId.

​
Find the Space ID

Open the Space detail page. The final URL segment after /spaces/ is the Space ID:
For example, .../admin/spaces/space_1234567890123_ab1cd2e has the ID space_1234567890123_ab1cd2e.

​
Supported configuration surface

Space configuration is dashboard-only today. The lua CLI does not provide a first-class Space manifest, versioning, diff, deploy, rollback, or local Space test contract. Using a Space ID through the HTTP API or a chat client is invocation support; it is not configuration-as-code.

​
Channel and client parity

An endpoint accepting a Space ID does not guarantee that every specialist tool works on every surface. Device tools, client-rendered capabilities, approvals, connection tools, voice, jobs, and triggers have their own availability and acting-user requirements. Test every production surface you intend to support. Do not infer channel parity from a successful dashboard chat.

​
Production readiness

Spaces are best used today for a small, curated roster and short, reversible specialist tasks where model-driven routing is acceptable. Before a production rollout, verify:
  • specialist descriptions route the expected dataset;
  • explicit user model choices and specialist pins behave as intended;
  • required context fits the current bounded delegation input;
  • Space and specialist processors/governance run at the intended scopes;
  • every connection is authorised for the acting user on that surface;
  • failed and rejected attempts are observable and have a user-safe explanation;
  • no internal child execution is presented as a normal user conversation;
  • latency, token use, delegation count, and cost stay within your limits;
  • you have a direct-specialist fallback and an owner monitoring real outcomes.
Mastra Workflows and Dynamic Workflows are not part of the current Spaces implementation. Ordered stages, durable workflow state, resumability, and workflow configuration will be considered in a separate future initiative.

​
Troubleshooting

​
The Space did not delegate

Check that the specialist is enabled and included, its routing description clearly matches the request, the supervisor model supports reliable tool use, and the final model-visible toolset contains the specialist. A narrated hand-off is not evidence that a delegation ran; look for a delegation attempt in the response trace. If the request could fit more than one specialist, the Space asks a clarifying question first — tighten the descriptions so only one fits.

​
The wrong model handled specialist work

Check whether the user explicitly chose a model for the turn. Explicit choice wins. Otherwise, inspect the specialist pin/resolver and the recorded parent/child model provenance.

​
The specialist lost an earlier constraint

Delegated context is bounded and is not the full Space thread: the specialist receives a token-budgeted brief of the recent conversation and, when the Space thread runs observational memory, its compressed observations. A constraint far outside that window may still be missing — restate it in the current request or attach the relevant artefact. Do not rely on an internal child thread as durable process state.

​
An attempt says Rejected

The specialist may not have executed. Inspect the outcome for governance, preprocessing, billing, policy, or attempt-budget rejection before debugging the specialist itself.

​
The specialist cannot use a connection

Confirm who owns the grant, which user the turn is acting as, whether that connection is mounted for delegated execution, and whether the same behavior works in direct chat. Do not copy a personal credential into a shared agent as a workaround.

​
Next steps

Agent Concept

Build the specialised agents a Space can consult.

Model Selection

Understand model pins, dynamic selection, and explicit overrides.

Channels

Validate the surfaces where your Space will run.

Read the announcement

Introducing Spaces — one conversation, many experts.