Update Agent

Update an existing agent’s configuration

PATCH /v1/agents/

Update one or more fields of an existing agent. Only provided fields will be updated (partial update).

Path Parameters

id · string · required

UUID of the agent to update

Request Body

All fields are optional. Only include fields you want to update.

name · string

Update agent name. Maximum 2 KB.

system_prompt · string

Update base system prompt. Maximum 1 MB.

description · string

Update description. Maximum 10 KB.

default_model_id · string

Update default model UUID. Set to null to remove model override.

capabilities · array

Replace capabilities list. Maximum 250 items.

This field replaces the entire capabilities array. To add a single capability, you must include all existing capabilities plus the new one.

Response

Returns the updated agent object with all fields.

id · string

UUID of the agent (unchanged)

name · string

Updated agent name

system_prompt · string

Updated system prompt

description · string

Updated description

default_model_id · string

Updated default model UUID

capabilities · array

Updated capabilities array

status · string

Agent status (unchanged by PATCH)

created_at · string

Original creation timestamp

updated_at · string

New update timestamp

Example: Update Name and Description

curl -X PATCH http://localhost:9300/v1/agents/01933b5a-0000-7000-8000-000000000001 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Research Assistant",
    "description": "Enhanced research agent with additional capabilities"
  }'

Example: Add Capability

curl -X PATCH http://localhost:9300/v1/agents/01933b5a-0000-7000-8000-000000000001 \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": [
      "current_time",
      "web_fetch",
      "session_file_system",
      "stateless_todo_list"
    ]
  }'

Example: Update Model

curl -X PATCH http://localhost:9300/v1/agents/01933b5a-0000-7000-8000-000000000001 \
  -H "Content-Type: application/json" \
  -d '{
    "default_model_id": "01933b5a-0000-7000-8000-000000000020"
  }'

Example Response

{
  "id": "01933b5a-0000-7000-8000-000000000001",
  "name": "Advanced Research Assistant",
  "system_prompt": "You are a helpful research assistant.",
  "description": "Enhanced research agent with additional capabilities",
  "default_model_id": "01933b5a-0000-7000-8000-000000000020",
  "capabilities": [
    "current_time",
    "web_fetch",
    "session_file_system",
    "stateless_todo_list"
  ],
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z"
}

Changes to agent configuration do not affect existing sessions. New sessions created after the update will use the new configuration. To apply changes to existing sessions, you would need to update the session’s capabilities separately.

Error Responses

• 400 Bad Request - Invalid input or size limits exceeded
• 404 Not Found - Agent with specified ID does not exist
• 422 Unprocessable Entity - Validation error (invalid capability reference)
• 500 Internal Server Error - Server error