> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kortix-ai/suna/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="agent_id" type="string" required>
  The unique identifier (UUID) of the agent to retrieve.
</ParamField>

## Response

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

<ResponseField name="agent_id" type="string">
  Unique identifier for the agent (UUID format)
</ResponseField>

<ResponseField name="name" type="string">
  Agent name
</ResponseField>

<ResponseField name="description" type="string" optional>
  Agent description (if set)
</ResponseField>

<ResponseField name="system_prompt" type="string">
  Current system prompt from active version
</ResponseField>

<ResponseField name="model" type="string">
  AI model identifier (e.g., "kortix/basic", "openai/gpt-4")
</ResponseField>

<ResponseField name="icon_name" type="string">
  Icon identifier from the icon library
</ResponseField>

<ResponseField name="icon_color" type="string">
  Icon color in hex format
</ResponseField>

<ResponseField name="icon_background" type="string">
  Icon background color in hex format
</ResponseField>

<ResponseField name="is_default" type="boolean">
  Whether this agent is the default for new threads
</ResponseField>

<ResponseField name="is_public" type="boolean">
  Whether this agent is publicly shared (enterprise feature)
</ResponseField>

<ResponseField name="tags" type="array">
  Array of tag strings for categorization
</ResponseField>

<ResponseField name="current_version_id" type="string">
  UUID of the currently active version
</ResponseField>

<ResponseField name="version_count" type="integer">
  Total number of versions for this agent
</ResponseField>

<ResponseField name="current_version" type="object">
  Complete configuration of the active version

  <Expandable title="Version Object Fields">
    <ResponseField name="version_id" type="string">
      Unique version identifier
    </ResponseField>

    <ResponseField name="version_number" type="integer">
      Sequential version number (1, 2, 3...)
    </ResponseField>

    <ResponseField name="version_name" type="string">
      Human-readable version label (e.g., "v1", "v2")
    </ResponseField>

    <ResponseField name="system_prompt" type="string">
      System prompt for this version
    </ResponseField>

    <ResponseField name="model" type="string">
      AI model for this version
    </ResponseField>

    <ResponseField name="configured_mcps" type="array">
      Array of configured MCP integrations
    </ResponseField>

    <ResponseField name="custom_mcps" type="array">
      Array of custom MCP server configurations
    </ResponseField>

    <ResponseField name="agentpress_tools" type="object">
      Tool enable/disable configuration
    </ResponseField>

    <ResponseField name="is_active" type="boolean">
      Whether this version is currently active
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of version creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last version update
    </ResponseField>

    <ResponseField name="created_by" type="string">
      User ID who created this version
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="configured_mcps" type="array">
  MCP integrations from current version (flattened for convenience)
</ResponseField>

<ResponseField name="custom_mcps" type="array">
  Custom MCP servers from current version (flattened for convenience)
</ResponseField>

<ResponseField name="agentpress_tools" type="object">
  Tool configurations from current version (flattened for convenience)
</ResponseField>

<ResponseField name="metadata" type="object" optional>
  Additional agent metadata (e.g., `is_suna_default`, `restrictions`)
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when agent was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of last update
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python SDK theme={null}
  from kortix import Kortix

  client = Kortix(api_key="YOUR_API_KEY")

  agent = client.agents.get("550e8400-e29b-41d4-a716-446655440000")

  print(f"Agent: {agent.name}")
  print(f"Model: {agent.model}")
  print(f"Version: {agent.current_version.version_name}")
  print(f"Tools enabled: {agent.agentpress_tools.keys()}")
  ```

  ```typescript TypeScript SDK theme={null}
  import { Kortix } from '@kortix/sdk';

  const client = new Kortix({ apiKey: 'YOUR_API_KEY' });

  const agent = await client.agents.get('550e8400-e29b-41d4-a716-446655440000');

  console.log(`Agent: ${agent.name}`);
  console.log(`Model: ${agent.model}`);
  console.log(`Version: ${agent.currentVersion.versionName}`);
  console.log(`Has web search: ${agent.agentpressTools.web_search?.enabled}`);
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.get(
    'https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000',
    {
      headers: {
        'Authorization': `Bearer ${process.env.KORTIX_API_KEY}`,
      },
    }
  );

  const agent = response.data;
  console.log('Agent:', agent.name);
  console.log('Versions:', agent.version_count);
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "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

<ResponseField name="404 Not Found" type="error">
  Agent does not exist or user does not have access

  ```json theme={null}
  {
    "detail": "Agent not found"
  }
  ```
</ResponseField>

<ResponseField name="401 Unauthorized" type="error">
  Missing or invalid authentication token

  ```json theme={null}
  {
    "detail": "Not authenticated"
  }
  ```
</ResponseField>

<ResponseField name="500 Internal Server Error" type="error">
  Server error retrieving agent

  ```json theme={null}
  {
    "detail": "Failed to fetch agent: <error details>"
  }
  ```
</ResponseField>

## Use Cases

### Inspect Agent Configuration

Retrieve complete configuration before starting a run or making updates:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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](/api/agents/list) - Get all agents for the authenticated user
* [Update Agent](/api/agents/update) - Modify agent configuration
* [Delete Agent](/api/agents/delete) - Remove an agent
* [Create Agent](/api/agents/create) - Create a new agent