定义 Agent-Qoder CN 系列(Lingma)-阿里云帮助中心

核心要素

可以把 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）。