Get Agent

Retrieve detailed information about a specific agent including its configuration and current version

Endpoint

GET /agents/{agent_id}

Authentication

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

Description

Retrieves complete information about a specific agent, including its current version configuration, tools, MCP integrations, and metadata. The agent must belong to the authenticated user.

Path Parameters

agent_id · string · required

The unique identifier (UUID) of the agent to retrieve.

Response

Returns the agent object with full configuration including the current active version.

agent_id · string

Unique identifier for the agent (UUID format)

name · string

Agent name

description · string

Agent description (if set)

system_prompt · string

Current system prompt from active version

model · string

AI model identifier (e.g., “kortix/basic”, “openai/gpt-4”)

icon_name · string

Icon identifier from the icon library

icon_color · string

Icon color in hex format

icon_background · string

Icon background color in hex format

is_default · boolean

Whether this agent is the default for new threads

is_public · boolean

Whether this agent is publicly shared (enterprise feature)

tags · array

Array of tag strings for categorization

current_version_id · string

UUID of the currently active version

version_count · integer

Total number of versions for this agent

current_version · object

Complete configuration of the active version

Show Version Object Fields

version_id · string

Unique version identifier

version_number · integer

Sequential version number (1, 2, 3…)

version_name · string

Human-readable version label (e.g., “v1”, “v2”)

system_prompt · string

System prompt for this version

model · string

AI model for this version

configured_mcps · array

Array of configured MCP integrations

custom_mcps · array

Array of custom MCP server configurations

agentpress_tools · object

Tool enable/disable configuration

is_active · boolean

Whether this version is currently active

created_at · string

ISO 8601 timestamp of version creation

updated_at · string

ISO 8601 timestamp of last version update

created_by · string

User ID who created this version

configured_mcps · array

MCP integrations from current version (flattened for convenience)

custom_mcps · array

Custom MCP servers from current version (flattened for convenience)

agentpress_tools · object

Tool configurations from current version (flattened for convenience)

metadata · object

Additional agent metadata (e.g., is_suna_default, restrictions)

created_at · string

ISO 8601 timestamp when agent was created

updated_at · string

ISO 8601 timestamp of last update

Examples

cURL

curl -X GET https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Research Assistant",
  "description": "Specialized agent for research and analysis tasks",
  "system_prompt": "You are an expert research assistant. Help users find accurate information, analyze sources, and synthesize insights from multiple documents.",
  "model": "kortix/basic",
  "icon_name": "search",
  "icon_color": "#10B981",
  "icon_background": "#D1FAE5",
  "is_default": false,
  "is_public": false,
  "tags": ["research", "analysis"],
  "current_version_id": "660f9511-f3ac-52e5-b827-557766551111",
  "version_count": 3,
  "current_version": {
    "version_id": "660f9511-f3ac-52e5-b827-557766551111",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "version_number": 3,
    "version_name": "v3",
    "system_prompt": "You are an expert research assistant. Help users find accurate information, analyze sources, and synthesize insights from multiple documents.",
    "model": "kortix/basic",
    "configured_mcps": [
      {
        "mcp_id": "brave-search",
        "enabled": true
      }
    ],
    "custom_mcps": [],
    "agentpress_tools": {
      "bash": { "enabled": true },
      "read": { "enabled": true },
      "write": { "enabled": true },
      "edit": { "enabled": true },
      "glob": { "enabled": true },
      "grep": { "enabled": true },
      "web_search": { "enabled": true }
    },
    "is_active": true,
    "created_at": "2025-08-15T14:25:00.000Z",
    "updated_at": "2025-08-15T14:25:00.000Z",
    "created_by": "user_123abc"
  },
  "configured_mcps": [
    {
      "mcp_id": "brave-search",
      "enabled": true
    }
  ],
  "custom_mcps": [],
  "agentpress_tools": {
    "bash": { "enabled": true },
    "read": { "enabled": true },
    "write": { "enabled": true },
    "edit": { "enabled": true },
    "glob": { "enabled": true },
    "grep": { "enabled": true },
    "web_search": { "enabled": true }
  },
  "metadata": {},
  "created_at": "2025-08-14T09:00:00.000Z",
  "updated_at": "2025-08-15T14:25:00.000Z"
}

Error Responses

404 Not Found · error

Agent does not exist or user does not have access

{
  "detail": "Agent not found"
}

401 Unauthorized · error

Missing or invalid authentication token

{
  "detail": "Not authenticated"
}

500 Internal Server Error · error

Server error retrieving agent

{
  "detail": "Failed to fetch agent: <error details>"
}

Use Cases

Inspect Agent Configuration

Retrieve complete configuration before starting a run or making updates:

agent = client.agents.get(agent_id)

# Check what tools are enabled
if agent.agentpress_tools.get('web_search', {}).get('enabled'):
    print("Web search is available")

# Check configured integrations
for mcp in agent.configured_mcps:
    if mcp['enabled']:
        print(f"Integration enabled: {mcp['mcp_id']}")

Version History

Check how many versions exist:

agent = client.agents.get(agent_id)
print(f"This agent has {agent.version_count} versions")
print(f"Currently on: {agent.current_version.version_name}")

Validate Agent Before Run

Ensure agent has required capabilities:

agent = client.agents.get(agent_id)

required_tools = ['bash', 'read', 'write']
for tool in required_tools:
    if not agent.agentpress_tools.get(tool, {}).get('enabled', False):
        raise ValueError(f"Agent missing required tool: {tool}")

print("Agent validated, starting run...")

Notes

• Full Configuration: This endpoint loads the complete agent configuration including the current version
• Flattened Fields: The system_prompt, model, configured_mcps, custom_mcps, and agentpress_tools fields at the top level mirror the current version for convenience
• Version Access: Only the current active version is returned; use the versions API to access historical versions
• Metadata: The metadata field may contain special flags like is_suna_default or restrictions for system agents

Related Endpoints

• List Agents - Get all agents for the authenticated user
• Update Agent - Modify agent configuration
• Delete Agent - Remove an agent
• Create Agent - Create a new agent