Save a new immutable revision of a custom Agent definition

PATCH/api/v1/workspaces/{workspace_id}/agents/studio/definitions/{definition_id}

Path Parameters

workspace_idRequired

string <uuid>

Example0198ac5e-f9b7-7000-8000-000000000001

definition_idRequired

string <uuid>

Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired

string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

If-MatchRequired

string

Entity tag containing the resource version last observed by the client.

Request Body

application/json

slugRequired

string·min 2·max 80

nameRequired

string·min 1·max 80

descriptionRequired

string·min 1·max 500

responsibilityRequired

string·min 1·max 500

personality

string·max 1000

Customer-authored tone and interaction style.

routing_description

string·max 500

Safe description used to select this Agent for a request; responsibility is used when omitted.

routing_tags

string[]·max 12

instructionsRequired

string·min 1·max 8000

conversation_starters

string[]·max 6

subagent_definition_ids

string <uuid>[]·max 8

Same-Workspace custom Agent definitions this Agent may delegate to. Self-references and cycles are rejected.

approval_policy

string·default manage_actions

Values

manage_actionsevery_action

prohibited_actions

string[]·max 12

trigger_types

string[]·min 1·max 3·default ["manual"]

Values

manualeventschedule

visibility

string·default workspace

Values

workspace

stateRequired

string

Values

draftactivepaused

mcp_enabled

boolean

Allow permitted Assign MCP operations under this Agent identity. New definitions default to false; omitted updates preserve the current value. Saving false revokes operational access.

bindingsRequired

object[]·max 32

Responses

Authentication · Conventions and errors · API guides · Resource reference

Save a new immutable revision of a custom Agent definition