Skip to main content

​
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
​
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 -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

Build docs developers (and LLMs) love

Get started for freeTalk to us