> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Mastra.getAgentById()

The `.getAgentById()` method retrieves a registered agent by its `id`. It first searches registered agents by `agent.id`. If no agent matches, it falls back to [`Mastra.getAgent()`](https://mastra.ai/reference/core/getAgent) and treats the provided value as the agent registry key.

Use `mastra.getAgentById(id)` to retrieve the code-defined agent. Use `await mastra.getAgentById(id, version)` to retrieve a versioned agent.

## Usage example

The following example registers an agent, retrieves it by ID, and uses the returned agent.

```typescript
import { Agent } from '@mastra/core/agent'
import { Mastra } from '@mastra/core/mastra'

const supportAgent = new Agent({
  id: 'support-agent-id',
  name: 'Support Agent',
  instructions: 'Answer support questions clearly and concisely.',
  model: 'openai/gpt-5.5',
})

export const mastra = new Mastra({
  agents: {
    supportAgent,
  },
})

const agent = mastra.getAgentById('support-agent-id')

const response = await agent.generate('How can I reset my password?')
```

## Parameters

**id** (`string`): The ID of the agent to retrieve. Mastra first searches registered agents by agent.id. If none match, it uses this value as the agent registry key and calls getAgent().

**version** (`{ versionId: string } | { status?: 'draft' | 'published' }`): Optional version selector for retrieving a versioned agent. When provided, the method returns a promise.

**version.versionId** (`string`): The ID of a specific agent version to retrieve.

**version.status** (`'draft' | 'published'`): Select the latest agent version with this publication status.

## Returns

**agent** (`TAgents[TAgentName]`): The agent instance with the specified ID when version is omitted.

**agent** (`Promise<TAgents[TAgentName]>`): A promise that resolves to the versioned agent instance when version is provided.

Throws a `MastraError` when no agent is found by ID or registry key.

## Related

- [Mastra.getAgent()](https://mastra.ai/reference/core/getAgent)
- [Agents overview](https://mastra.ai/docs/agents/overview)