Agent definitions

Beta

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.

Overview

Managed Agents

Context Management

Test & Evaluate

Chat

Configuration

Phase instructions

Capabilities

API

​Configuration

​Phase instructions

​Capabilities

​API

Configuration

Phase instructions

Capabilities

API