Update an agent (partial update)

Partially update agent fields. Setting status: draft clears the published_config snapshot. If the agent is published, has_draft_changes is automatically set to true.

PATCH /v1/agents/{agentId}

Update an agent (partial update)

cURL

curl --request PATCH \
  --url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "model": "<string>",
  "fallback_models": [
    "<string>"
  ],
  "temperature": 123,
  "icon_url": "<string>",
  "skills": [
    {}
  ],
  "tools": [
    {
      "id": "<string>",
      "name": "<string>",
      "display_name": "<string>",
      "description": "<string>",
      "catalog_id": "<string>",
      "auth": {},
      "icon_url": "<string>",
      "vector_store_id": "<string>",
      "server": "<string>",
      "headers": {},
      "scope": "<string>",
      "url": "<string>",
      "parameters": {}
    }
  ],
  "tool_permissions": {
    "default": "auto",
    "tools": [
      {
        "tool": "<string>",
        "conditions": {},
        "approvers": [
          {
            "id": "<string>"
          }
        ]
      }
    ]
  },
  "tool_activation": {
    "default": "auto",
    "tools": [
      {
        "tool": "<string>"
      }
    ]
  },
  "guardrails": {},
  "sub_agents": [
    {
      "agent_id": "<string>",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "starters": [
    {}
  ],
  "allowed_models": [
    "<string>"
  ],
  "max_tokens": 123,
  "max_turns": 123,
  "token_budget": 123,
  "tool_call_budget": 123,
  "canvas_enabled": true,
  "category": "<string>",
  "tags": [
    "<string>"
  ],
  "owner_id": "<string>",
  "orgSlug": "<string>",
  "subscription_id": "<string>",
  "serviceAccountId": "<string>",
  "published_config": {},
  "published_at": "2023-11-07T05:31:56Z",
  "has_draft_changes": true,
  "rating": 123,
  "ratings_count": 123,
  "messages_count": 123,
  "conversations_count": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

BearerAuthOrgApiKeyAuth

Authorization · string · header · required

User-bound credential carrying an identity: either a session JWT or a user access token (at:*) generated from the user settings UI. Send as Authorization: Bearer <token>. Org API keys (iak_*) are not accepted here - they carry no user identity. Use the x-prismeai-api-key header instead (see OrgApiKeyAuth).

Path Parameters

agentId · string · required

Maximum string length: 64

Body

application/json

Partial agent update payload. Any subset of the writable Agent fields.

name · string

Maximum string length: 256

description · string

Maximum string length: 4096

instructions · string

Maximum string length: 100000

model · string

Maximum string length: 128

fallback_models · string[]

temperature · number

icon_url · string

skills · object[]

guardrails · object

sub_agents · object[]

tool_permissions · object

Human-in-the-Loop configuration. Sets a default policy plus optional per-tool overrides. Policies:

• auto: run immediately (default).
• always_ask: halt every call on approval.
• ask_external: halt only on MCP tool calls.
• ask_first: halt the first time a tool runs in a session; cache keyed per child name unless an MCP parent rule is configured (then cached per parent).

Hide child attributes

tool_permissions. default · enum<string> · default: auto

Available options: auto, always_ask, ask_external, ask_first

tool_permissions. tools · object[]

Hide child attributes

tool_permissions.tools. tool · string · required

tool_permissions.tools. policy · enum<string> · required

Available options: auto, always_ask, ask_external, ask_first

tool_permissions.tools. conditions · object

Optional jsonmatch pattern compared against the tool call's arguments. The rule's policy only fires when the pattern matches; otherwise the call runs without prompting.

tool_permissions.tools. approvers · object[]

Hide child attributes

tool_permissions.tools.approvers. type · enum<string> · required

Available options: owner, user, group

tool_permissions.tools.approvers. id · string

Required for user and group. Ignored for owner.

tool_activation · object

Controls whether the model can use a given tool on a given turn. user_first tools are replaced by a same-named, schema-less stub with a "disabled" description on each turn, unless the user explicitly summons the tool from the chat input via metadata.tool_choice. Eligible tool types: function and mcp. file_search, skill, guardrail, and system types are exempt and always behave as auto.

Hide child attributes

tool_activation. default · enum<string> · default: auto

Available options: auto, user_first

tool_activation. tools · object[]

Hide child attributes

tool_activation.tools. tool · string · required

tool_activation.tools. activation · enum<string> · required

Available options: auto, user_first

allowed_models · string[]

max_tokens · integer

max_turns · integer

token_budget · integer

tool_call_budget · integer

canvas_enabled · boolean

visibility · enum<string>

Available options: public, private, restricted

Maximum string length: 32

category · string

Maximum string length: 128

tags · string[]

starters · object[]

status · enum<string>

Available options: draft, published

Maximum string length: 32

profile · enum<string>

Available options: simple, workflow, agent_light, agent_full, orchestrator

Maximum string length: 64

Response

200

application/json

Updated agent record.

Agent record (full view). Owners see this complete record including published_config. Non-owners with binding receive the same shape with published_config stripped server-side. Restricted-agent rows additionally carry access_status (granted or none) when seen in list/discovery views.

id · string

name · string

description · string

instructions · string

model · string

fallback_models · string[]

temperature · number

icon_url · string

skills · object[]

tools · object[]

Hide child attributes

tools. id · string

tools. type · enum<string>

Available options: file_search, mcp, function

tools. name · string

Pattern: ^[a-zA-Z0-9_-]+$

tools. display_name · string

tools. description · string

tools. catalog_id · string

tools. auth · object

tools. icon_url · string

tools. vector_store_id · string

Required for file_search.

tools. server · string

MCP server URL (for mcp).

tools. headers · object

tools. scope · string

tools. url · string

Required for function.

tools. parameters · object

JSON Schema describing the function tool's parameters.

tool_permissions · object

Human-in-the-Loop configuration. Sets a default policy plus optional per-tool overrides. Policies:

• auto: run immediately (default).
• always_ask: halt every call on approval.
• ask_external: halt only on MCP tool calls.
• ask_first: halt the first time a tool runs in a session; cache keyed per child name unless an MCP parent rule is configured (then cached per parent).

Hide child attributes

tool_permissions. default · enum<string> · default: auto

Available options: auto, always_ask, ask_external, ask_first

tool_permissions. tools · object[]

Hide child attributes

tool_permissions.tools. tool · string · required

tool_permissions.tools. policy · enum<string> · required

Available options: auto, always_ask, ask_external, ask_first

tool_permissions.tools. conditions · object

Optional jsonmatch pattern compared against the tool call's arguments. The rule's policy only fires when the pattern matches; otherwise the call runs without prompting.

tool_permissions.tools. approvers · object[]

Hide child attributes

tool_permissions.tools.approvers. type · enum<string> · required

Available options: owner, user, group

tool_permissions.tools.approvers. id · string

Required for user and group. Ignored for owner.

tool_activation · object

Controls whether the model can use a given tool on a given turn. user_first tools are replaced by a same-named, schema-less stub with a "disabled" description on each turn, unless the user explicitly summons the tool from the chat input via metadata.tool_choice. Eligible tool types: function and mcp. file_search, skill, guardrail, and system types are exempt and always behave as auto.

Hide child attributes

tool_activation. default · enum<string> · default: auto

Available options: auto, user_first

tool_activation. tools · object[]

Hide child attributes

tool_activation.tools. tool · string · required

tool_activation.tools. activation · enum<string> · required

Available options: auto, user_first

guardrails · object

sub_agents · object[]

Hide child attributes

sub_agents. agent_id · string

sub_agents. name · string

sub_agents. description · string

starters · object[]

allowed_models · string[]

max_tokens · integer

max_turns · integer

token_budget · integer

tool_call_budget · integer

canvas_enabled · boolean

visibility · enum<string>

Available options: public, private, restricted

category · string

tags · string[]

status · enum<string>

Available options: draft, published

profile · enum<string>

Available options: simple, workflow, agent_light, agent_full, orchestrator

owner_id · string

orgSlug · string

subscription_id · string

serviceAccountId · string

published_config · object

Snapshot of runtime fields at last publish (owners only).

published_at · string<date-time>

has_draft_changes · boolean

rating · number

ratings_count · integer

messages_count · integer

conversations_count · integer

access_status · enum<string>

Only present on restricted-agent rows in list/discovery views.

Available options: granted, none

createdAt · string<date-time>

updatedAt · string<date-time>