> ## 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. # 创建 Agent > 创建一个新的 Agent 配置。 `POST /api/v1/cloud/agents` 创建一个新的 Agent 配置。 ## 请求头 | 头部 | 必选 | 说明 | | ----------------- | -- | ------------------ | | `Authorization` | 是 | `Bearer ` | | `Content-Type` | 是 | `application/json` | | `Idempotency-Key` | 否 | 幂等键，防止重复创建 | ## 请求体 | 字段 | 类型 | 必选 | 说明 | | ------------- | --------------------------------------------------------------------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | 是 | Agent 名称，长度 1-256 字符 | | `model` | string \| object | 是 | 模型标识。可传 string（如 `"ultimate"`），或传 [Agent model](/zh/cloud-agents/api/agents/schemas#agent-model) 对象以同时配置 `effort` 或 `context_window`。可通过 [列出模型](/zh/cloud-agents/api/models/list) 查询可用值 | | `system` | string | 否 | 系统提示词（System Prompt），最长 100000 字符 | | `description` | string | 否 | Agent 描述，最长 2048 字符 | | `tools` | [Agent tool](/zh/cloud-agents/api/agents/schemas#agent-tool) 数组 | 否 | 工具配置列表，最多 128 个 | | `mcp_servers` | [MCP server](/zh/cloud-agents/api/agents/schemas#mcp-server) 数组 | 否 | MCP 服务器配置列表，最多 20 个。鉴权通过 [Vault](/zh/cloud-agents/vaults) 配置 | | `skills` | [Skill binding](/zh/cloud-agents/api/agents/schemas#skill-binding) 数组 | 否 | Skill 绑定列表，最多 20 个 | | `metadata` | [Metadata 对象](/zh/cloud-agents/api/conventions/schemas#metadata-对象) | 否 | 自定义元数据，省略时为 `{}` | | `multiagent` | [Multiagent](/zh/cloud-agents/api/agents/schemas#multiagent) | 否 | Agents 配置。设置后需同时配置 `agent_toolset_20260401` 工具 | ## 示例请求 ```bash theme={null} curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "doc-test-agent", "model": "ultimate", "system": "你是文档测试助手", "tools": [ { "type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"] } ], "mcp_servers": [ { "type": "url", "name": "weather-service", "url": "https://mcp.example.com/mcp" } ] }' ``` 如需配置 reasoning effort 或上下文窗口，将 `model` 以对象形式传入： ```bash theme={null} curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "doc-test-agent-tuned", "model": { "id": "ultimate", "effort": "high", "context_window": 400000 }, "system": "你是文档测试助手" }' ``` ## 示例响应 **HTTP 200 OK** ```json theme={null} { "type": "agent", "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "name": "doc-test-agent", "description": "", "model": "ultimate", "system": "你是文档测试助手", "tools": [ { "type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"] } ], "mcp_servers": [ { "type": "url", "name": "weather-service", "url": "https://mcp.example.com/mcp" } ], "skills": [], "metadata": {}, "multiagent": null, "version": 1, "archived_at": null, "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 \| object | 模型标识，详见 [Agent model](/zh/cloud-agents/api/agents/schemas#agent-model) | | `system` | string | 系统提示词 | | `tools` | [Agent tool](/zh/cloud-agents/api/agents/schemas#agent-tool) 数组 | 工具配置列表 | | `mcp_servers` | [MCP server](/zh/cloud-agents/api/agents/schemas#mcp-server) 数组 | MCP 服务器配置 | | `skills` | [Skill binding](/zh/cloud-agents/api/agents/schemas#skill-binding) 数组 | Skill 绑定列表 | | `metadata` | [Metadata 对象](/zh/cloud-agents/api/conventions/schemas#metadata-对象) | 自定义元数据 | | `multiagent` | [Multiagent](/zh/cloud-agents/api/agents/schemas#multiagent) \| null | Agents 配置，未设置时为 `null` | | `version` | integer | 当前版本号，从 1 开始递增 | | `archived_at` | string\|null | 归档时间（ISO 8601），未归档时为 `null` | | `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` | `model.effort` 不在 `none`、`low`、`medium`、`high`、`xhigh`、`max` 之内 | | 400 | `invalid_request_error` | `model.context_window` 不是正整数 | | 400 | `invalid_request_error` | 传入了 `model.speed`，请改用 `model.effort` | | 400 | `invalid_request_error` | `tools` 数量超过 128 个上限 | | 400 | `invalid_request_error` | `mcp_servers` 或 `skills` 配置格式错误 | | 400 | `invalid_request_error` | `skills` 数量超过 20 个上限 | | 400 | `invalid_request_error` | `multiagent.type` 不是 `"coordinator"` | | 400 | `invalid_request_error` | `multiagent.agents` 为空或超过 20 个上限 | | 400 | `invalid_request_error` | 设置 `multiagent` 但 `tools` 缺少 `agent_toolset_20260401` | | 400 | `invalid_request_error` | `multiagent.agents` 中引用的 Agent ID 不存在 | | 401 | `authentication_error` | PAT 无效或过期 | | 403 | `permission_error` | 无权限执行此操作 | 错误响应示例： ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "invalid_request_error", "message": "name must be between 1 and 256 characters" } } ``` 完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。 ## 相关 创建可复用、可版本化的 Agent 配置。