agent-graphSAFE
Graph Engineering for Agent Skills: a specification and toolchain for dynamically discovering context and building observable, testable, and recoverable agent workflows.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://github.com/context4ai/agent-graph/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@c4a/agent-graph) [](./package.json) [](./LICENSE)
Agent Graph is a work-contract layer for Agent Skills. You describe a workflow as a small graph of steps; at runtime it reads the current facts and tells an Agent what to do next, which files to read for that step, and what proves the step is done. It never calls a model itself.
Agent Graph coordinates the work, not the Agents. It does not invoke models, assign Agent identities, transport shared mutable state, or schedule parallel workers. Existing Agents and hosts consume its fact-grounded Routes and hold the execution boundary.
Agents usually have enough knowledge. The harder problem is knowing which part applies now, which action is legal next, what proves that action is complete, and where to resume after an interruption. Making the prompt longer does not solve this reliably.
Context should be discovered, not accumulated. The plan is explicit; the path is selected from current reality.
When to use it: Not every Skill needs a Graph; keep a short, single-session task in SKILL.md. Adopt Agent Graph when a host can supply trustworthy external facts and the work truly needs verifiable completion, cross-session recovery, or testable routing and human gates.Documentation · 简体中文 · User manual · Graph Engineering · Contributing · Development
A simple example
Suppose an Agent has one job:
a15a366b7b6bOBSERVED · 2026-10-14Install
Commands as the repository documents them. They are shown, not run.
git clone https://github.com/context4ai/agent-graph.git
npm install --save-dev @c4a/agent-graph # authoring and CI
npm install @c4a/agent-graph # embedded SDK host
git clone https://github.com/context4ai/agent-graph.git
npm install --save-dev @c4a/agent-graph # 编写与 CI
npm install @c4a/agent-graph # 内嵌 SDK 的宿主
Host compatibility
What the documentation claims. We have not run a compatibility test.
| Host | Status | Notes |
|---|---|---|
| codex | mentioned |
What it tells the agent
The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.
--- name: consumer-a description: Resolve a shared Agent Graph provider through the host registry. metadata: agent-graph: provider:shared.provider agent-graph.graph: main agent-graph.entry: default --- # Consumer A Ask the host to resolve `shared.provider`, then consume the selected route.
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (3 observation(s))
- Network
- none-observed
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (7)
.nojekyll
agent-graph: path:../../provider.yaml
const skillName = await bindImportedSkill(copiedSkill, "path:../../provider.yaml", id, "default");
- Added Skill binding: Provider \`path:../../provider.yaml\`, Graph \`${id}\`, Entry \`default\`import { loadProvider, runGraphTests } from "../../src/index.js";const root = resolve(import.meta.dir, "../../examples", name);
@eslint/js, @types/bun, @types/node, ajv, ajv-formats, commander, eslint, typescript
Gates applied: no_behavioural_pass.
a15a366b7b6bfull audit observations/trust-audit/skill/context4ai__agent-graph.json · Report an issue / request a re-scanAudit history
Every audit this skill has had.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-14 | a15a366b7b6b | SAFE | B | 89 | first audit |
Questions
What does the agent-graph skill do?
Graph Engineering for Agent Skills: a specification and toolchain for dynamically discovering context and building observable, testable, and recoverable agent workflows.
Is agent-graph safe to install?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean skill reads B.
What can agent-graph access on my machine?
The audit observed that it runs shell commands and reads or writes files. Each of those is consistent with what it says it does. Secrets in the source: none found.
Which assistants does agent-graph work with?
Its documentation mentions codex. That is what the text claims, not a compatibility test we ran.
How current is this page?
The grade is for one exact copy of the source (a15a366b7b6b), read on 2026-10-14. The repository is watched, and a new audit runs when it changes — this is the first audit.