API overview

Prefer the guide for when-to-use context. This page is a quick reference.

Subpaths

Subpath	Module
mastra-effect	Barrel — common imports
mastra-effect/Agent	Agent.of
mastra-effect/Tool	MastraTool.make
mastra-effect/Toolkit	Toolkit.make, toMastra
mastra-effect/ToolUI	HITL schemas, stream cards
mastra-effect/Memory	MastraMemory
mastra-effect/Stream	Mastra stream helpers
mastra-effect/Suspend	Suspend.execute
mastra-effect/Observability	Span stitching
mastra-effect/Error	MastraError, reasons
mastra-effect/assistant-ui	ClientToolkit (React)

Tools (mastra-effect/Tool, mastra-effect/Toolkit)

Export	When to use
MastraTool.make	Define a tool with Effect Schema
tool.annotate(ToolUI.Schema, s)	Client registration — marks client-fulfilled tool for ClientToolkit
MastraTool.getToolUISchema	Read Tool UI schema annotation from a tool
Toolkit.make / Toolkit.merge	Build typed toolkits
toolkit.of(handlers)	Typed identity for handler maps — helps inference at call sites
toolkit.schemas	Tool UI schemas from annotated tools (client registration index)
toolkit.toMastraTools	Mastra ToolsInput for agent loop
ToolHandlers	Server handler registry context
HandlerRequirementsFrom<H>	Union of handler R — provide at execute/stream, not on layer

Agent (mastra-effect/Agent)

Export	When to use
Agent.of(id, { …, toolkit, handlers })	Preferred wiring — typed ops; handler R on method Effects
Context.Service + Layer.effect	Preferred agent — service class + explicit Live layer
yield* Service	Call agent methods; method Effects carry handler R

Agent.of config accepts Mastra inputProcessors, outputProcessors, errorProcessors, requestContext, and dynamic instruction fields. Per-call overrides via agent.stream(msgs, { inputProcessors }) too. See Agents guide.

Memory (mastra-effect/Memory)

Export	When to use
MastraMemory.layer(config?)	Construct @mastra/memory
MastraMemory.layer(instance)	Wrap an existing Mastra memory instance
MastraMemory.recall, getThreadById, listThreads, saveThread, saveMessages, createThread, deleteThread, settled	Effect wrappers

Stream (mastra-effect/Stream)

Export	When to use
fromMastraOutput	MastraModelOutput.fullStream → Stream
fromReadableStream / fromAsyncIterable	Adapters

ToolUI (mastra-effect/ToolUI)

Export	When to use
ToolUI.make	Inert schema (stateSchema, optional answerSchema, optional equals)
ToolUI.equalsBy / ToolUI.answersEqual	Optional sugar for answer equality; default is Object.is
ToolUI.getSchema	Read Tool UI schema annotation from a tool (alias)
ToolUI.present(schema, args, { transient? })	Stream card create (no answerSchema)
ToolUI.update(schema, id, args, { transient? })	Stream card update
ToolUI.toSuspendPayload / encodeResumeAnswer	Wire encode for client rendering / resume
ToolUI.fromSuspendArgs / fromToolCallSuspend	Parse suspend payloads (advanced)
ToolUI.isStreamChunk / fromStreamChunk	Parse data-mastra-effect-block chunks
ToolUI.Runtime	Service required by Tool UI ops (auto-provided)
ToolUI.Error	Encode/decode or missing Mastra context failures

Suspend (mastra-effect/Suspend)

Export	When to use
Suspend.execute(schema, args)	HITL suspend — requires answerSchema on the schema
Suspend.isToolCallSuspendPart	Parse tool-call-suspend chunks (advanced)

Observability (mastra-effect/Observability)

See the observability guide.

Export	When to use
MastraObservability.layer()	Opt in to span stitching at tool FFI
ObservabilityBridge	Shape of the MastraObservability service value
enterMastraSpanContext / runEffectInMastraSpan	Promise FFI span stitching
currentSpanFromToolContext	Read active span from Mastra tool context

Errors (mastra-effect/Error)

See the errors guide for Match / catchTag examples.

Export	When to use
fromUnknown	Bridge native MastraError / unknown failures at boundaries
MastraError	Top-level Effect error; narrow reason with Match.tag
reasonsById / mastraErrorsById	Lookup generated reason class by Mastra id
ErrorDomain, ErrorCategory	Re-exported from @mastra/core/error
ClientToolRequiredError	Server hit an annotated tool without client fulfillment
UnknownMastraError	Fallback reason when no Mastra id matches

Assistant UI (mastra-effect/assistant-ui)

Export	When to use
ClientToolkit.of(toolkit, handlers)	Handlers for annotated tools + stream views
clientToolkit.toAssistantUiTools()	Assistant UI human tools from annotated tool views
clientToolkit.renderChunk(chunk, { resume })	Demux suspend / stream-card / ignore
clientToolkit.renderToolUI	Render suspend payloads directly
clientToolkit.renderStreamToolUI	Render data-mastra-effect-block stream chunks
clientToolkit.encodeResume	Schema-encode resume answers
clientToolIds / serverToolIds	List tool ids by kind

Pass clientToolkit.toAssistantUiTools() to Assistant UI's Tools({ toolkit }) helper.