# Mastra.listStoredAgents()

The `.listStoredAgents()` method retrieves a paginated list of agent configurations from storage. By default, it returns executable `Agent` instances, but can also return raw storage data.

## Usage example

```typescript
// Get Agent instances from storage
const { agents, total, hasMore } = await mastra.listStoredAgents();

for (const agent of agents) {
  console.log(agent.id, agent.name);
  // Each agent is ready to use
  // const response = await agent.generate("Hello");
}
```

```typescript
// Get paginated results with raw storage data
const result = await mastra.listStoredAgents({
  page: 0,
  perPage: 10,
  raw: true,
});

console.log(`Showing ${result.agents.length} of ${result.total} agents`);
console.log(`Has more: ${result.hasMore}`);

for (const config of result.agents) {
  console.log(config.id, config.name, config.createdAt);
}
```

## Parameters

### args?:

object

Optional configuration object for pagination and output format.

### Args Options

### page?:

number

Zero-indexed page number for pagination.

### perPage?:

number | false

Number of items per page. Set to \`false\` to fetch all records without pagination.

### raw?:

boolean

When \`true\`, returns raw \`StorageAgentType\` objects instead of \`Agent\` instances.

## Returns

### agents:

Agent\[] | StorageAgentType\[]

Array of \`Agent\` instances by default, or \`StorageAgentType\` objects when \`raw: true\`.

### total:

number

Total number of stored agents across all pages.

### page:

number

Current page number (zero-indexed).

### perPage:

number | false

Number of items per page, or \`false\` if fetching all.

### hasMore:

boolean

Whether there are more pages available.

## Primitive Resolution

When creating `Agent` instances (default behavior), each stored agent's configuration is resolved against 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

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

## Example: Iterating Through All Stored Agents

```typescript
async function getAllStoredAgents(mastra: Mastra) {
  const allAgents: Agent[] = [];
  let page = 0;
  let hasMore = true;

  while (hasMore) {
    const result = await mastra.listStoredAgents({ page, perPage: 50 });
    allAgents.push(...result.agents);
    hasMore = result.hasMore;
    page++;
  }

  return allAgents;
}
```

## Related

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