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

Create or replace a Custom Agent definition. Used for both creation and full-config updates.

Properties

• name string optional
  The agent’s name: lower-case letters, digits and hyphens, at most 64 characters, unique within the organization. Optional – when omitted it is derived from displayName, so a form that asks for one name still works. A name already taken by another agent is rejected with a 409 rather than silently suffixed. Supplying a different name on an update renames the agent, which is safe because every internal reference is by id.
• displayName string optional
  The human-readable label shown wherever the agent is displayed. Required unless name is supplied, in which case the name is used as the label too.
• roleId string optional
  The RBAC role id the agent’s tasks assume. With Agents-as-Team-Members enabled, creation with omitted/null or empty uses the feature’s read-only default; on update, omitted/null preserves the existing role and empty selects that default. A role that does not exist in the organization is rejected with a 404.
• permissionMode enum optional
  Deprecated. Custom Agent authority is controlled by roleId and this field is ignored.
  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 to enable 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. ‘manual’ makes the agent propose rather than act, and applies to every run of the agent, including scheduled and triggered ones – such a run stops and waits for a person even though nothing yet notifies them it is waiting, so choose it deliberately for an unattended agent.
  Values: manual, auto, balanced