# 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

```typescript
// 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);
}
```

```typescript
// 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

### id:

string

The unique identifier of the stored agent to retrieve.

### options?:

{ raw?: boolean }

Optional configuration object.

### Options

### raw?:

boolean

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

## 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

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

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.

## Related

- [Mastra.listStoredAgents()](https://mastra.ai/reference/core/listStoredAgents/llms.txt)
- [Storage overview](https://mastra.ai/reference/storage/overview/llms.txt)
- [Agents overview](https://mastra.ai/docs/agents/overview/llms.txt)