Bundle Agent 定义、版本创建与 Workflow 引用

使用统一 Bundle 资源命令创建 Agent 定义和不可变版本，并以领域身份供 Workflow agent 节点引用。

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

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

机器可读合同

Agent Definition Schema 描述 --definition 文件，不包含资源身份和响应 envelope。workspaceId、bundleId 和 agentKey 由已授权 Bundle 上下文和资源 Owner 注入，创建时不传入身份，definition 中出现这些字段会被拒绝；版本号只在版本创建命令和 Manifest 中出现。

定义边界

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

personaPrompt、dockerImage、apiKeyId、inheritCcSystemPrompt 和整个 promptConfig（包括 sections）已退出公开合同。系统提示词统一使用 systemPrompt，保存和执行时保留正文；promptConfig 即使为 null 也不能进入新的作者定义。镜像由 defaultRuntime.runtimeKey / defaultRuntime.semanticVersion 对应的 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。这些是目录数据，不应作为固定名单写入代码或文档。可先使用公开示例作为结构起点，但必须替换其中的模型占位文本，并按目标环境补充实际选择。

baijimu bundle object create <bundle> agent --workspace-id <workspaceId> \
  --definition @agent.json --json

baijimu bundle object update <bundle> agent --workspace-id <workspaceId> --object-id <ownerReturnedAgentKey> \
  --definition @agent.json --json

update 是完整定义更新，不是局部 patch。agentKey 由 Owner 返回；修改显示名不会改变身份，不能通过更新定义改变 Bundle 归属。子 Agent 应使用同一 Bundle 中稳定的 agentKey；创建当前 Agent 版本前，目标子 Agent 必须已经创建不可变版本。Skill 引用也会在版本创建时解析成可移植的 Bundle Skill 版本引用。

创建不可变 Agent 版本

baijimu bundle object version create <bundle> agent --workspace-id <workspaceId> \
  --object-id <ownerReturnedAgentKey> --version <semanticVersion> --json

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

写入 Bundle Manifest

baijimu bundle manifest include <bundle> agent --workspace-id <workspaceId> \
  --file baijimu.bundle.json --object-id <ownerReturnedAgentKey> --version <semanticVersion>

baijimu bundle manifest validate @baijimu.bundle.json

CLI 自动写入 definition.resources 的集合项，例如：

{
  "resourceType": "AGENT",
  "resourceKey": "owner-returned-agent-id",
  "semanticVersion": "1.0.0"
}

Bundle 版本创建后，Runtime 根据安装台账把这个资源版本物化成当前工作区可执行的 Agent。Workflow 使用 agent: {bundleId, agentKey} 领域引用选择对象，精确版本由 Bundle 源清单确定，不引用 Agent 数据库 ID、会话 ID、某台主机或可变“最新版”。

在 Workflow 中调用

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

agent.bundleId + agent.agentKey 必须来自当前 Bundle 或显式依赖闭包的目录。Agent 会话结束后，worker 按 result.type 校验最终结构并写入 context.analysisReport，后续节点或 end 直接消费该路径。旧字段 promptTemplate、outputFormat、projectIdPath、workspaceIdPath、userIdPath、sessionIdTemplate 和节点级 timeoutSecs 不属于当前作者合同，会被引擎拒绝。

Runtime 方法范围

runtimeMethods 统一使用范围对象，无需传入能力格式版本：

{
  "configName": "Operations Assistant",
  "runtimeMethods": { "mode": "selected", "methods": [{ "service": "orders", "method": "list" }] }
}

mode 有三种：all 选择当前可授权的全部 Runtime 方法；selected 选择明确列出的非空方法集合； none 禁用 Runtime 方法。all 和 none 不携带 methods，selected 最多 1024 个不重复方法。这里的 service 是当前 Runtime 中的服务 businessId。方法范围不接受数组；禁用时明确使用 none。

配置字段缺省或为 null 时默认为 all。部分更新省略该字段时保留已保存的显式范围。 Session 创建时确定并固定范围。内部 Agent 使用已认证的会话创建用户，外部 Agent 使用执行 Token 绑定用户。 Scope 只选方法，不增加用户权限：实际访问同时受有限的 Access Grant 和当前工作区 IAM 约束。 all 在授权时形成方法快照；后续安装的新服务不会自动扩大已有 Grant。

历史不可变 Agent 定义和 Schema 1.0.0 保持原样。作者更新配置后需发布新的 Agent 版本，再通过 Bundle 升级应用到工作区；既有 Session 不自动扩权。

sections 迁移

将原 systemPrompt 与启用的 sections 按 sortOrder 和原数组顺序合并为一段 systemPrompt；保留 Markdown 标题和正文。发布新的 Agent 和 Bundle 版本，再升级工作区安装。旧的不可变版本不改写，使用旧 sections 版本的会话需要改用新版本建立会话。

Runtime 使用可移植的 defaultRuntime 引用；旧 runtimeId、runtimeVersionId 和 parentAgentConfigId 不进入当前作者合同。父 Agent 使用 parentAgentKey，Skill 使用 {skillKey, semanticVersion}，子 Agent 使用稳定的 agentKey。

Bundle Agent 定义、版本创建与 Workflow 引用

本页内容