Skip to main content
PATCH
Update Agent

Usage

The Update Agent endpoint allows you to update an existing agent’s configuration. The API uses deep merging, so you only need to provide the fields you want to update.
Unknown top-level keys return HTTP 400 (not a silent 200). Only documented / allowlisted fields are accepted. Use additionalConfig only as an escape hatch for fields not yet promoted — secrets and channel credentials inside it are rejected.
Important: Agent instructions are stored in the nodes array, not at the top level. To update your agent’s prompt/instructions, you must update the nodes[0].instructions field where the node has id: "__start__".
These are first-class PATCH params (no longer “legacy / ignore”):

Updating Agent Instructions

Agent instructions are stored within the nodes array. Each agent has a start node with id: "__start__" that contains the main instructions.

Example: Update Instructions Only

Example: Update Instructions and LLM Model

Example: Update Agent Metadata and Instructions

Node Structure

Each node in the nodes array can have the following properties:

Using Variables and Tools in Instructions

You can reference variables and tools in your instructions using the following syntax:
  • Variables: {{var:variable_id}}
  • Tools: {{tool:tool_id}}

Updating Custom Theme & Color Palette

You can customize your agent’s appearance by setting a custom color palette. This requires setting both the theme field and the customThemeJSONString field.

Example: Custom Dark Theme

Example: Custom Light Theme

Custom Theme JSON Structure

The customThemeJSONString is a stringified JSON object with the following properties:

HSL Color Format

Each color in nineColorPallet is an array of 3 numbers:
  • Hue: 0-360 (position on the color wheel)
  • Saturation: 0-100 (color intensity percentage)
  • Lightness: 0-100 (brightness percentage)
Important: When updating the custom theme, ensure that:
  1. The theme field matches the themeType in the JSON string (e.g., "custom-dark" with "themeType": "dark")
  2. The nineColorPallet array contains exactly 10 HSL color values
  3. The customThemeJSONString is a properly escaped JSON string

Auto-Generate Palette

If you only want to set a primary color and have the palette auto-generated:

Example Response

Prompt fields vs nodes

For the live agent prompt, prefer updating nodes (id: "__start__"instructions). Top-level vg_systemPrompt / vg_initPrompt / vg_initMessages are accepted and stored, and are useful for migrations and tooling, but node instructions are what the runtime uses when enableNodes is true.

Notes

  • The API uses deep merging, so only the fields you specify will be updated
  • When updating nodes, the merge is performed by matching the id field
  • You only need to provide the node properties you want to change; other properties will be preserved
  • The lastModified timestamp is automatically updated
  • Model changes stamp modelId / modelIdLastChangedAt / modelIdLastChangedBy and write an audit-log entry
  • Unknown top-level keys → 400
  • If the agent doesn’t exist, a 404 error will be returned
  • You must be the owner of the agent to update it
  • See GET /agents/{agentId}/audit-log for field-level history

Authorizations

Authorization
string
header
required

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

Path Parameters

id
string
required

Body

application/json
agent
object
required

Response

Successful response

success
boolean
required
message
string
required
data
object
required