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

# Create Agent

> Create a new AI agent with custom configuration, tools, and integrations

## Endpoint

```
POST /agents
```

## Authentication

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

## Description

Creates a new AI agent with a custom name, icon, and initial configuration version. The agent is initialized with default tools and system prompt, which can be customized immediately or later via the update endpoint.

## Limits

Agent creation is subject to tier-based limits:

* **Free tier**: 3 agents maximum
* **Pro tier**: 10 agents maximum
* **Enterprise tier**: Unlimited agents

Exceeding the limit returns a `402` error with code `AGENT_LIMIT_EXCEEDED`.

## Request Body

<ParamField body="name" type="string" required>
  Agent name (2-100 characters). Used for identification in the UI.
</ParamField>

<ParamField body="is_default" type="boolean" default={false}>
  Whether this agent should be the default for new threads. Only one agent can be default per account.
</ParamField>

<ParamField body="icon_name" type="string" default="bot">
  Icon identifier from the icon library (e.g., "bot", "code", "brain", "sparkles").
</ParamField>

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

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

<ParamField body="system_prompt" type="string">
  Custom system prompt for the agent. If not provided, uses default Suna configuration.
</ParamField>

<ParamField body="configured_mcps" type="array" default={[]}>
  Array of configured MCP (Model Context Protocol) integrations.

  <Expandable title="MCP Configuration Object">
    <ResponseField name="mcp_id" type="string">
      ID of the MCP server configuration
    </ResponseField>

    <ResponseField name="enabled" type="boolean">
      Whether this MCP is enabled
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="custom_mcps" type="array" default={[]}>
  Array of custom MCP server configurations.

  <Expandable title="Custom MCP Object">
    <ResponseField name="name" type="string">
      Name of the custom MCP server
    </ResponseField>

    <ResponseField name="command" type="string">
      Command to start the MCP server
    </ResponseField>

    <ResponseField name="args" type="array">
      Command line arguments
    </ResponseField>

    <ResponseField name="env" type="object">
      Environment variables
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="agentpress_tools" type="object" default={{}}>
  Tool configurations. Core tools (bash, read, write, edit, glob, grep) are automatically enabled.

  <Expandable title="Tool Configuration Structure">
    ```json theme={null}
    {
      "bash": { "enabled": true },
      "read": { "enabled": true },
      "write": { "enabled": true },
      "edit": { "enabled": true },
      "glob": { "enabled": true },
      "grep": { "enabled": true },
      "web_search": { "enabled": false }
    }
    ```
  </Expandable>
</ParamField>

## Response

Returns the created agent with full configuration including the initial version (v1).

<ResponseField name="agent_id" type="string">
  Unique identifier for the agent (UUID format)
</ResponseField>

<ResponseField name="name" type="string">
  Agent name
</ResponseField>

<ResponseField name="description" type="string" optional>
  Agent description
</ResponseField>

<ResponseField name="icon_name" type="string">
  Icon identifier
</ResponseField>

<ResponseField name="icon_color" type="string">
  Icon color in hex format
</ResponseField>

<ResponseField name="icon_background" type="string">
  Icon background color in hex format
</ResponseField>

<ResponseField name="is_default" type="boolean">
  Whether this is the default agent
</ResponseField>

<ResponseField name="current_version_id" type="string">
  ID of the current active version
</ResponseField>

<ResponseField name="version_count" type="integer">
  Total number of versions (starts at 1)
</ResponseField>

<ResponseField name="current_version" type="object">
  Full version configuration object

  <Expandable title="Version Object">
    <ResponseField name="version_id" type="string">
      Version UUID
    </ResponseField>

    <ResponseField name="version_number" type="integer">
      Sequential version number (1, 2, 3...)
    </ResponseField>

    <ResponseField name="version_name" type="string">
      Version label (e.g., "v1", "v2")
    </ResponseField>

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

    <ResponseField name="model" type="string">
      AI model identifier (e.g., "kortix/basic")
    </ResponseField>

    <ResponseField name="configured_mcps" type="array">
      Configured MCP integrations
    </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
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.kortix.ai/agents \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Code Assistant",
      "icon_name": "code",
      "icon_color": "#6366F1",
      "icon_background": "#EEF2FF",
      "is_default": false
    }'
  ```

  ```python Python SDK theme={null}
  from kortix import Kortix

  client = Kortix(api_key="YOUR_API_KEY")

  agent = client.agents.create(
      name="Code Assistant",
      icon_name="code",
      icon_color="#6366F1",
      icon_background="#EEF2FF",
      is_default=False
  )

  print(f"Created agent: {agent.agent_id}")
  print(f"Version: {agent.current_version.version_name}")
  ```

  ```typescript TypeScript SDK theme={null}
  import { Kortix } from '@kortix/sdk';

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

  const agent = await client.agents.create({
    name: 'Code Assistant',
    iconName: 'code',
    iconColor: '#6366F1',
    iconBackground: '#EEF2FF',
    isDefault: false,
  });

  console.log(`Created agent: ${agent.agentId}`);
  console.log(`Version: ${agent.currentVersion.versionName}`);
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.post(
    'https://api.kortix.ai/agents',
    {
      name: 'Code Assistant',
      icon_name: 'code',
      icon_color: '#6366F1',
      icon_background: '#EEF2FF',
      is_default: false,
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.KORTIX_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );

  const agent = response.data;
  console.log('Agent created:', agent.agent_id);
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Code Assistant",
  "description": null,
  "icon_name": "code",
  "icon_color": "#6366F1",
  "icon_background": "#EEF2FF",
  "is_default": false,
  "is_public": false,
  "tags": [],
  "current_version_id": "660f9511-f3ac-52e5-b827-557766551111",
  "version_count": 1,
  "current_version": {
    "version_id": "660f9511-f3ac-52e5-b827-557766551111",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "version_number": 1,
    "version_name": "v1",
    "system_prompt": "You are an expert coding assistant. Help users write clean, efficient code and debug issues.",
    "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-15T10:30:00.000Z",
    "updated_at": "2025-08-15T10:30:00.000Z"
  },
  "configured_mcps": [],
  "custom_mcps": [],
  "agentpress_tools": {
    "bash": { "enabled": true },
    "read": { "enabled": true },
    "write": { "enabled": true },
    "edit": { "enabled": true },
    "glob": { "enabled": true },
    "grep": { "enabled": true }
  },
  "created_at": "2025-08-15T10:30:00.000Z",
  "updated_at": "2025-08-15T10:30:00.000Z"
}
```

## Error Responses

<ResponseField name="402 Payment Required" type="error">
  Agent limit exceeded for current tier

  ```json theme={null}
  {
    "detail": {
      "message": "Maximum of 3 agents allowed for your current plan. You have 3 agents.",
      "current_count": 3,
      "limit": 3,
      "tier_name": "free",
      "error_code": "AGENT_LIMIT_EXCEEDED"
    }
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Invalid request data (e.g., missing name, invalid icon)

  ```json theme={null}
  {
    "detail": "Agent name is required"
  }
  ```
</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 agent creation

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

## Notes

* **Default Agent**: Setting `is_default: true` automatically unsets any existing default agent
* **Versioning**: Every agent starts with version v1, which is automatically created
* **Core Tools**: The core tools (bash, read, write, edit, glob, grep) are always enabled and cannot be disabled
* **Icon Library**: Use the `/agents/generate-icon` endpoint to get AI-suggested icons based on agent name
* **Cache**: Creating an agent invalidates the agent count cache for the user

## Related Endpoints

* [Update Agent](/api/agents/update) - Modify agent configuration
* [Get Agent](/api/agents/get) - Retrieve agent details
* [Delete Agent](/api/agents/delete) - Remove an agent
* [Run Agent](/api/agents/run) - Start an agent run