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

string

required

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

Request Body

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

string

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

string

Agent description. Updates metadata only.

string

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

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

boolean

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

string

Icon identifier from icon library.

string

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

string

Icon background color in hex format.

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
  }
]

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"
    }
  }
]

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 }
}

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.

string

Unique identifier for the agent

string

Updated agent name

string

Current system prompt (from active version)

string

Current AI model (from active version)

string

UUID of the new version if configuration changed, otherwise unchanged

integer

Total number of versions (incremented if new version created)

object

Complete configuration of the active version

Show Version Object

integer

Sequential version number (incremented on config changes)

string

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

string

System prompt for this version

string

AI model for this version

array

MCP configurations

array

Custom MCP servers

object

Tool configurations

string

ISO 8601 timestamp of version creation

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"
  }'

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 '{
    "system_prompt": "You are an expert Python developer. Focus on writing clean, Pythonic code with comprehensive error handling."
  }'

from kortix import Kortix

client = Kortix(api_key="YOUR_API_KEY")

# Get current configuration
agent = client.agents.get("550e8400-e29b-41d4-a716-446655440000")

# Enable web search tool
tools = agent.agentpress_tools.copy()
tools['web_search'] = {'enabled': True}

# Update agent (creates new version)
updated_agent = client.agents.update(
    agent_id=agent.agent_id,
    agentpress_tools=tools
)

print(f"Created version {updated_agent.current_version.version_name}")
print(f"Web search enabled: {updated_agent.agentpress_tools['web_search']['enabled']}")

import { Kortix } from '@kortix/sdk';

const client = new Kortix({ apiKey: 'YOUR_API_KEY' });

const updatedAgent = await client.agents.update(
  '550e8400-e29b-41d4-a716-446655440000',
  {
    configuredMcps: [
      { mcpId: 'brave-search', enabled: true },
      { mcpId: 'github', enabled: true },
    ],
  }
);

console.log(`Version: ${updatedAgent.currentVersion.versionName}`);
console.log(`MCPs: ${updatedAgent.configuredMcps.length}`);

const axios = require('axios');

const response = await axios.put(
  'https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000',
  {
    model: 'openai/gpt-5-nano-2025-08-07',
  },
  {
    headers: {
      'Authorization': `Bearer ${process.env.KORTIX_API_KEY}`,
      'Content-Type': 'application/json',
    },
  }
);

const agent = response.data;
console.log('Updated to model:', agent.model);
console.log('New version:', agent.current_version.version_name);

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

error

Agent does not exist or user does not have access

{
  "detail": "Worker not found"
}

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."
}

error

Invalid request data

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

error

Missing or invalid authentication token

{
  "detail": "Not authenticated"
}

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

​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

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