Creating Agents

Learn how to create and configure AI agents in Kortix using the UI or API

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

   Manual Configuration

   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

   Chat-Based Setup

   Select Configure by Chat and describe what your agent should do:

   A worker that monitors competitor prices and sends me daily reports
   

   The AI will automatically:

   • Generate an appropriate name
   • Create a tailored system prompt
   • Enable relevant tools
   • Configure necessary integrations

   Template Installation

   Browse the template marketplace and install a pre-configured agent:

   1. Click Explore Templates
   2. Browse Kortix team templates or community templates
   3. Click on a template to preview
   4. Click Install to add it to your workspace
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.

Python

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:

Python

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:

Tier	Agent Limit
Free	3 agents
Pro	10 agents
Team	50 agents
Enterprise	Unlimited

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