Migration
Agent Graph is pre-1.0: a 0.x release may tighten a field or invariant, but documents the break and updates every template, example and test. A Provider's own version is independent of the @c4a/agent-graph package version.
| Release | What changed for Provider authors |
|---|---|
| 0.1.0 | Initial specification, SDK, CLI, schemas, templates and examples |
| 0.1.1 | Stricter Graph validation and materialization boundaries; explicit Run state and recovery |
| 0.2.0 | Breaking. Action and Gate nodes require a route.* reasonCode; Skill bindings need all three metadata fields; a declared Code Catalog is a closed set |
| 0.2.1 | Gate resolutionAction, which must be able to change observable state |
| 0.2.2 | Read-only Gate inspectionAction, exposed separately from the resolution plan |
| 0.2.3 | Current-conversation read receipts and readState on Route resources |
| 0.2.4 | Documentation and replay updates to the Context case study |
| 0.2.5 | Lifecycle-aware evidence modelled as ordinary revision-bound Facts |
| 0.2.6 | Gate delegated policies for session-authority Routes |
| 0.2.7 | Host-materialized resources with versioned input and output schemas |
| 0.3.0 | Breaking. Resource identifiers split into three independent v1 protocols |
| 0.3.1 | Scaffold, templates and examples declare compatibility.agentGraph: ^0.3.0; the 0.3.0 Resource migration is documented |
Upgrading to 0.2.x
- Give every Action and Gate node a stable
reasonCodebeginning withroute.. - If the Provider declares
catalogs.codes, add every one of those codes as aroute-reasonentry, or validation fails withroute-reason-code-missing. - Update every bound Skill to declare all three fields:
metadata:
agent-graph: path:../../provider.yaml
agent-graph.graph: release
agent-graph.entry: default- Validate every Provider before switching hosts to the new runtime.
The later 0.2 releases are additive: Gate inspection and resolution Actions, read receipts, delegated policies and host-materialized resources are opt-in.
Upgrading to 0.3.0
0.3.0 removed the numbered resource identifiers agent-graph.resource.v1, agent-graph.resource.v2, agent-graph.resource-location.v1 and agent-graph.resource-location.v2; the old names now fail schema validation with schema-invalid. Replace them by what the descriptor actually is:
| Before | Used for | After |
|---|---|---|
agent-graph.resource.v1 with path | A non-Markdown file (schema, template, diagnostic) | agent-graph.resource.file.v1 |
agent-graph.resource.v1 with materializer | A command or script context view | agent-graph.resource.graph-action.v1 |
agent-graph.resource.v2 | A host-materialized resource | agent-graph.resource.host-action.v1 |
agent-graph.resource-location.v1 | Resolved file or context-view location | agent-graph.resource-location.file.v1 or .graph-action.v1 |
agent-graph.resource-location.v2 | Resolved host-action location | agent-graph.resource-location.host-action.v1 |
Then raise the Provider's compatibility.agentGraph to ^0.3.0 and run agent-graph validate; the examples/host-materialized-resource example shows a Host-action resource. Markdown resources that carry id, kind and media-type in frontmatter are unaffected. Hosts that read Route resources should branch on the new location schema names; the host-action input and output ABI and its recovery rules are unchanged.
Importing an existing Skill
agent-graph init ./provider --id product-workflow
agent-graph import skill ../legacy-skill/SKILL.md --into ./provider --graph legacy-capability
agent-graph --manifest ./provider/provider.yaml validateThe importer copies the whole Skill directory to skills/<graph>/, adds the Provider, Graph and Entry binding to the copied SKILL.md and creates one agent Action and one Graph. The original instructions are preserved, not split into guessed phases, and the source Skill is left untouched.
Importing scripts and workflows
agent-graph import scripts ./inspect.sh ./package.sh --into ./provider --graph package-flow
agent-graph import workflow ./workflow.yaml --into ./provider- Scripts become a sequential Graph. The extension selects Node, Bun, Python or shell; the effect defaults to
write, because the importer cannot know which scripts are read-only or external. - Workflows use a compact shape —
idplusstepswithid,command,effectanddependsOn. The importer checks step shapes, missing dependencies, ID collisions and cycles before writing anything, turns dependencies into edges (fan-in usesjoin: all), adds a start Action and a Terminal after the leaves, and registers a reason code per step. Topology does not mean parallel execution. Templating, expressions, secrets, matrices and vendor retry policies are not interpreted.
Every import appends a section to IMPORT_REPORT.md beside provider.yaml and refuses to replace an existing Graph, Action, script directory or copied Skill. The report lists what must not be guessed — effects, Outcomes, recovery, Gates, resources and fact-backed completion. Treat it as an authoring checklist, then remove or archive it per your repository policy.
Finishing the draft
Review the imported Provider for:
- which operations are separate Actions;
- which resources are needed by only one Route;
- each Action's effect (
read,write,external); - human Gates and whether delegation is allowed;
- Facts that prove success;
failed,partial,unverifiedand recovery transitions;- stopping conditions for repeated work.
For a large Skill, change it in small, testable steps:
- Import without changing the source Skill.
- Validate the generated Provider.
- Add one graph test for today's happy path.
- Extract deterministic commands into Action files.
- Move long phase-specific instructions into Route resources.
- Add Facts and
satisfiedBybefore trusting recorded success. - Add explicit Gates and failure and recovery Outcomes.
- Add loop tests if work can repeat.
- Build and test the relocatable bundle.
- Only then replace the original Skill with a thinner bound entry.
Not every paragraph should become a node: nodes are independently actionable, gated, recoverable or testable transitions, and the rest stays a Resource. See Authoring Graphs and Testing and Publishing.
版本迁移
Agent Graph 尚处于 1.0 之前：0.x 版本可能会收紧某个字段或不变量，但会在文档中说明这一破坏性变更，并同步更新所有模板、示例和测试。Provider 自身的 version 与 @c4a/agent-graph 包的版本相互独立。
| 版本 | 对 Provider 作者的变化 |
|---|---|
| 0.1.0 | 初始的规范、SDK、CLI、schema、模板和示例 |
| 0.1.1 | 更严格的 Graph 校验和物化边界；显式的 Run 状态与恢复 |
| 0.2.0 | 破坏性变更。 Action 和 Gate 节点必须带有 route.* 形式的 reasonCode；Skill 绑定需要全部三个元数据字段；声明的 Code Catalog 是封闭集合 |
| 0.2.1 | Gate resolutionAction，它必须能够改变可观察的状态 |
| 0.2.2 | 只读的 Gate inspectionAction，与 resolution 计划分开暴露 |
| 0.2.3 | 当前会话的读取回执，以及 Route 资源上的 readState |
| 0.2.4 | 更新 Context 案例研究的文档与回放 |
| 0.2.5 | 把具有生命周期的证据建模为绑定修订号的普通 Facts |
| 0.2.6 | 面向会话授权 Route 的 Gate delegated 策略 |
| 0.2.7 | 宿主物化的资源，带有版本化的输入和输出 schema |
| 0.3.0 | 破坏性变更。 资源标识拆分为三个相互独立的 v1 协议 |
| 0.3.1 | 脚手架、模板和示例声明 compatibility.agentGraph: ^0.3.0；补充了 0.3.0 Resource 迁移说明 |
升级到 0.2.x
- 为每个 Action 和 Gate 节点指定一个以
route.开头的稳定reasonCode。 - 如果 Provider 声明了
catalogs.codes，把这些原因码全部添加为route-reason条目，否则校验会以route-reason-code-missing失败。 - 更新每个已绑定的 Skill，声明全部三个字段：
metadata:
agent-graph: path:../../provider.yaml
agent-graph.graph: release
agent-graph.entry: default- 在把宿主切换到新运行时之前，校验每个 Provider。
之后的 0.2 版本都是增量式的：Gate 的 inspection 与 resolution Action、读取回执、委托策略和宿主物化的资源都需要主动启用。
升级到 0.3.0
0.3.0 移除了带编号的资源标识 agent-graph.resource.v1、agent-graph.resource.v2、agent-graph.resource-location.v1 和 agent-graph.resource-location.v2；旧名称现在会以 schema-invalid 无法通过 schema 校验。请按描述符的实际用途替换：
| 之前 | 用途 | 之后 |
|---|---|---|
带 path 的 agent-graph.resource.v1 | 非 Markdown 文件（schema、模板、诊断） | agent-graph.resource.file.v1 |
带 materializer 的 agent-graph.resource.v1 | 命令或脚本上下文视图 | agent-graph.resource.graph-action.v1 |
agent-graph.resource.v2 | 宿主物化的资源 | agent-graph.resource.host-action.v1 |
agent-graph.resource-location.v1 | 解析后的文件或上下文视图位置 | agent-graph.resource-location.file.v1 或 .graph-action.v1 |
agent-graph.resource-location.v2 | 解析后的 Host Action 位置 | agent-graph.resource-location.host-action.v1 |
然后把 Provider 的 compatibility.agentGraph 提高到 ^0.3.0，并运行 agent-graph validate；examples/host-materialized-resource 示例展示了一个 Host-action 资源。在 frontmatter 中带有 id、kind 和 media-type 的 Markdown 资源不受影响。读取 Route 资源的宿主应根据新的位置 schema 名称分支处理；Host Action 的输入输出 ABI 及其恢复规则保持不变。
导入现有 Skill
agent-graph init ./provider --id product-workflow
agent-graph import skill ../legacy-skill/SKILL.md --into ./provider --graph legacy-capability
agent-graph --manifest ./provider/provider.yaml validate导入器会把整个 Skill 目录复制到 skills/<graph>/，在复制出的 SKILL.md 中添加 Provider、Graph 和 Entry 绑定，并创建一个 agent Action 和一个 Graph。原有说明会完整保留，不会被拆分成猜测出来的阶段，源 Skill 也保持不变。
导入脚本和工作流
agent-graph import scripts ./inspect.sh ./package.sh --into ./provider --graph package-flow
agent-graph import workflow ./workflow.yaml --into ./provider- 脚本会变成一个顺序执行的 Graph。扩展名决定使用 Node、Bun、Python 还是 shell；effect 默认为
write，因为导入器无法知道哪些脚本是只读的或会影响外部。 - 工作流使用一种紧凑的结构——
id加上steps，每个步骤包含id、command、effect和dependsOn。导入器在写入任何内容之前，会检查步骤结构、缺失的依赖、ID 冲突和环；然后把依赖转换为边（扇入使用join: all），添加一个起始 Action，并在叶子节点之后添加一个 Terminal（终止节点），同时为每个步骤登记一个原因码。拓扑结构并不意味着并行执行。模板、表达式、密钥、矩阵和各厂商的重试策略都不会被解释。
每次导入都会在 provider.yaml 旁边的 IMPORT_REPORT.md 中追加一节，并拒绝替换已有的 Graph、Action、脚本目录或已复制的 Skill。报告列出了不能靠猜测的内容——effect、Outcome、恢复、Gate、资源以及由 Facts 支撑的完成。请把它当作编写检查清单，然后按你所在仓库的策略删除或归档。
完善草稿
审查导入后的 Provider，确认：
- 哪些操作是独立的 Action；
- 哪些资源只被一个 Route 需要；
- 每个 Action 的 effect（
read、write、external）； - 人工 Gate，以及是否允许委托；
- 能证明成功的 Facts；
failed、partial、unverified及恢复转换；- 重复工作的停止条件。
对于大型 Skill，请以小而可测试的步骤逐步修改：
- 导入，但不修改源 Skill。
- 校验生成的 Provider。
- 为当前的正常路径添加一个 Graph 测试。
- 把确定性的命令提取到 Action 文件中。
- 把长篇的、特定于阶段的说明移到 Route 资源中。
- 在信任记录下来的成功之前，先添加 Facts 和
satisfiedBy。 - 添加显式的 Gate，以及失败和恢复 Outcome。
- 如果工作可能重复，添加循环测试。
- 构建并测试可迁移的产物包。
- 只有在此之后，才用更轻量的绑定入口替换原来的 Skill。
并非每一段都应变成节点：节点是可独立执行、受 Gate 控制、可恢复或可测试的转换，其余内容仍作为 Resource。参见 编写 Graph 和 测试与发布。