Documentation Index
Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
Use this file to discover all available pages before exploring further.
POST /v1/agents
创建一个新的 Agent 配置。
请求头
| 头部 | 必选 | 说明 |
|---|
Authorization | 是 | Bearer <PAT> |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 幂等键，防止重复创建。详见 幂等键 |
请求体
| 字段 | 类型 | 必选 | 说明 |
|---|
name | string | 是 | Agent 名称，长度 1-256 字符 |
model | string/object | 是 | 模型标识，可以是字符串（如 "ultimate"）或对象 |
system | string | 否 | 系统提示词（System Prompt） |
description | string | 否 | Agent 描述 |
tools | array | 否 | 工具配置列表 |
mcp_servers | array | 否 | MCP 服务器配置列表 |
metadata | object | 否 | 自定义元数据键值对 |
示例请求
curl -X POST "https://openapi.qoder.sh/api/v1/cloud/agents" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "doc-test-agent",
"model": "ultimate",
"system": "你是文档测试助手"
}'
示例响应
HTTP 201 Created
{
"type": "agent",
"id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"name": "doc-test-agent",
"description": "",
"model": "ultimate",
"system": "你是文档测试助手",
"instructions": "你是文档测试助手",
"tools": [],
"mcp_servers": [],
"default_environment": "",
"version": 1,
"created_at": "2026-05-18T15:26:39.61669Z",
"updated_at": "2026-05-18T15:26:39.61669Z"
}
响应字段
| 字段 | 类型 | 说明 |
|---|
type | string | 固定值 "agent" |
id | string | Agent 唯一标识，前缀 "agent_" |
name | string | Agent 名称 |
description | string | Agent 描述 |
model | string | 模型标识 |
system | string | 系统提示词 |
instructions | string | 指令内容（与 system 字段同步） |
tools | array | 工具配置列表 |
mcp_servers | array | MCP 服务器配置 |
default_environment | string | 默认运行环境 |
version | integer | 当前版本号，从 1 开始递增 |
created_at | string | 创建时间（ISO 8601） |
updated_at | string | 最后更新时间（ISO 8601） |
错误码
| HTTP | type | 触发条件 |
|---|
| 400 | invalid_request_error | 缺少必填字段 name |
| 400 | invalid_request_error | name 长度超过 256 字符 |
| 400 | invalid_request_error | 缺少必填字段 model |
| 400 | invalid_request_error | mcp_servers 或 skills 配置格式错误 |
| 401 | authentication_error | PAT 无效或过期 |
| 403 | permission_error | 无权限执行此操作 |
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "name must be between 1 and 256 characters"
}
}
