# Bundle Agent 定义、发布与 Workflow 引用

使用统一 Bundle 资源命令创建和发布 Agent，并以稳定 Resource Locator 供 Workflow agent 节点引用。

Bundle Agent 是由 Agent Config Owner 保存、按严格 SemVer 冻结、随 Bundle 安装到 Runtime 的资源。
它负责稳定的系统提示词、工具、Skill、子 Agent、运行时和模型选择；Workflow 的 `agent` 节点只负责
传入本次任务的 `message`、声明结构化 `result`，以及配置持久化等待的 `executionPolicy`。

`baijimu agent` 只管理会话和消息。Agent 资源的创建、完整更新和发布统一使用
`baijimu bundle resource`，并不是通过会话命令创建。

## 机器可读合同

- [Agent Definition JSON Schema 1.0.0](https://docs.baijimu.com/contracts/agent-definition/1.0.0/schema.json)
- [运营分析 Agent definition 示例](https://docs.baijimu.com/contracts/agent-definition/1.0.0/examples/operations-analyst.json)
- [Workflow Definition JSON Schema 5.0.0](https://docs.baijimu.com/contracts/workflow-definition/5.0.0/schema.json)
- [`agent` 节点 JSON 示例](https://docs.baijimu.com/contracts/workflow-definition/5.0.0/examples/agent-node.json)

Agent Definition Schema 描述 `--definition` 文件，不包含资源身份和响应 envelope。`workspaceId`、`bundleId` 和 `agentKey`
由 CLI 参数及资源 Owner 注入，definition 中出现这些字段会被拒绝；版本号只在发布命令和
Manifest 中出现。

## 定义边界

| 配置                                           | 所属层                 | 规则                                                         |
| -------------------------------------------- | ------------------- | ---------------------------------------------------------- |
| `configName`、`systemPrompt`、工具、Skill、子 Agent | Agent Definition    | 随不可变 Agent 版本冻结。                                           |
| `runtimeId`、`runtimeVersionId`               | Agent Definition    | 从当前 Agent Runtime 目录选择，不得把示例值、旧环境 ID 或部署事实复制到其他环境。         |
| `modelName`                                  | Agent Definition    | Runtime 可选择的模型名，可继承或显式覆盖。                                  |
| provider 路由                                  | llm-gateway         | 不属于 Agent Definition；`modelProvider` 不进入 1.0.0 definition。 |
| `message`、`result`、`executionPolicy`         | Workflow `agent` 节点 | 表达一次工作流任务、结构化结果和等待策略。                                      |
| `workspaceId`、`userId`、`sessionId`           | 受信运行时上下文            | 不能由 Agent 或 Workflow 作者伪造。                                 |

`personaPrompt`、`dockerImage`、`apiKeyId`、`inheritCcSystemPrompt` 和 `promptConfig.stages` 已退出公开合同。
系统提示词使用 `systemPrompt` 或 `promptConfig.sections`；镜像由 `runtimeId` / `runtimeVersionId` 对应的
Agent Runtime 版本解析；模型凭证由目标工作区的凭证体系按请求身份解析，不能冻结进 Agent definition。

`environmentVariables` 和 `mcpServersConfig.*.env` 只能保存非敏感配置。字段名包含
`API_KEY`、`APIKEY`、`ACCESS_KEY`、`SECRET`、`TOKEN`、`PASSWORD`、`PRIVATE_KEY` 或 `CREDENTIAL`
的内联变量会在发布时失败；密钥应使用目标工作区的模型凭证、Connector 或密钥绑定。

## 创建和更新草稿

先从目标环境的 Agent Runtime 目录选择可用 Runtime、Runtime Version 和 `modelName`，再准备
`agent.json`。这些是目录数据，不应作为固定名单写入代码或文档。可先使用公开示例作为结构起点，
但必须替换其中的模型占位文本，并按目标环境补充实际选择。

```bash
baijimu bundle resource create --workspace-id <workspaceId> <bundle> AGENT <agentKey> \
  --definition @agent.json --json

baijimu bundle resource update --workspace-id <workspaceId> <bundle> AGENT <agentKey> \
  --definition @agent.json --json
```

`update` 是完整定义更新，不是局部 patch。`agentKey` 是 Bundle 内稳定资源 Key；重命名或移动到其他
Bundle 必须创建新资源。子 Agent 应使用同一 Bundle 中稳定的 `agentKey`，发布前目标子 Agent 必须已经
冻结为不可变版本。Skill 引用也会在发布时解析成可移植的 Bundle Skill 版本引用。

## 发布不可变 Agent 版本

```bash
baijimu bundle resource publish --workspace-id <workspaceId> <bundle> AGENT <agentKey> <semanticVersion> --json
```

发布会把当前草稿冻结为不可变快照，并校验资源归属、严格 SemVer、子 Agent、Skill 和内联密钥。
发布结果中的 Agent 版本归 Agent Config Owner；Bundle Manifest 只引用它，不复制 definition。

## 写入 Bundle Manifest

```bash
baijimu bundle manifest resource add @baijimu.bundle.json --resource-type AGENT \
  --resource-key <agentKey> --version <semanticVersion>

baijimu bundle manifest validate @baijimu.bundle.json
```

Manifest 中的引用是：

```json
{
  "resourceType": "AGENT",
  "resourceKey": "operations-analyst",
  "semanticVersion": "1.0.0"
}
```

Bundle 版本发布后，Runtime 根据安装台账把这个资源版本物化成当前工作区可执行的 Agent。Workflow 使用
`baijimu/example-operations/AGENT/operations-analyst` 形式的 Bundle Resource Locator 引用安装后的资源，
不引用 Agent 数据库 ID、会话 ID、某台主机或可变“最新版”。

## 在 Workflow 中调用

```json
{
  "type": "agent",
  "id": "analyze_operations",
  "agentResourceLocator": "baijimu/example-operations/AGENT/operations-analyst",
  "message": "请基于 {{context.analysisInput}} 完成分析、给出建议并生成报告。",
  "result": {
    "path": "analysisReport",
    "type": {
      "@type": "DataType",
      "type": "object"
    }
  },
  "executionPolicy": {
    "completionTimeoutSecs": 600
  }
}
```

`agentResourceLocator` 必须能由当前 Runtime 的有效 Bundle 安装唯一解析。Agent 会话结束后，worker 按
`result.type` 校验最终结构并写入 `context.analysisReport`，后续节点或 `end` 直接消费该路径。旧字段
`promptTemplate`、`outputFormat`、`projectIdPath`、`workspaceIdPath`、`userIdPath`、`sessionIdTemplate`
和节点级 `timeoutSecs` 不属于 Workflow 5.0.0，会被 Schema 和引擎拒绝。