> ## 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 配置。

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       | 否  | 系统提示词，默认 `""`                    |
| `tools`       | array        | 否  | 可用工具列表，详见下文                      |
| `skills`      | array        | 否  | 关联的 Skill ID 列表                  |
| `mcp_servers` | array        | 否  | MCP 服务器配置列表，默认 `[]`              |
| `multiagent`  | object\|null | 否  | Agents 配置；未设置时返回 `null`          |
| `metadata`    | object       | 否  | 自定义键值对，用于标记和筛选                   |
| `version`     | integer      | —  | 版本号，从 1 开始递增                     |
| `archived_at` | string\|null | —  | 归档时间（ISO 8601），未归档时为 `null`      |
| `created_at`  | string       | —  | 创建时间，ISO 8601 格式                 |
| `updated_at`  | string       | —  | 最后更新时间                           |

### model

`model` 指定 Agent 使用的模型。可先调用 [列出模型](/zh/cloud-agents/api/models/list) 查询当前账户可用值，再在创建或更新 Agent 时传入模型 `id`。

### tools

`tools` 是工具对象数组。内置工具通过 `agent_toolset_20260401` 配置，并使用 `enabled_tools` 数组按需开启原子工具：

```json theme={null}
{
  "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`        | 联网搜索                           |
| `DeliverArtifacts` | 将 Agent 在 `/data/` 下产出的文件投递给用户 |

自定义 client-side 工具与权限策略参见 [Agent 工具配置](/zh/cloud-agents/tools)。

## 管理 Agent

完整的 CRUD 接口请参考 [API Reference / Agents](/zh/cloud-agents/api/agents/create)。下面是常用工作流示例。

### 创建

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

成功返回 **200 OK**，`version` 从 `1` 开始。

### 查询

```bash theme={null}
# 获取单个 Agent
curl -s https://api.qoder.com/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

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

### 更新

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

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

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

## 版本管理

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

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

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

### 处理 409 冲突

当持有的版本已过期时：

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}
```

恢复步骤：

1. `GET` 最新 Agent 拿到当前 `version`
2. 合并自己的变更
3. 用新 `version` 重新 `POST`

## 最佳实践

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

## 常见问题

**Q：更新 Agent 后，正在运行的 Session 会受影响吗？**

不会。Session 在创建时绑定了 Agent 的特定版本，后续修改不影响已存在的 Session。

**Q：`tools` 数组为空可以吗？**

可以。不带工具的 Agent 只能进行纯文本对话，无法执行任何操作。

**Q：`name` 字段有长度限制吗？**

建议控制在 64 字符以内，使用小写字母、数字和短横线。

**Q：如何回滚到旧版本的 Agent？**

目前不支持自动回滚。建议在更新前记录旧配置，需要时手动 `POST` 回旧配置（携带最新 `version`）。

## 下一步

<CardGroup cols={2}>
  <Card title="云端环境配置" icon="server" href="/zh/cloud-agents/environments">
    配置 Agent 运行的基础设施。
  </Card>

  <Card title="启动 Session" icon="play" href="/zh/cloud-agents/sessions">
    用 Agent 创建工作会话。
  </Card>

  <Card title="Agent 工具配置" icon="wrench" href="/zh/cloud-agents/tools">
    工具类型与权限策略详解。
  </Card>

  <Card title="Agents API" icon="code" href="/zh/cloud-agents/api/agents/create">
    完整的 Agents CRUD 接口。
  </Card>
</CardGroup>