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

# Agents API

> Create, update, and configure AI agents via REST API

Programmatically manage AI agents in AGO. Create, update, delete, and configure agents via REST API.

## Authentication

All endpoints require authentication via API key or JWT token.

```bash theme={null}
# API Key authentication
-H "X-API-Key: your-api-key"

# JWT authentication
-H "Authorization: Bearer your-jwt-token"
```

***

## Endpoints Overview

| Method | Endpoint                      | Description                |
| ------ | ----------------------------- | -------------------------- |
| GET    | /api/agents/list              | List all agents            |
| GET    | /api/agents/detail/{id}       | Get agent details          |
| POST   | /api/agents/create            | Create new agent           |
| PUT    | /api/agents/update/{id}       | Update agent               |
| DELETE | /api/agents/delete/{id}       | Delete agent               |
| PUT    | /api/agents/bulk-update-order | Update agent display order |

***

## List Agents

Retrieve all agents accessible to the authenticated user.

```bash theme={null}
GET /api/agents/list
```

### Response

```json theme={null}
{
  "agents": [
    {
      "id": "uuid",
      "name": "support-agent",
      "display_name": "Customer Support",
      "status": "active",
      "icon": "🤖",
      "order": 1,
      "is_background_agent": false,
      "is_reasoning_agent": false
    }
  ]
}
```

***

## Get Agent Details

Retrieve full details for a specific agent.

```bash theme={null}
GET /api/agents/detail/{agent_id}
```

### Response

```json theme={null}
{
  "id": "uuid",
  "name": "support-agent",
  "display_name": "Customer Support",
  "status": "active",
  "icon": "🤖",
  "custom_icon_id": null,
  "order": 1,
  "prompt_template_id": "uuid",
  "custom_llm_id": null,
  "custom_llm_temperature": null,
  "custom_llm_top_p": null,
  "sources": ["source-uuid-1", "source-uuid-2"],
  "tools": ["tool-uuid-1"],
  "agent_tools": [],
  "pinned_documents": [],
  "number_docs_to_retrieve": 8,
  "number_docs_to_display": 8,
  "reranker_activated": true,
  "is_background_agent": false,
  "is_reasoning_agent": false,
  "reasoning_iterations": 1,
  "can_be_used_as_tool": false,
  "tool_description": null,
  "share_conversation_context": false,
  "max_call_depth": 5,
  "satisfaction_feedback_activated": true,
  "satisfaction_feedback_question": "Was this helpful?",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:15:00Z"
}
```

***

## Create Agent

Create a new agent with specified configuration.

```bash theme={null}
POST /api/agents/create
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "name": "billing-agent",
  "display_name": "Billing Support",
  "icon": "💰",
  "prompt_template_id": "template-uuid",
  "sources": ["source-uuid-1"],
  "tools": ["ticketing-tool-uuid"],
  "number_docs_to_retrieve": 10,
  "reranker_activated": true
}
```

### Required Fields

| Field                | Type   | Description                |
| -------------------- | ------ | -------------------------- |
| name                 | string | Unique internal identifier |
| prompt\_template\_id | UUID   | Associated prompt template |

### Optional Fields

| Field                                | Type    | Default  | Description                       |
| ------------------------------------ | ------- | -------- | --------------------------------- |
| display\_name                        | string  | null     | User-facing name                  |
| icon                                 | string  | null     | Emoji icon                        |
| custom\_icon\_id                     | UUID    | null     | Custom uploaded icon              |
| status                               | string  | "active" | Agent status                      |
| order                                | integer | null     | Display order                     |
| custom\_llm\_id                      | UUID    | null     | Override LLM model                |
| custom\_llm\_temperature             | float   | null     | LLM temperature (0.0-2.0)         |
| custom\_llm\_top\_p                  | float   | null     | Nucleus sampling (0.0-1.0)        |
| sources                              | UUID\[] | \[]      | Knowledge sources                 |
| tools                                | UUID\[] | \[]      | Assigned tools                    |
| agent\_tools                         | UUID\[] | \[]      | Agents to invoke as tools         |
| pinned\_documents                    | UUID\[] | \[]      | Always-included documents         |
| number\_docs\_to\_retrieve           | integer | 8        | Documents for context             |
| number\_docs\_to\_display            | integer | 8        | Documents shown to user           |
| reranker\_activated                  | boolean | null     | Enable reranking                  |
| is\_background\_agent                | boolean | false    | Async processing                  |
| is\_reasoning\_agent                 | boolean | false    | Extended reasoning                |
| reasoning\_iterations                | integer | 1        | Reasoning cycles                  |
| can\_be\_used\_as\_tool              | boolean | false    | Allow invocation by other agents  |
| tool\_description                    | string  | null     | Description when used as tool     |
| share\_conversation\_context         | boolean | false    | Share context with invoking agent |
| max\_call\_depth                     | integer | 5        | Max nesting depth                 |
| satisfaction\_feedback\_activated    | boolean | false    | Enable feedback                   |
| satisfaction\_feedback\_question     | string  | ""       | Feedback question                 |
| satisfaction\_feedback\_helper\_text | string  | ""       | Helper text                       |
| satisfaction\_feedback\_no\_action   | string  | null     | Negative feedback action          |

### Response

```json theme={null}
{
  "id": "new-agent-uuid",
  "name": "billing-agent",
  "display_name": "Billing Support",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}
```

***

## Update Agent

Update an existing agent's configuration.

```bash theme={null}
PUT /api/agents/update/{agent_id}
Content-Type: application/json
```

### Request Body

Only include fields you want to update:

```json theme={null}
{
  "display_name": "Updated Name",
  "custom_llm_temperature": 0.5,
  "tools": ["tool-uuid-1", "tool-uuid-2"],
  "reranker_activated": true
}
```

### Response

```json theme={null}
{
  "id": "agent-uuid",
  "name": "billing-agent",
  "display_name": "Updated Name",
  "updated_at": "2024-01-20T14:15:00Z"
}
```

***

## Delete Agent

Delete an agent permanently.

```bash theme={null}
DELETE /api/agents/delete/{agent_id}
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Agent deleted successfully"
}
```

> **Warning**: Deleting an agent is permanent. Associated conversations remain but can no longer continue.

***

## Bulk Update Order

Update the display order of multiple agents at once.

```bash theme={null}
PUT /api/agents/bulk-update-order
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "agents": [
    { "id": "agent-uuid-1", "order": 1 },
    { "id": "agent-uuid-2", "order": 2 },
    { "id": "agent-uuid-3", "order": 3 }
  ]
}
```

### Response

```json theme={null}
{
  "success": true,
  "updated_count": 3
}
```

***

## Global Configuration

Configure system-wide agent settings via the Config API.

```bash theme={null}
PUT /api/config/update
Content-Type: application/json
```

### Agent-Related Global Settings

```json theme={null}
{
  "add_ask_human_tool_for_all_agents": true,
  "description_ask_human_tool": "Use this tool to escalate...",
  "question_similarity_threshold": 0.85,
  "file_attachments_enabled": true,
  "reranker_activated": true
}
```

| Field                                   | Type    | Default   | Description             |
| --------------------------------------- | ------- | --------- | ----------------------- |
| add\_ask\_human\_tool\_for\_all\_agents | boolean | true      | Auto-add ticketing tool |
| description\_ask\_human\_tool           | text    | (default) | Ticketing tool prompt   |
| question\_similarity\_threshold         | float   | 0.85      | FAQ matching threshold  |
| file\_attachments\_enabled              | boolean | false     | Allow file uploads      |
| reranker\_activated                     | boolean | false     | Global reranker setting |

***

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": "validation_error",
  "message": "Field 'name' is required",
  "details": {
    "field": "name",
    "code": "required"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "error": "not_found",
  "message": "Agent with ID 'uuid' not found"
}
```

### 409 Conflict

```json theme={null}
{
  "error": "conflict",
  "message": "Agent with name 'support-agent' already exists"
}
```

***

## Related Documentation

* [Agents Overview](../agent/agents) - Agent concepts and configuration
* [Send Message API](./send-message-api) - Send messages to agents
* [Agent Permissions](../users/agent-permissions) - Access control