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.

# 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/	Get agent details
POST	/api/agents/create	Create new agent
PUT	/api/agents/update/	Update agent
DELETE	/api/agents/delete/	Delete agent
PUT	/api/agents/bulk-update-order	Update agent display order

---

List Agents

Retrieve all agents accessible to the authenticated user.

GET /api/agents/list

Response

{
  "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.

GET /api/agents/detail/{agent_id}

Response

{
  "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.

POST /api/agents/create
Content-Type: application/json

Request Body

{
  "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

{
  "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.

PUT /api/agents/update/{agent_id}
Content-Type: application/json

Request Body

Only include fields you want to update:

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

Response

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

---

Delete Agent

Delete an agent permanently.

DELETE /api/agents/delete/{agent_id}

Response

{
  "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.

PUT /api/agents/bulk-update-order
Content-Type: application/json

Request Body

{
  "agents": [
    { "id": "agent-uuid-1", "order": 1 },
    { "id": "agent-uuid-2", "order": 2 },
    { "id": "agent-uuid-3", "order": 3 }
  ]
}

Response

{
  "success": true,
  "updated_count": 3
}

---

Global Configuration

Configure system-wide agent settings via the Config API.

PUT /api/config/update
Content-Type: application/json

Agent-Related Global Settings

{
  "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

{
  "error": "validation_error",
  "message": "Field 'name' is required",
  "details": {
    "field": "name",
    "code": "required"
  }
}

404 Not Found

{
  "error": "not_found",
  "message": "Agent with ID 'uuid' not found"
}

409 Conflict

{
  "error": "conflict",
  "message": "Agent with name 'support-agent' already exists"
}

---

Related Documentation

• Agents Overview - Agent concepts and configuration
• Send Message API - Send messages to agents
• Agent Permissions - Access control