Skip to main content
Mastra 1.0 is available 🎉 Read announcement

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("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.
On this page