Skip to main content

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
Direct link to Usage example

// 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({ messages: "Hello!" });
}
// 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
Direct link to Parameters

args?:

object
Optional configuration object for pagination and output format.

Args Options
Direct link to Args Options

page?:

number
= 0
Zero-indexed page number for pagination.

perPage?:

number | false
= 100
Number of items per page. Set to `false` to fetch all records without pagination.

raw?:

boolean
= false
When `true`, returns raw `StorageAgentType` objects instead of `Agent` instances.

Returns
Direct link to 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
Direct link to 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
Direct link to Example: Iterating Through All Stored Agents

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;
}