1. Docs
2. Reference
3. REST API Docs
4. Schema
5. AgentDefinition

A Custom Agent definition: a saved, team-owned agent configuration that a task can be run as. Its role, integrations, and instructions are applied to every task run as the agent.

Properties

• id string required
  The unique identifier of the agent definition.
• name string required
  The agent’s name: lower-case letters, digits and hyphens, unique within the organization. This is the stable handle a person writes down – in an automation, in a CLI invocation – and it may be changed, because everything that references an agent internally references it by id.
• displayName string required
  The human-readable label shown wherever the agent is displayed. Falls back to the name when the agent has none.
• roleId string optional
  The RBAC role id the agent’s tasks assume, identified by role id. Null means no assumed role: tasks run with the invoking user’s own permissions.
• permissionMode enum optional
  Deprecated. Custom Agent authority is controlled by roleId.
  Values:

  default — Default

  read-only — ReadOnly

• customInstructions string optional
  Instructions that shape how the agent behaves in the team’s environment.
• enabledIntegrations array[AgentTaskIntegrationRef] optional
  The integrations enabled for the agent’s tasks, by id. Omitted or null inherits all organization integrations; an empty list enables none.
• ↳ id string required
  The catalog integration ID (e.g. ‘honeycomb’, ‘datadog’).
• purpose string optional
  A one-line description of what this agent is for, shown under its name in the roster.
• avatar string optional
  A presentation token the console maps to an icon. Not an uploaded asset.
• approvalMode enum optional
  The approval posture the agent’s runs inherit. When omitted, runs are auto-approved, matching scheduled automations.
  Values: manual, auto, balanced
• pausedAt string optional
  When the agent was paused, or null if it is not paused. A paused agent starts no new runs from any source – console, schedule, or trigger – until it is resumed; runs already in flight continue.
• pausedBy string optional
  Who paused the agent, by user id. Null when the agent is not paused. Recorded by the server from the caller rather than supplied by the client.
• pausedReason string optional
  Why the agent was paused. Null when it is not paused, or when no reason was given.
• taskCounts AgentDefinitionTaskCounts optional
  Run counts for this agent, shown on its roster card.
• ↳ total integer required
  How many runs this agent has started in total.
• ↳ running integer required
  How many of this agent’s runs are currently running.