Skip to main content
PATCH
Update an agent (partial)

Authorizations

Authorization
string
header
required

OAuth 2.0 / OIDC bearer token.

Tenant-Name
string
header
required

The tenant the request operates within.

Path Parameters

agentId
string<agent-id>
required

Agent identifier (prefixed UUIDv7). Agent identifier. Accepts agt.<uuidv7> or a bare UUIDv7 on input; always returned prefixed.

Pattern: ^(agt\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40"

Body

application/merge-patch+json

The fields to change, as a JSON Merge Patch (RFC 7386).

JSON Merge Patch body. Omitted fields are unchanged; null clears; connectors is replaced wholesale. Note: the server currently honors only name, description, systemPrompt, model, and connectors. visibility, lifecycle, and labels are accepted but not yet persisted.

name
string

New agent name.

Required string length: 1 - 128
Example:

"coder-v2"

description
string | null

New description; null clears it.

Maximum string length: 4096
Example:

"Returns SNOMED CT codes for a clinical encounter."

systemPrompt
string | null

New system prompt; null clears it.

Example:

"Respond with only the SNOMED CT code."

model
string | null

New model identifier; null falls back to the tenant default.

Example:

"corti-default"

visibility
enum<string>
  • private — creator / service principal only.
  • unlisted — usable by ID, hidden from list results.
  • public — listed tenant-wide.
Available options:
private,
unlisted,
public
Example:

"private"

lifecycle
enum<string>
default:ephemeral
  • ephemeral — short-lived; expired automatically.
  • persistent — retained until explicitly deleted.
Available options:
ephemeral,
persistent
connectors
object[] | null

Replacement connector list; null clears connectors.

Same envelope as Connector but without the server-generated id.

Example:
labels
object | null

Replacement labels; null clears labels.

Example:

Response

The updated agent.

A configured agent — its metadata, model, and attached connectors.

id
string<agent-id>
required

Agent identifier. Accepts agt.<uuidv7> or a bare UUIDv7 on input; always returned prefixed.

Pattern: ^(agt\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40"

name
string
required

Human-readable, unique-per-tenant agent name.

Required string length: 1 - 128
visibility
enum<string>
required
  • private — creator / service principal only.
  • unlisted — usable by ID, hidden from list results.
  • public — listed tenant-wide.
Available options:
private,
unlisted,
public
Example:

"private"

lifecycle
enum<string>
default:ephemeral
required
  • ephemeral — short-lived; expired automatically.
  • persistent — retained until explicitly deleted.
Available options:
ephemeral,
persistent
connectors
object[]
required

Connectors attached to the agent, discriminated by type.

A connector attached to an agent, discriminated by type.

createdAt
string<date-time>
required
read-only

When the agent was created.

updatedAt
string<date-time>
required
read-only

When the agent was last updated.

createdBy
string<user-id>
required
read-only

Principal (user or service principal) that created the agent.

Pattern: ^(usr\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"usr.0192f4c8-8bc0-7194-8570-92e3ce81d0a6"

description
string | null

Free-form agent description shown to users and in tooling.

Maximum string length: 4096
systemPrompt
string | null

System prompt prepended to every invocation.

model
string | null

Model identifier. Tenant default if omitted or null. Open question — in the current implementation a model is configured per expert, not per agent (Expert.modelName), and an Agent has no model field at all. The desired end state is that there is no distinction between an expert and an agent, so model lives uniformly on this resource. Until that convergence lands, the precedence of an agent-level model over a connector/expert-level override is undecided and MUST be resolved before this field ships.

Example:

"corti-default"

labels
object

Free-form string → string metadata for filtering and organisation. Not used for routing or auth.

Example: