定义 Agent - Qoder CN

Agent 是 Qoder Cloud Agents 的核心配置模板，描述了 AI 代理的能力边界 —— 模型、行为指令、可用工具。一个 Agent 可被多个 Session 复用；修改 Agent 不影响已运行的 Session。

核心要素

可以把 Agent 理解为一份”岗位说明书”：

要素	含义
模型	Agent 的智力水平
系统提示词	Agent 的行为准则
工具集	Agent 能执行的操作
Skills	Agent 可调用的高级技能

Agent 本身不执行任务，它只是配置。真正执行任务的是绑定该 Agent 的 Session。

字段参考

字段	类型	必填	说明
`id`	string	—	系统生成，`agent_` 前缀 + 32 字符十六进制（小写）
`type`	string	—	固定为 `"agent"`
`name`	string	是	Agent 名称，建议用英文短横线命名（≤ 64 字符）
`description`	string	否	描述信息，默认 `""`
`model`	string	是	模型标识，详见下文
`system`	string	否	系统提示词，默认 `""`
`instructions`	string	否	追加在系统提示词后的行为指令
`tools`	array	否	可用工具列表，详见下文
`skills`	array	否	关联的 Skill ID 列表
`mcp_servers`	array	否	MCP 服务器配置列表，默认 `[]`
`default_environment`	string	否	该 Agent 的默认 Environment ID，默认 `""`
`metadata`	object	否	自定义键值对，用于标记和筛选
`version`	integer	—	版本号，从 1 开始递增
`archived`	boolean	—	是否已归档，默认 `false`
`archived_at`	string\|null	—	归档时间（ISO 8601），未归档时为 `null`
`created_at`	string	—	创建时间，ISO 8601 格式
`updated_at`	string	—	最后更新时间

model

model 为字符串类型，指定 Agent 使用的模型：

值	说明
`Auto`	自动选型
`Qwen3.7-Max`	通义旗舰
`Qwen3.7-Plus`	通义多模态
`Qwen3.6-Flash`	通义轻量
`DeepSeek-V4-Pro`	DeepSeek 旗舰
`DeepSeek-V4-Flash`	DeepSeek 轻量
`GLM-5.1`	智谱旗舰
`Kimi-K2.6`	月之暗面
`MiniMax-M2.7`	MiniMax

tools

tools 是工具对象数组，当前仅支持单一对象 agent_toolset_20260401，通过 enabled_tools 数组按需开启原子工具：

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

可用的 enabled_tools 值（首字母大写）：

工具名	说明
`Bash`	执行 shell 命令
`Read`	读取文件内容
`Write`	创建或覆盖文件
`Edit`	局部编辑文件
`Glob`	通配符列文件
`Grep`	文件内容搜索
`WebFetch`	HTTP GET 单页面
`WebSearch`	联网搜索

更多工具配置参见 Agent 工具配置。

管理 Agent

完整的 CRUD 接口请参考 API Reference / Agents。下面是常用工作流示例。

创建

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "你是代码审查专家。逐行审查代码并以 Markdown 输出问题与改进建议。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .

成功返回 201 Created，version 从 1 开始。

查询

# 获取单个 Agent
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

# 分页列表
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

更新

更新 Agent 必须携带当前 version，详见下文「版本管理」。

curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "你是资深代码审查专家，专注安全漏洞和性能问题。",
    "version": 1
  }' | jq .

成功返回 200 OK，version 自动 +1。

删除

curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

删除 Agent 不会终止已绑定该 Agent 的活跃 Session。Session 在创建时已快照了 Agent 配置。

版本管理

Agent 采用乐观并发控制（OCC）机制：

创建时 version 从 1 开始
每次成功更新，version 自动 +1
更新请求必须携带当前 version。两种失败情形：
- 缺少 version 字段 — 返回 400 invalid_request_error（"Field 'version' is required."）
- version 存在但与服务端不一致 — 返回 409 conflict_error

这避免了多人 / 多系统并发修改时互相覆盖。

处理 409 冲突

当持有的版本已过期时：

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}

恢复步骤：

GET 最新 Agent 拿到当前 version
合并自己的变更
用新 version 重新 PUT

最佳实践

命名规范 — 用 团队-用途 格式，如 backend-code-review、frontend-test-gen
提示词精炼 — system 字段写清角色、输出格式、限制条件
最小工具集 — 只配置任务所需的工具，减少误操作风险
善用 metadata — 用标签分类管理，方便后续筛选和审计
生产环境锁版本 — 创建 Session 时用 {"id": ..., "version": ...} 形式锁定 Agent 版本，避免新版本影响线上行为

常见问题

Q：更新 Agent 后，正在运行的 Session 会受影响吗？不会。Session 在创建时绑定了 Agent 的特定版本，后续修改不影响已存在的 Session。Q：tools数组为空可以吗？可以。不带工具的 Agent 只能进行纯文本对话，无法执行任何操作。Q：name字段有长度限制吗？建议控制在 64 字符以内，使用小写字母、数字和短横线。Q：如何回滚到旧版本的 Agent？目前不支持自动回滚。建议在更新前记录旧配置，需要时手动 PUT 回旧配置（携带最新 version）。

下一步

云端环境 — 配置 Agent 运行的基础设施
启动 Session — 用 Agent 创建工作会话
Agent 工具配置 — 工具类型与权限策略详解

​核心要素

​字段参考

​model

​tools

​管理 Agent

​创建

​查询

​更新

​删除

​版本管理

​处理 409 冲突

​最佳实践

​常见问题

​下一步