Agent Builder UI

The Agent Builder provides a comprehensive interface for configuring every aspect of your AI agents, from system prompts to integrations.

Accessing the Agent Builder

Navigate to an agent’s configuration page:

Go to Agents in the sidebar
Click on any agent card
Click Configure or navigate to /agents/config/{agent_id}

Configuration Sections

Basic Settings

Name & Icon
Default Agent
Model Selection

Customize your agent’s visual identity:Agent Name

Click the agent name to edit
Name appears in the UI and API responses
Best practice: Use descriptive, role-based names (e.g., “Sales Assistant”, “Code Reviewer”)

Icon & ColorsClick the icon to customize:

Icon: Choose from Lucide icon library
Icon Color: Foreground color for the icon
Background Color: Background color of the icon container

// Example: Generate icon programmatically
const result = await generateAgentIcon({ name: "Data Analyst" });
// Returns: { icon_name: "chart-bar", icon_color: "#3B82F6", icon_background: "#EFF6FF" }

Choose the AI model powering your agent:Available Models

kortix/basic - Claude 4.5 Sonnet (default for Pro+ users)
kortix/minimax - Fast, efficient model (default for Free tier)
anthropic/claude-4.5-sonnet - Latest Claude model
openai/gpt-4o - OpenAI’s most capable model
openai/o3-mini - Fast reasoning model

Model Selection via API

requests.put(
    f"https://api.kortix.com/agents/{agent_id}",
    json={"model": "anthropic/claude-4.5-sonnet"},
    headers=headers
)

Model availability depends on your subscription tier. Attempting to use unavailable models returns a 402 MODEL_ACCESS_DENIED error.

System Prompt Configuration

The system prompt defines your agent’s behavior, personality, and capabilities. See System Prompts for detailed guidance. Quick Access

Click Edit System Prompt in the agent builder
Use markdown formatting for structured instructions
Test changes immediately by starting a conversation

Tool Configuration

AgentPress Tools
MCP Integrations
Custom MCPs

Built-in tools that are always available:Core Tools (Always enabled)

message_tool: Communication with users (ask, complete)
task_tool: Task management and planning

File Operations

sb_files_tool: Create, edit, and delete files
sb_file_reader_tool: Read and search file contents

Execution & Research

sb_shell_tool: Execute terminal commands
web_search_tool: Search the internet
browser_tool: Navigate and interact with websites

Specialized Tools

sb_vision_tool: Analyze images
sb_presentation_tool: Create presentations
sb_canvas_tool: Design and visual tools
people_search_tool: Find information about people
company_search_tool: Research companies

Enable/Disable Tools

agentpress_tools = {
    "sb_files_tool": {"enabled": True},
    "web_search_tool": {"enabled": True},
    "browser_tool": {"enabled": False}
}

requests.put(
    f"https://api.kortix.com/agents/{agent_id}",
    json={"agentpress_tools": agentpress_tools},
    headers=headers
)

Connect external services using the Model Context Protocol:Pre-configured MCPsAvailable integrations:

Gmail
Google Drive
Slack
GitHub
Linear
Notion
And more…

Add MCP Integration

Click Add Integration in the Tools section
Select the service (e.g., Gmail)
Authenticate if required
Select which tools to enable

Configure via API

configured_mcps = [
    {
        "name": "gmail",
        "type": "mcp",
        "enabledTools": [
            "GMAIL_SEND_EMAIL",
            "GMAIL_SEARCH_EMAILS"
        ]
    }
]

requests.put(
    f"https://api.kortix.com/agents/{agent_id}",
    json={"configured_mcps": configured_mcps},
    headers=headers
)

Connect to your own MCP servers:Supported Protocols

SSE (Server-Sent Events)
WebSocket
Composio integrations

Add Custom MCP

Get Server Details

Obtain your MCP server URL and type:

# Example MCP server
https://your-mcp-server.com/api/mcp

Discover Available Tools

response = requests.get(
    f"https://api.kortix.com/agents/{agent_id}/custom-mcp-tools",
    headers={
        **headers,
        "X-MCP-URL": "https://your-mcp-server.com/api/mcp",
        "X-MCP-Type": "sse"
    }
)
tools = response.json()["tools"]
# [{"name": "custom_tool", "description": "...", "enabled": false}, ...]

Enable Tools

custom_mcps = [{
    "name": "My Custom MCP",
    "customType": "sse",
    "type": "sse",
    "config": {
        "url": "https://your-mcp-server.com/api/mcp"
    },
    "enabledTools": ["custom_tool_1", "custom_tool_2"]
}]

requests.put(
    f"https://api.kortix.com/agents/{agent_id}",
    json={"custom_mcps": custom_mcps},
    headers=headers
)

Custom MCP limits depend on your subscription tier. Free tier: 0, Pro: 3, Team: 10, Enterprise: Unlimited.

Version Management

Agent configurations are automatically versioned:

Automatic Versioning

Changes to these fields create new versions:

System prompt
Model
AgentPress tools
MCP integrations (configured_mcps, custom_mcps)

Changes to these fields do NOT create versions:

Name
Icon and colors
Default status

View Version History

response = requests.get(
    f"https://api.kortix.com/agents/{agent_id}/versions",
    headers=headers
)
versions = response.json()["versions"]

for version in versions:
    print(f"v{version['version_number']}: {version['version_name']}")
    print(f"  Created: {version['created_at']}")
    print(f"  Model: {version['model']}")

Switch Between Versions

# Set active version
requests.put(
    f"https://api.kortix.com/agents/{agent_id}/versions/{version_id}/activate",
    headers=headers
)

Switching versions changes the agent’s behavior for all new conversations. Existing conversations continue using their original version.

Keyboard Shortcuts

Speed up your workflow with keyboard shortcuts:

Shortcut	Action
`Cmd/Ctrl + S`	Save changes
`Cmd/Ctrl + K`	Open command palette
`Esc`	Close dialogs

Configuration Best Practices

Tool Selection Strategy

Enable only the tools your agent needs:

Start minimal: Begin with core tools only
Add iteratively: Enable tools as you discover needs
Test thoroughly: Verify each tool works as expected
Monitor usage: Check which tools are actually used

Too many tools can:

Slow down agent decision-making
Increase token usage
Create unexpected behaviors

Model Selection

Choose models based on use case:

Complex reasoning: claude-4.5-sonnet, gpt-4o
Fast responses: kortix/minimax, o3-mini
Vision tasks: Models with vision support
Cost optimization: Balance performance vs. cost

Naming Conventions

Use clear, descriptive names:

Good: “Customer Support Agent”, “Code Review Bot”
Bad: “Agent 1”, “My Worker”
Include role or function in the name
Use consistent naming across similar agents

Troubleshooting

Agent Not Responding

Check that required tools are enabled
Verify MCP integrations are authenticated
Review system prompt for conflicting instructions
Check subscription tier for model access

Tool Errors

# Get agent tools and their status
response = requests.get(
    f"https://api.kortix.com/agents/{agent_id}/tools",
    headers=headers
)

for tool in response.json()["agentpress_tools"]:
    print(f"{tool['name']}: {'enabled' if tool['enabled'] else 'disabled'}")

Version Conflicts

If configuration changes aren’t reflecting:

Verify the current version is active
Check for pending changes
Review version history for recent updates
Clear cache and reload

Next Steps

System Prompts

Learn to write effective system prompts

Workflows & Triggers

Automate your agents with triggers

Get Started

Core Concepts

Building Agents

Agent Capabilities

Tools & Extensions

Platform Features

Self-Hosting

Agent Builder UI

Accessing the Agent Builder

Configuration Sections

Basic Settings

System Prompt Configuration

Tool Configuration

Version Management

Automatic Versioning

View Version History

Switch Between Versions

Keyboard Shortcuts

Configuration Best Practices

Troubleshooting

Agent Not Responding

Tool Errors

Version Conflicts

Next Steps

System Prompts

Workflows & Triggers

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Agents

Agent Capabilities

Tools & Extensions

Platform Features

Self-Hosting

​Accessing the Agent Builder

​Configuration Sections

​Basic Settings

​System Prompt Configuration

​Tool Configuration

​Version Management

​Automatic Versioning

​View Version History

​Switch Between Versions

​Keyboard Shortcuts

​Configuration Best Practices

​Troubleshooting

​Agent Not Responding

​Tool Errors

​Version Conflicts

​Next Steps

System Prompts

Workflows & Triggers

Build docs developers (and LLMs) love

Accessing the Agent Builder

Configuration Sections

Basic Settings

System Prompt Configuration

Tool Configuration

Version Management

Automatic Versioning

View Version History

Switch Between Versions

Keyboard Shortcuts

Configuration Best Practices

Troubleshooting

Agent Not Responding

Tool Errors

Version Conflicts

Next Steps