Skip to main content
Agents in Kortix are autonomous AI workers that can be customized with specific capabilities, tools, and behaviors. This guide shows you how to create agents using both the web interface and API.

​
Overview

Every agent in Kortix consists of:
  • Name and Icon: Visual identification for your agent
  • System Prompt: Instructions that define the agent’s behavior and capabilities
  • Model: The AI model powering the agent (e.g., claude-4.5-sonnet, gpt-4o)
  • Tools: Integrations and capabilities available to the agent
  • Triggers: Automated workflows that start the agent

​
Creating an Agent via UI

1

Open Agent Creation Dialog

Navigate to the Agents page and click Create Worker. You’ll see three options:
  • Configure Manually: Full control over every setting
  • Configure by Chat: Let AI set it up based on your description
  • Explore Templates: Start from a pre-built worker template
2

Choose Your Creation Method

Select Configure Manually to create an agent with default settings that you can customize later.This creates a basic agent with:
  • Default Suna system prompt
  • Your account’s default model
  • Core AgentPress tools enabled
  • No MCP integrations
3

Customize Your Agent

After creation, navigate to the agent’s configuration page to customize:
  • Name & Icon: Update visual branding
  • System Prompt: Define behavior and instructions
  • Model: Choose the AI model
  • Tools: Enable AgentPress tools and MCP integrations
  • Triggers: Set up automated workflows

​
Creating an Agent via API

Use the /agents endpoint to programmatically create agents. 
import requests

url = "https://api.kortix.com/agents"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "name": "Sales Assistant",
    "icon_name": "user-check",
    "icon_color": "#3B82F6",
    "icon_background": "#EFF6FF",
    "is_default": False
}

response = requests.post(url, json=payload, headers=headers)
agent = response.json()

print(f"Created agent: {agent['agent_id']}")
print(f"Version: {agent['current_version']['version_name']}")

​
API Response

The API returns a complete agent object with initial version: 
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Sales Assistant",
  "account_id": "user-123",
  "icon_name": "user-check",
  "icon_color": "#3B82F6",
  "icon_background": "#EFF6FF",
  "is_default": false,
  "current_version_id": "ver-001",
  "version_count": 1,
  "current_version": {
    "version_id": "ver-001",
    "version_number": 1,
    "version_name": "v1",
    "system_prompt": "You are Kortix, an autonomous AI Worker...",
    "model": "kortix/basic",
    "agentpress_tools": {
      "sb_files_tool": { "enabled": true },
      "sb_shell_tool": { "enabled": true },
      "message_tool": { "enabled": true }
    },
    "configured_mcps": [],
    "custom_mcps": []
  },
  "created_at": "2024-01-15T10:30:00Z"
}

​
Updating Agent Configuration

Update agent properties using the PUT /agents/{agent_id} endpoint: 
import requests

agent_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://api.kortix.com/agents/{agent_id}"

payload = {
    "name": "Senior Sales Assistant",
    "is_default": True,
    "system_prompt": "You are a sales expert focused on B2B SaaS deals...",
    "model": "anthropic/claude-4.5-sonnet",
    "agentpress_tools": {
        "sb_files_tool": { "enabled": True },
        "web_search_tool": { "enabled": True },
        "message_tool": { "enabled": True }
    }
}

response = requests.put(url, json=payload, headers=headers)
updated_agent = response.json()

print(f"Updated to version: {updated_agent['current_version']['version_name']}")
Version Control: Configuration changes (system prompt, model, tools) automatically create new versions. Metadata changes (name, icon) update the agent without creating versions.

​
Agent Limits

Agent creation is subject to subscription tier limits:
TierAgent Limit
Free3 agents
Pro10 agents
Team50 agents
EnterpriseUnlimited

​
Handling Limit Errors

When you reach your agent limit, the API returns a 402 status: 
{
  "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"
  }
}

​
Default Agents

Set an agent as default to use it automatically in new conversations: 
response = requests.put(
    f"https://api.kortix.com/agents/{agent_id}",
    json={"is_default": True},
    headers=headers
)
Setting an agent as default automatically clears the default flag from other agents.

​
Next Steps

Agent Builder UI

Configure agents using the visual interface

System Prompts

Write effective system prompts

Workflows

Set up automated triggers

API Reference

Full API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us