Mastra client SDK

The Mastra Client SDK provides a type-safe interface for interacting with your Mastra Server from your client environment.

Usage example

lib/mastra/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111/',
})

RequestContext

When you use RequestContext with the client SDK, import it from @mastra/client-js.

import { MastraClient, RequestContext } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111/',
})

const requestContext = new RequestContext()
requestContext.set('userId', 'user-123')

const agent = client.getAgent('support-agent')

const response = await agent.generate('Summarize this ticket', {
  requestContext,
})

You can also pass requestContext as a Record<string, any>.

Parameters

baseUrl:

string

The base URL for the Mastra API. All requests will be sent relative to this URL.

retries?:

number

= 3

The number of times a request will be retried on failure before throwing an error.

backoffMs?:

number

= 300

The initial delay in milliseconds before retrying a failed request. This value is doubled with each retry (exponential backoff).

maxBackoffMs?:

number

= 5000

The maximum backoff time in milliseconds. Prevents retries from waiting too long between attempts.

headers?:

Record<string, string>

An object containing custom HTTP headers to include with every request.

credentials?:

"omit" | "same-origin" | "include"

Credentials mode for requests. See https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials for more info.

Methods

listAgents():

Promise<Record<string, GetAgentResponse>>

Returns all available agent instances.

getAgent(agentId):

Agent

Retrieves a specific agent instance by ID.

listAgentControllers():

Promise<AgentControllerInfo[]>

Returns the agent controllers hosted on the connected Mastra instance. Each entry's id is the key the controller is registered under in new Mastra({ agentControllers }).

getAgentController(controllerId):

AgentController

Retrieves a specific agent controller by the key it is registered under in new Mastra({ agentControllers }), which can differ from the controller id. .session(sessionId) returns a session client; call await session.create() to create or resume the server session.

listMemoryThreads(params):

Promise<StorageThreadType[]>

Retrieves memory threads for the specified resource and agent. Requires a resourceId and an agentId.

createMemoryThread(params):

Promise<MemoryThread>

Creates a new memory thread with the given parameters.

getMemoryThread({ threadId, agentId }):

MemoryThread

Fetches a specific memory thread by ID.

saveMessageToMemory(params):

Promise<{ messages: (MastraMessageV1 | MastraDBMessage)[] }>

Saves one or more messages to the memory system. Returns the saved messages.

getMemoryStatus():

Promise<MemoryStatus>

Returns the current status of the memory system.

listTools():

Record<string, Tool>

Returns all available tools.

getTool(toolId):

Tool

Retrieves a specific tool instance by ID.

listWorkflows():

Record<string, Workflow>

Returns all available workflow instances.

getWorkflow(workflowId):

Workflow

Retrieves a specific workflow instance by ID.

getAgentBuilderActions():

Promise<GetAgentBuilderActionsResponse>

Returns all available Agent Builder actions. See Agent Builder API.

getAgentBuilderAction(actionId):

AgentBuilder

Retrieves an Agent Builder action by ID. See Agent Builder API.

responses:

Responses

Provides OpenAI-style Responses API helpers with create(), retrieve(), stream(), and delete().

conversations:

Conversations

Provides conversation helpers with create(), retrieve(), delete(), and items.list().

resumeBackgroundTask(backgroundTaskId, resumeData, options?):

Promise<BackgroundTaskResponse>

Answers a suspended background task with resumeData and returns the task. Pass options.suspendedAt (a Date, ISO string, or epoch milliseconds) from the task you read; the server rejects the answer with 409 if the task has resumed or suspended again since. Also rejects with 409 when the task isn't suspended or no concurrency slot is free, and 404 when the task doesn't exist or belongs to another resource.

getVector(vectorName):

MastraVector

Returns a vector store instance by name.

listLogs(params):

Promise<LogEntry[]>

Fetches system logs matching the provided filters.

getLog(params):

Promise<LogEntry>

Retrieves a specific log entry by ID or filter.

listLogTransports():

string[]

Returns the list of configured log transport types.

getTrace(traceId):

Promise<TraceRecord>

Retrieves a specific trace by ID, including all its spans and details.

getTraces(params):

Promise<GetTracesResponse>

Retrieves paginated list of trace root spans with optional filtering. Use getTrace() to get complete traces with all spans.

deleteTraces(params):

Promise<{ success: true }>

Deletes traces by ID and cascades deletion to their trace-linked observability signals.