> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kortix-ai/suna/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Agent

> Modify an agent's configuration, creating a new version if configuration changes are detected

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

<ParamField path="agent_id" type="string" required>
  The unique identifier (UUID) of the agent to update.
</ParamField>

## Request Body

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

<ParamField body="name" type="string">
  Agent name (2-100 characters). Updates metadata only, does not create new version.
</ParamField>

<ParamField body="description" type="string">
  Agent description. Updates metadata only.
</ParamField>

<ParamField body="system_prompt" type="string">
  System prompt for the agent. Creates new version if changed.
</ParamField>

<ParamField body="model" type="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
</ParamField>

<ParamField body="is_default" type="boolean">
  Whether this agent should be the default for new threads. Setting to `true` automatically unsets other default agents.
</ParamField>

<ParamField body="icon_name" type="string">
  Icon identifier from icon library.
</ParamField>

<ParamField body="icon_color" type="string">
  Icon color in hex format (e.g., "#6366F1").
</ParamField>

<ParamField body="icon_background" type="string">
  Icon background color in hex format.
</ParamField>

<ParamField body="configured_mcps" type="array">
  Array of configured MCP integrations. Creates new version if changed.

  <Expandable title="MCP Configuration">
    ```json theme={null}
    [
      {
        "mcp_id": "brave-search",
        "enabled": true
      },
      {
        "mcp_id": "github",
        "enabled": false
      }
    ]
    ```
  </Expandable>
</ParamField>

<ParamField body="custom_mcps" type="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.

  <Expandable title="Custom MCP Structure">
    ```json theme={null}
    [
      {
        "name": "my-custom-server",
        "command": "node",
        "args": ["/path/to/server.js"],
        "env": {
          "API_KEY": "value"
        }
      }
    ]
    ```
  </Expandable>
</ParamField>

<ParamField body="agentpress_tools" type="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.

  <Expandable title="Tool Configuration">
    ```json theme={null}
    {
      "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 }
    }
    ```
  </Expandable>
</ParamField>

<ParamField body="replace_mcps" type="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
</ParamField>

## 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.

<ResponseField name="agent_id" type="string">
  Unique identifier for the agent
</ResponseField>

<ResponseField name="name" type="string">
  Updated agent name
</ResponseField>

<ResponseField name="system_prompt" type="string">
  Current system prompt (from active version)
</ResponseField>

<ResponseField name="model" type="string">
  Current AI model (from active version)
</ResponseField>

<ResponseField name="current_version_id" type="string">
  UUID of the new version if configuration changed, otherwise unchanged
</ResponseField>

<ResponseField name="version_count" type="integer">
  Total number of versions (incremented if new version created)
</ResponseField>

<ResponseField name="current_version" type="object">
  Complete configuration of the active version

  <Expandable title="Version Object">
    <ResponseField name="version_number" type="integer">
      Sequential version number (incremented on config changes)
    </ResponseField>

    <ResponseField name="version_name" type="string">
      Auto-generated version label (e.g., "v2", "v3")
    </ResponseField>

    <ResponseField name="system_prompt" type="string">
      System prompt for this version
    </ResponseField>

    <ResponseField name="model" type="string">
      AI model for this version
    </ResponseField>

    <ResponseField name="configured_mcps" type="array">
      MCP configurations
    </ResponseField>

    <ResponseField name="custom_mcps" type="array">
      Custom MCP servers
    </ResponseField>

    <ResponseField name="agentpress_tools" type="object">
      Tool configurations
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of version creation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of this update
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL - Update Name theme={null}
  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"
    }'
  ```

  ```bash cURL - Update System Prompt theme={null}
  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."
    }'
  ```

  ```python Python SDK - Enable Web Search theme={null}
  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']}")
  ```

  ```typescript TypeScript SDK - Add MCP Integration theme={null}
  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}`);
  ```

  ```javascript Node.js - Update Model theme={null}
  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);
  ```
</CodeGroup>

### Response Example (New Version Created)

```json theme={null}
{
  "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

<ResponseField name="404 Not Found" type="error">
  Agent does not exist or user does not have access

  ```json theme={null}
  {
    "detail": "Worker not found"
  }
  ```
</ResponseField>

<ResponseField name="403 Forbidden" type="error">
  Attempting to modify restricted fields on system agents (e.g., Suna)

  ```json theme={null}
  {
    "detail": "Suna's system prompt cannot be modified. This is managed centrally to ensure optimal performance."
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Invalid request data

  ```json theme={null}
  {
    "detail": "Cannot delete default agent"
  }
  ```
</ResponseField>

<ResponseField name="401 Unauthorized" type="error">
  Missing or invalid authentication token

  ```json theme={null}
  {
    "detail": "Not authenticated"
  }
  ```
</ResponseField>

<ResponseField name="500 Internal Server Error" type="error">
  Server error during update

  ```json theme={null}
  {
    "detail": "Failed to update agent: <error details>"
  }
  ```
</ResponseField>

## 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:

```python theme={null}
# 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`:

```json theme={null}
{
  "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`

## Related Endpoints

* [Get Agent](/api/agents/get) - Retrieve current configuration
* [Create Agent](/api/agents/create) - Create a new agent
* [Delete Agent](/api/agents/delete) - Remove an agent
* [List Versions](/api/agents/versions) - View version history