#Agents API

管理你的 AI Agent：创建、查看、更新和删除。

基础路径: /v1/agents

#列出 Agent

GET /v1/agents

#查询参数

参数	类型	必填	说明
`page`	number	否	页码，默认 1
`limit`	number	否	每页条数，默认 20，最大 100
`projectId`	string	否	按项目 ID 筛选
`status`	string	否	按状态筛选

#响应

json{
  "data": [
    {
      "id": "agent_abc123",
      "name": "客服助手",
      "description": "智能客服机器人",
      "model": "zhipu/glm-4",
      "systemPrompt": "你是一个友善的客服助手。",
      "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
  }
}

#获取 Agent 详情

GET /v1/agents/:agentId

#路径参数

参数	类型	说明
`agentId`	string	Agent ID

#响应

返回单个 Agent 对象。

#创建 Agent

POST /v1/agents

所需权限: agents:create（admin 或 user 角色）

注意：创建 Agent 需要 Project 上下文。确保 API Key 已关联 Project 或通过 X-Project-Id 请求头指定。

#请求体

json{
  "name": "我的助手",
  "description": "一个通用 AI 助手",
  "systemPrompt": "你是一个专业的 AI 助手，擅长回答用户问题。",
  "model": "zhipu/glm-4",
  "settings": {
    "temperature": 0.7,
    "maxTokens": 2048,
    "toolsEnabled": true,
    "allowedToolCategories": ["web-search", "fetch-url"],
    "knowledgeBaseIds": ["kb_abc123"],
    "contextWindowSize": 20
  }
}

字段	类型	必填	说明
`name`	string	是	Agent 名称
`description`	string	否	描述
`systemPrompt`	string	否	系统提示词
`model`	string	是	模型标识（格式：`provider/model`）
`settings`	object	否	Agent 配置

#Settings 字段说明

字段	类型	说明
`temperature`	number	生成温度，0-2
`maxTokens`	number	最大输出 token 数
`toolsEnabled`	boolean	是否启用工具调用
`allowedToolCategories`	string[]	允许的工具类别
`knowledgeBaseIds`	string[]	关联的知识库 ID 列表
`contextWindowSize`	number	上下文窗口大小（消息数），默认 20
`customToolIds`	string[]	自定义工具 ID 列表

#响应

HTTP 201 Created

返回创建的 Agent 对象。

#更新 Agent

PATCH /v1/agents/:agentId

所需权限: agents:update（admin 或 user 角色）

#请求体

所有字段均为可选，只需传入需要更新的字段：

json{
  "name": "更新后的名称",
  "settings": {
    "toolsEnabled": true,
    "allowedToolCategories": ["web-search"]
  }
}

#响应

返回更新后的 Agent 对象。

#删除 Agent

DELETE /v1/agents/:agentId

所需权限: agents:delete（admin 或 user 角色）

#响应

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