#Agents API

Manage your AI Agents: create, view, update, and delete.

Base Path: /v1/agents

#List Agents

GET /v1/agents

#Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number, default 1
`limit`	number	No	Items per page, default 20, max 100
`projectId`	string	No	Filter by project ID
`status`	string	No	Filter by status

#Response

json{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Customer Service Assistant",
      "description": "Intelligent customer service bot",
      "model": "zhipu/glm-4",
      "systemPrompt": "You are a friendly customer service assistant.",
      "settings": {},
      "organizationId": "org_xxx",
      "projectId": "proj_xxx",
      "createdAt": "2026-01-15T08:00:00Z",
      "updatedAt": "2026-01-15T08:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

#Get Agent Details

GET /v1/agents/:agentId

#Path Parameters

Parameter	Type	Description
`agentId`	string	Agent ID

#Response

Returns a single Agent object.

#Create Agent

POST /v1/agents

Required Permission: agents:create (admin or user role)

Note: Creating an Agent requires a Project context. Ensure the API Key is bound to a Project or specify one via the X-Project-Id request header.

#Request Body

json{
  "name": "My Assistant",
  "description": "A general-purpose AI assistant",
  "systemPrompt": "You are a professional AI assistant skilled at answering user questions.",
  "model": "zhipu/glm-4",
  "settings": {
    "temperature": 0.7,
    "maxTokens": 2048,
    "toolsEnabled": true,
    "allowedToolCategories": ["web-search", "fetch-url"],
    "knowledgeBaseIds": ["kb_abc123"],
    "contextWindowSize": 20
  }
}

Field	Type	Required	Description
`name`	string	Yes	Agent name
`description`	string	No	Description
`systemPrompt`	string	No	System prompt
`model`	string	Yes	Model identifier (format: `provider/model`)
`settings`	object	No	Agent configuration

#Settings Field Description

Field	Type	Description
`temperature`	number	Generation temperature, 0-2
`maxTokens`	number	Maximum output tokens
`toolsEnabled`	boolean	Whether to enable tool calling
`allowedToolCategories`	string[]	Allowed tool categories
`knowledgeBaseIds`	string[]	Associated knowledge base ID list
`contextWindowSize`	number	Context window size (number of messages), default 20
`customToolIds`	string[]	Custom tool ID list

#Response

HTTP 201 Created

Returns the created Agent object.

#Update Agent

PATCH /v1/agents/:agentId

Required Permission: agents:update (admin or user role)

#Request Body

All fields are optional -- only include the fields you want to update:

json{
  "name": "Updated Name",
  "settings": {
    "toolsEnabled": true,
    "allowedToolCategories": ["web-search"]
  }
}

#Response

Returns the updated Agent object.

#Delete Agent

DELETE /v1/agents/:agentId

Required Permission: agents:delete (admin or user role)

#Response

json{
  "id": "agent_abc123",
  "deleted": true
}