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 是 Qoder Cloud Agents 的核心配置模板，描述了 AI 代理的能力边界 —— 模型、行为指令、可用工具。一个 Agent 可被多个 Session 复用；修改 Agent 不影响已运行的 Session。
核心要素
可以把 Agent 理解为一份”岗位说明书”：
| 要素 | 含义 |
|---|
| 模型 | Agent 的智力水平 |
| 系统提示词 | Agent 的行为准则 |
| 工具集 | Agent 能执行的操作 |
| Skills | Agent 可调用的高级技能 |
字段参考
| 字段 | 类型 | 必填 | 说明 |
|---|
id | string | — | 系统生成，ag_ 前缀 |
name | string | 是 | Agent 名称，建议用英文短横线命名（≤ 64 字符） |
model | string | 是 | 模型标识，详见下文 |
system | string | 否 | 系统提示词，定义 Agent 行为 |
tools | array | 否 | 可用工具列表，详见下文 |
skills | array | 否 | 关联的 Skill ID 列表 |
metadata | object | 否 | 自定义键值对，用于标记和筛选 |
version | integer | — | 版本号，从 1 开始递增 |
created_at | string | — | 创建时间，ISO 8601 格式 |
updated_at | string | — | 最后更新时间 |
model
model 为字符串类型，指定 Agent 使用的模型：
| 值 | 说明 |
|---|
"ultimate" | 最强模型，适合复杂推理和长任务 |
"auto" | 自动选择性价比最优的模型 |
tools 是工具对象数组，每个元素声明 Agent 能执行的一类操作：
{
"tools": [
{"type": "bash_20250124"},
{"type": "file_read"},
{"type": "file_write"},
{"type": "web_search"}
]
}
| 类型 | 说明 |
|---|
bash | 执行 shell 命令 |
file_read | 读取文件内容 |
file_write | 创建或修改文件 |
web_search | 搜索互联网 |
管理 Agent
完整的 CRUD 接口请参考 API Reference / Agents。下面是常用工作流示例。
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "code-reviewer",
"model": "ultimate",
"system": "你是代码审查专家。逐行审查代码并以 Markdown 输出问题与改进建议。",
"tools": [
{"type": "bash_20250124"},
{"type": "file_read"},
{"type": "file_write"}
],
"metadata": {
"team": "backend",
"purpose": "code-review"
}
}' | jq .
version 从 1 开始。
# 获取单个 Agent
curl -s https://openapi.qoder.sh/api/v1/cloud/agents/ag_xxx \
-H "Authorization: Bearer $QODER_PAT"
# 分页列表
curl -s "https://openapi.qoder.sh/api/v1/cloud/agents?limit=20" \
-H "Authorization: Bearer $QODER_PAT"
version，详见下文「版本管理」。
curl -s -X PUT https://openapi.qoder.sh/api/v1/cloud/agents/ag_xxx \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "code-reviewer",
"model": "ultimate",
"system": "你是资深代码审查专家，专注安全漏洞和性能问题。",
"version": 1
}' | jq .
version 自动 +1。
curl -s -X DELETE https://openapi.qoder.sh/api/v1/cloud/agents/ag_xxx \
-H "Authorization: Bearer $QODER_PAT"
删除 Agent 不会终止已绑定该 Agent 的活跃 Session。Session 在创建时已快照了 Agent 配置。
版本管理
Agent 采用乐观并发控制（OCC）机制：
- 创建时
version 从 1 开始
- 每次成功更新，
version 自动 +1
- 更新请求必须携带当前
version，否则返回 409 Conflict
这避免了多人 / 多系统并发修改时互相覆盖。
处理 409 冲突
当持有的版本已过期时：
{
"error": {
"type": "conflict",
"message": "Version mismatch: expected 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）。
下一步
