Skip to main content
PATCH
JavaScript
Edit the agent’s own settings. The prompt, model, and tools live on the variations; this endpoint changes the shell around them.

Editing a published agent keeps it published

An edit does not knock the agent back to draft. Change its name or mode while it is STATE_PUBLISHED and it stays published, with the change live on the next objective. There is no republish step, the same as editing a variation.

What you can change

variationSelectionMode flips freely, so you can move an agent from equal-odds RANDOM to Thompson-sampled WEIGHTED once its variations have earned enough feedback to rank.

The merge keeps what you leave out, except zero values

Like every PATCH here, the update merges: send metadata.name alone and the mode, memory flag, and output schema all survive. The one snag is turning a boolean off. enableEpisodicMemory: false is a proto zero value, indistinguishable from “not sent,” so a plain merge ignores it and the flag stays on:
Turning it on works through a plain merge, because true is not the zero value. Only the off direction needs the mask. Same rule as temperature: 0 on a variation.

Update a variation

The prompt, model, and tools, with the same zero-value rule.

Publish an agent

Why an edit does not un-publish.

Create an agent

Every field this endpoint can change.

List variations

The score that WEIGHTED mode samples from.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

id
string
required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

Body

application/json

Update agent request

metadata
object

UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

spec
object

Agent specification (user-provided configuration)

updateMask
string<field-mask>

Fields to update

Response

OK

Agent resource

metadata
object
required

Resource metadata

spec
object
required

Agent specification

state
enum<string>
required
read-only

The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states.

Available options:
STATE_UNSPECIFIED,
STATE_DRAFT,
STATE_PUBLISHED,
STATE_ARCHIVED
info
object

Agent information