> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent definitions

> Define factory-scoped agents with their own instructions and access.

Beta

> [!NOTE]
>
> **Agent Sessions** is in private preview. The API is not part of the public
> SDKs yet.

An agent definition is a factory-scoped agent with its own instructions and access. A factory can have several definitions; their names and descriptions identify which one a run should use.

New factories include Planner, Implementer, and Reviewer definitions. The Planner classifies the request, checks the repository context, decides whether the work is ready, then plans. Update them or add specialized definitions.

## Configuration

| Field | Purpose |
| - | - |
| `display_name`, `description` | Identify the agent and describe when it should be selected. Names are unique within a factory. |
| `model` | Optional gateway model. The factory's effective policy must allow an override. |
| `phase_instructions` | Instructions injected when the agent starts a run. |
| `capabilities` | Git access plus allowed MCP gateways, skills, and tools. These cannot widen factory policy. |

### Phase instructions

`phase_instructions` is added to the agent's system instructions for the run. Keep it specific to the work that definition does.

### Capabilities

Capabilities limit each run to the access required for its phase:

| Capability | Behavior |
| - | - |
| `git: none` | Provides no Git credential to the run. |
| `git: read` | Provides a repository-scoped GitHub App token with `contents:read`. Personal access tokens and OAuth tokens are not used because they cannot be downscoped. |
| `mcp_gateway_ids`, `skill_ids`, `allowed_tools` | Limits the MCP gateways, skills, and runtime tools available to the run. |

Pushes and pull requests are always control-plane actions. Write credentials are sent only with that operation and are not stored in the agent environment. The built-in reviewer receives no Git credential. Custom definitions can request read-only Git access when the factory policy permits it. All capabilities remain subject to the factory's effective policy. An agent definition cannot widen factory access.

## API

| Method and path | Purpose |
| - | - |
| `POST /v3/factories/{factory_id}/agent-definitions` | Create a definition. |
| `GET /v3/factories/{factory_id}/agent-definitions` | List definitions. |
| `GET /v2/agent-definitions/{agent_definition_id}` | Read a definition. |
| `PATCH /v2/agent-definitions/{agent_definition_id}` | Update mutable fields. |
| `DELETE /v2/agent-definitions/{agent_definition_id}` | Delete a definition. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.