Getting Started
Agent Graph is useful only as part of a Skill or an Agent host; installing the CLI does not by itself change how any Agent works. Decide which boundary you are changing first:
| Your situation | Path | Start with |
|---|---|---|
| A Skill works but has grown long, repeats context every turn, loses its place across sessions, or describes Gates and recovery in prose | Improve an existing Skill | Migration |
| The capability does not exist yet and its operating contract can be designed with the Skill | Create a new Skill or workflow | This tutorial, then Authoring Graphs |
| A product already owns Agent discovery, command execution, UI or workspace state | Embed Agent Graph in a host | Skills and Providers and CLI and SDK |
The tutorial below needs Node.js 20 or later. Every command pins the CLI with npx @c4a/agent-graph@0.3.0 so the results are reproducible.
1. Create a Provider
npx @c4a/agent-graph@0.3.0 init ./example-provider --id example-provider
cd example-providerThe generated project is a complete, minimal Provider:
| File | What it is |
|---|---|
provider.yaml | The Provider manifest: ID, version, Graph list and Code Catalog |
graphs/main.yaml | One Graph, entry default, an Action node work and a Terminal done |
actions/work.yaml | An Agent Action (runner: agent, effect: write) bound to the Skill below |
skills/getting-started/SKILL.md | A thin Skill whose metadata binds Provider, Graph main and Entry default |
resources/procedure.md | The procedure the Route requires the Agent to read |
codes.yaml | The Code Catalog declaring the reason code route.main.work |
tests/main.yaml | One graph test asserting the starter Route is actionable |
No runtime directory is created. Where a host keeps Run files is the host's choice; the protocol reserves no directory.
2. Validate and test
npx @c4a/agent-graph@0.3.0 validate --format json
npx @c4a/agent-graph@0.3.0 test tests --format jsonValidation checks JSON Schemas, that relative paths stay inside the Provider, IDs and references, entrypoints, explicit Terminals, edge endpoints, Subgraph calls, recursion, dynamic resource materializers and duplicate identities. It never executes an Action. For the starter it reports "state":"valid" with 1 Graph, 2 nodes and 1 edge; the test run reports "state":"passed","total":1,"failed":0.
3. Find the current Route
npx @c4a/agent-graph@0.3.0 evaluate main --format jsonThe Evaluation contains a stable statusCode, a revision digest, one primaryRoute, compact alternatives and diagnostics. For the starter, the primary Route is the work node with reasonCode: route.main.work, availability: immediate and the catalog hint "The requested work is ready to perform." No Skill or procedure body is inlined.
Resolve that Route using both values from the same Evaluation:
npx @c4a/agent-graph@0.3.0 route main <route-id> --revision <revision> --format jsonThe Route returns the selected node and its call path, the Action, an empty commandPlan (an Agent Action runs no command), the required resources — the Skill and resources/procedure.md, each as an absolute file path with a content digest and readState: read-required — and afterAction: {evaluate: true, recordNode: "main/work"}. If a Provider file or input changed in between, the CLI rejects the stale revision instead of returning a mismatched plan.
Because the Skill already binds Provider, Graph and Entry, the same Evaluation works from the Skill alone:
npx @c4a/agent-graph@0.3.0 --skill ./skills/getting-started/SKILL.md evaluate --format json4. Track a long task with a Run
npx @c4a/agent-graph@0.3.0 run start main --state ./runtime/run.json --workspace "$PWD"
# ... the Agent reads the required resources and does the work ...
npx @c4a/agent-graph@0.3.0 run record main/work completed --state ./runtime/run.json
npx @c4a/agent-graph@0.3.0 run status --manifest ./provider.yaml --state ./runtime/run.json --format jsonRecord with the exact afterAction.recordNode key. run record reminds you that recorded Outcomes are not proof of Facts, and run status evaluates again: for the starter it now returns statusCode: complete with outcome: completed. In a real Graph a historical completed does not override a missing fact check; the next Evaluation may route to verification or recovery instead. See Runs and Recovery.
5. Build a relocatable bundle
npx @c4a/agent-graph@0.3.0 build ./dist/provider --format json
npx @c4a/agent-graph@0.3.0 --manifest ./dist/provider/manifest.json validateThe bundle contains only reachable Provider files, a normalized provider.yaml and a manifest.json with every file digest, the Graph dependency index and an overall digest. Tests stay out, and no source-machine absolute path is written, so the bundle can be shipped inside your own package.
Next steps
- Turn the starter into a real workflow with Facts, a Gate, recovery and a loop: Authoring Graphs.
- Cover every branch in CI and ship the bundle: Testing and Publishing.
- Learn the evaluation model behind what you just ran: Core Model.
- Browse runnable patterns in the repository's
examples/directory, such asreview-gate,facts-recovery,fact-driven-batch,monitoring-loopandsubgraphs.
快速上手
Agent Graph 只有作为 Skill 或 Agent 宿主的一部分时才有用；仅安装 CLI 并不会改变任何 Agent 的工作方式。先确定你要改变的是哪一层边界：
| 你的情况 | 路径 | 从这里开始 |
|---|---|---|
| Skill 能用，但已经变得很长、每轮重复上下文、跨会话会丢失进度，或者用文字描述 Gate 和恢复 | 改进现有 Skill | 版本迁移 |
| 能力尚不存在，其运行契约可以与 Skill 一起设计 | 新建 Skill 或工作流 | 本教程，然后是 编写 Graph |
| 某个产品已经负责 Agent 发现、命令执行、UI 或工作区状态 | 在宿主中嵌入 Agent Graph | 技能与 Provider 和 CLI 与 SDK |
下面的教程需要 Node.js 20 或更高版本。每条命令都用 npx @c4a/agent-graph@0.3.0 固定 CLI 版本，以保证结果可复现。
1. 创建 Provider
npx @c4a/agent-graph@0.3.0 init ./example-provider --id example-provider
cd example-provider生成的项目是一个完整而最小的 Provider：
| 文件 | 说明 |
|---|---|
provider.yaml | Provider 清单：ID、版本、Graph 列表和 Code Catalog |
graphs/main.yaml | 一个 Graph，入口为 default，包含 Action 节点 work 和 Terminal（终止节点）done |
actions/work.yaml | 一个 Agent Action（runner: agent、effect: write），绑定到下面的 Skill |
skills/getting-started/SKILL.md | 一个轻量 Skill，其元数据绑定 Provider、Graph main 和 Entry default |
resources/procedure.md | Route 要求 Agent 读取的流程 |
codes.yaml | 声明原因码 route.main.work 的 Code Catalog |
tests/main.yaml | 一个 Graph 测试，断言入门 Route 处于可执行状态 |
不会创建任何运行时目录。Run 文件存放在哪里由宿主决定；协议不预留任何目录。
2. 校验与测试
npx @c4a/agent-graph@0.3.0 validate --format json
npx @c4a/agent-graph@0.3.0 test tests --format json校验会检查 JSON Schema、相对路径是否留在 Provider 内、ID 与引用、入口、显式的 Terminal、边的端点、Subgraph 调用、递归、动态资源物化器以及重复的身份标识。它从不执行 Action。对于入门项目，它报告 "state":"valid"，包含 1 个 Graph、2 个节点和 1 条边；测试运行报告 "state":"passed","total":1,"failed":0。
3. 找到当前 Route
npx @c4a/agent-graph@0.3.0 evaluate main --format jsonEvaluation 包含一个稳定的 statusCode、一个 revision 摘要、一个 primaryRoute、精简的备选项和诊断。对于入门项目，主 Route 是 work 节点，带有 reasonCode: route.main.work、availability: immediate 以及目录提示 “The requested work is ready to perform.”。不会内联任何 Skill 或流程正文。
使用同一次 Evaluation 中的两个值来解析该 Route：
npx @c4a/agent-graph@0.3.0 route main <route-id> --revision <revision> --format jsonRoute 返回选中的节点及其调用路径、Action、一个空的 commandPlan（Agent Action 不运行命令）、必需的资源——Skill 和 resources/procedure.md，每项都以绝对文件路径给出，带有内容摘要和 readState: read-required——以及 afterAction: {evaluate: true, recordNode: "main/work"}。如果期间某个 Provider 文件或输入发生了变化，CLI 会拒绝这个过期的修订号（revision），而不是返回一个不匹配的计划。
由于 Skill 已经绑定了 Provider、Graph 和 Entry，仅凭 Skill 也能完成同样的 Evaluation：
npx @c4a/agent-graph@0.3.0 --skill ./skills/getting-started/SKILL.md evaluate --format json4. 用 Run 跟踪长任务
npx @c4a/agent-graph@0.3.0 run start main --state ./runtime/run.json --workspace "$PWD"
# ... the Agent reads the required resources and does the work ...
npx @c4a/agent-graph@0.3.0 run record main/work completed --state ./runtime/run.json
npx @c4a/agent-graph@0.3.0 run status --manifest ./provider.yaml --state ./runtime/run.json --format json记录时使用 afterAction.recordNode 给出的确切键。run record 会提醒你，记录的 Outcome 并不能证明 Facts；run status 会再次评估：对于入门项目，它现在返回 statusCode: complete 和 outcome: completed。在真实的 Graph 中，历史上的 completed 不能覆盖缺失的 Fact 检查；下一次 Evaluation 可能会转向校验或恢复。见 运行与恢复。
5. 构建可迁移的产物包
npx @c4a/agent-graph@0.3.0 build ./dist/provider --format json
npx @c4a/agent-graph@0.3.0 --manifest ./dist/provider/manifest.json validate产物包只包含可达的 Provider 文件、一个规范化的 provider.yaml，以及一个 manifest.json，其中记录每个文件的摘要、Graph 依赖索引和整体摘要。测试不会被打包，也不会写入源机器上的任何绝对路径，因此产物包可以随你自己的包一起分发。