Update Agent

Endpoint

PUT /agents/{agent_id}

Authentication

Requires JWT authentication via Authorization: Bearer <token> header.

Description

Updates an agent’s configuration. Changes to system_prompt, model, configured_mcps, custom_mcps, or agentpress_tools automatically create a new version. Changes to name, icon, or is_default update the agent metadata without creating a new version. Versioning Behavior:

Configuration changes (prompt, model, tools, MCPs) → Creates new version (v2, v3, etc.)
Metadata changes (name, icon, is_default) → Updates agent record directly

Path Parameters

agent_id

string

required

The unique identifier (UUID) of the agent to update.

Request Body

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

name

string

Agent name (2-100 characters). Updates metadata only, does not create new version.

description

string

Agent description. Updates metadata only.

system_prompt

string

System prompt for the agent. Creates new version if changed.

model

string

AI model identifier (e.g., “kortix/basic”, “openai/gpt-4”). Creates new version if changed.Available based on tier:

Free: kortix/minimax
Pro: kortix/basic, openai/gpt-5-nano, anthropic/claude-3.5-sonnet
Enterprise: All models

is_default

boolean

Whether this agent should be the default for new threads. Setting to true automatically unsets other default agents.

icon_name

string

Icon identifier from icon library.

icon_color

string

Icon color in hex format (e.g., “#6366F1”).

icon_background

string

Icon background color in hex format.

configured_mcps

array

Array of configured MCP integrations. Creates new version if changed.

Show MCP Configuration

[
  {
    "mcp_id": "brave-search",
    "enabled": true
  },
  {
    "mcp_id": "github",
    "enabled": false
  }
]

custom_mcps

array

Array of custom MCP server configurations. Creates new version if changed.By default, new custom MCPs are merged with existing ones. Set replace_mcps: true to replace entirely.

Show Custom MCP Structure

[
  {
    "name": "my-custom-server",
    "command": "node",
    "args": ["/path/to/server.js"],
    "env": {
      "API_KEY": "value"
    }
  }
]

agentpress_tools

object

Tool enable/disable configuration. Creates new version if changed.Core tools (bash, read, write, edit, glob, grep) are always enabled and cannot be disabled.

Show Tool Configuration

{
  "bash": { "enabled": true },
  "read": { "enabled": true },
  "write": { "enabled": true },
  "edit": { "enabled": true },
  "glob": { "enabled": true },
  "grep": { "enabled": true },
  "web_search": { "enabled": true },
  "browser": { "enabled": false }
}

replace_mcps

boolean

default:false

If true, replaces all MCPs (both configured and custom) instead of merging.

false (default): New MCPs are merged with existing ones
true: Provided MCPs completely replace existing configuration

Response

Returns the updated agent with full configuration. If a new version was created, version_count is incremented and current_version_id points to the new version.

agent_id

string

Unique identifier for the agent

name

string

Updated agent name

system_prompt

string

Current system prompt (from active version)

model

string

Current AI model (from active version)

current_version_id

string

UUID of the new version if configuration changed, otherwise unchanged

version_count

integer

Total number of versions (incremented if new version created)

current_version

object

Complete configuration of the active version

Show Version Object

version_number

integer

Sequential version number (incremented on config changes)

version_name

string

Auto-generated version label (e.g., “v2”, “v3”)

system_prompt

string

System prompt for this version

model

string

AI model for this version

configured_mcps

array

MCP configurations

custom_mcps

array

Custom MCP servers

agentpress_tools

object

Tool configurations

created_at

string

ISO 8601 timestamp of version creation

updated_at

string

ISO 8601 timestamp of this update

Examples

curl -X PUT https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Code Assistant"
  }'

Response Example (New Version Created)

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Code Assistant",
  "system_prompt": "You are an expert Python developer. Focus on writing clean, Pythonic code with comprehensive error handling.",
  "model": "kortix/basic",
  "current_version_id": "770fa622-g4bd-63f6-c938-668877662222",
  "version_count": 2,
  "current_version": {
    "version_id": "770fa622-g4bd-63f6-c938-668877662222",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "version_number": 2,
    "version_name": "v2",
    "system_prompt": "You are an expert Python developer. Focus on writing clean, Pythonic code with comprehensive error handling.",
    "model": "kortix/basic",
    "configured_mcps": [],
    "custom_mcps": [],
    "agentpress_tools": {
      "bash": { "enabled": true },
      "read": { "enabled": true },
      "write": { "enabled": true },
      "edit": { "enabled": true },
      "glob": { "enabled": true },
      "grep": { "enabled": true }
    },
    "is_active": true,
    "created_at": "2025-08-15T11:45:00.000Z",
    "updated_at": "2025-08-15T11:45:00.000Z",
    "created_by": "user_123abc"
  },
  "configured_mcps": [],
  "custom_mcps": [],
  "agentpress_tools": {
    "bash": { "enabled": true },
    "read": { "enabled": true },
    "write": { "enabled": true },
    "edit": { "enabled": true },
    "glob": { "enabled": true },
    "grep": { "enabled": true }
  },
  "updated_at": "2025-08-15T11:45:00.000Z"
}

Error Responses

404 Not Found

error

Agent does not exist or user does not have access

{
  "detail": "Worker not found"
}

403 Forbidden

error

Attempting to modify restricted fields on system agents (e.g., Suna)

{
  "detail": "Suna's system prompt cannot be modified. This is managed centrally to ensure optimal performance."
}

400 Bad Request

error

Invalid request data

{
  "detail": "Cannot delete default agent"
}

401 Unauthorized

error

Missing or invalid authentication token

{
  "detail": "Not authenticated"
}

500 Internal Server Error

error

Server error during update

{
  "detail": "Failed to update agent: <error details>"
}

Versioning Details

What Creates a New Version?

Changes to these fields trigger automatic version creation:

system_prompt
model
configured_mcps
custom_mcps
agentpress_tools

What Doesn’t Create a Version?

These fields update the agent record directly:

name
description
is_default
icon_name, icon_color, icon_background

Version Naming

Versions are automatically named sequentially: v1, v2, v3, etc.

MCP Merging vs. Replacement

By default, MCPs are merged:

# Current agent has: [{'mcp_id': 'brave-search', 'enabled': true}]

# Update with merge (default)
client.agents.update(
    agent_id=agent_id,
    configured_mcps=[{'mcp_id': 'github', 'enabled': true}]
)
# Result: [{'mcp_id': 'brave-search', 'enabled': true}, {'mcp_id': 'github', 'enabled': true}]

# Update with replace
client.agents.update(
    agent_id=agent_id,
    configured_mcps=[{'mcp_id': 'github', 'enabled': true}],
    replace_mcps=True
)
# Result: [{'mcp_id': 'github', 'enabled': true}]

Restrictions on System Agents

The default “Suna” agent has restrictions managed via metadata.restrictions:

{
  "restrictions": {
    "name_editable": false,
    "system_prompt_editable": false,
    "tools_editable": false,
    "mcps_editable": false
  }
}

Attempting to modify restricted fields returns 403 Forbidden.

Notes

Atomic Updates: All changes are applied atomically
Cache Invalidation: Updates invalidate the agent config cache
Default Agent: Setting is_default: true clears the default flag from other agents
Core Tools: Cannot be disabled even if explicitly set to enabled: false

Get Agent - Retrieve current configuration
Create Agent - Create a new agent
Delete Agent - Remove an agent
List Versions - View version history

Getting Started

Agents

Threads

Tools

SDK

Endpoint

Authentication

Description

Path Parameters

Request Body

Response

Examples

Response Example (New Version Created)

Error Responses

Versioning Details

What Creates a New Version?

What Doesn’t Create a Version?

Version Naming

MCP Merging vs. Replacement

Restrictions on System Agents

Notes

Build docs developers (and LLMs) love

Getting Started

Agents

Threads

Tools

SDK

​Endpoint

​Authentication

​Description

​Path Parameters

​Request Body

​Response

​Examples

​Response Example (New Version Created)

​Error Responses

​Versioning Details

​What Creates a New Version?

​What Doesn’t Create a Version?

​Version Naming

​MCP Merging vs. Replacement

​Restrictions on System Agents

​Notes

​Related Endpoints

Build docs developers (and LLMs) love

Endpoint

Authentication

Description

Path Parameters

Request Body

Response

Examples

Response Example (New Version Created)

Error Responses

Versioning Details

What Creates a New Version?

What Doesn’t Create a Version?

Version Naming

MCP Merging vs. Replacement

Restrictions on System Agents

Notes

Related Endpoints