Skip to main content

Mastra.getStoredAgentById()

The .getStoredAgentById() method retrieves an agent configuration from storage by its ID and creates an executable Agent instance. Stored agents allow you to persist agent configurations in a database and dynamically load them at runtime.

Usage example
Direct link to Usage example

// Get an Agent instance from storage
const agent = await mastra.getStoredAgentById("my-stored-agent");

if (agent) {
  const response = await agent.generate({ messages: "Hello!" });
  console.log(response.text);
}
// Get the raw storage data instead of an Agent instance
const storedConfig = await mastra.getStoredAgentById("my-stored-agent", { raw: true });

if (storedConfig) {
  console.log(storedConfig.instructions);
  console.log(storedConfig.createdAt);
}

Parameters
Direct link to Parameters

id:

string
The unique identifier of the stored agent to retrieve.

options?:

{ raw?: boolean }
Optional configuration object.

Options
Direct link to Options

raw?:

boolean
= false
When `true`, returns the raw `StorageAgentType` object from storage instead of creating an `Agent` instance. Useful for inspecting stored configuration or metadata.

Returns
Direct link to Returns

result:

Agent | StorageAgentType | null
Returns an `Agent` instance by default, or `StorageAgentType` when `raw: true`. Returns `null` if no agent with the given ID exists.

Primitive Resolution
Direct link to Primitive Resolution

When creating an Agent instance from stored configuration, the method resolves references to registered primitives:

  • Tools: Resolved from tools registered in Mastra config
  • Workflows: Resolved from workflows registered in Mastra config
  • Sub-agents: Resolved from agents registered in Mastra config
  • Memory: Resolved from memory registered in Mastra config
  • Scorers: Resolved from scorers registered in Mastra config, including sampling configuration

If a referenced primitive is not found in the registry, a warning is logged but the agent is still created.

StorageAgentType
Direct link to StorageAgentType

When using raw: true, the returned object has the following structure:

id:

string
Unique identifier for the agent.

name:

string
Display name of the agent.

description?:

string
Optional description of the agent.

instructions:

string
System instructions for the agent.

model:

Record<string, unknown>
Model configuration with provider and name.

tools?:

Record<string, unknown>
Tool references to resolve from registry.

workflows?:

Record<string, unknown>
Workflow references to resolve from registry.

agents?:

Record<string, unknown>
Sub-agent references to resolve from registry.

memory?:

Record<string, unknown>
Memory reference to resolve from registry.

scorers?:

Record<string, unknown>
Scorer references with optional sampling config.

defaultOptions?:

Record<string, unknown>
Default options passed to agent execution.

metadata?:

Record<string, unknown>
Custom metadata stored with the agent.

createdAt:

Date
Timestamp when the agent was created.

updatedAt:

Date
Timestamp when the agent was last updated.