Agentic Graph Specification

What it is

An Agentic Graph is a directed acyclic graph where every node is a bounded agentic loop, meaning one unit of work an agent runs end to end, and every edge is a control-flow dependency. The specification is an open, implementation-neutral format for writing that graph down, currently at version 1.0 with maintenance releases, under Apache 2.0.

A node is not a prompt and it is not a function call. It carries a precise brief, typed inputs and outputs, success conditions, a normalized capability tier, required tools, permissions and budgets, and failure handling. Graphs are written in YAML or JSON, with the two encodings equivalent.

The four problems it addresses

The specification is unusually clear about what it is fixing, and the four consequences it names are worth taking one at a time because each one is familiar.

You cannot review the plan before paying for it

A harness plans internally. By the time you see the decomposition, the tokens are spent and the work is done. If the plan was wrong, you find out afterwards. Writing the plan first moves review to the point where it is cheap.

You cannot move it

A decomposition produced by one harness lives in that harness's memory in that harness's shape. It is worthless to another. Everything the planning step figured out is discarded at the session boundary.

Done is whatever the model says

Without declared acceptance criteria, completion is a claim. An agent that says it finished has asserted something nobody checked. Declaring success conditions in the document turns completion into a check.

Every task gets the same model

Without a declared capability demand, a harness either sends trivial steps to an expensive model or sends the one genuinely difficult architectural decision to a cheap one. Both are common and both are invisible.

Each of these is a consequence of the plan being implicit. Making it explicit addresses all four with one change, which is the sign of a well-chosen abstraction.

What a node actually declares

The node is where the specification does its work, and the field list is more opinionated than a generic workflow format would be.

• A precise brief. What to accomplish, written so that an agent which has seen nothing else can act on it. This constraint is the useful part: a brief that only makes sense in the context of the previous node will fail the moment execution is parallel or resumed.
• Typed inputs and outputs. What it receives and what it must produce, with declared types such as a file set or a structured value. This is what allows a harness to check that a node produced something of the right shape rather than trusting a claim.
• Success conditions. Machine-checkable where possible, always human-readable, and evaluated by the harness rather than asserted by the model.
• A level of intelligence. A normalized capability tier plus hints, so a harness can route to an appropriate model without the graph naming one.
• Required tools, permissions, and budgets. The ceiling on what this node may do and what it may spend, declared per node rather than for the whole run.
• Failure handling. Retries with feedback, fallbacks, escalation, and human checkpoints.

Per-node permissions and budgets are the field group that most distinguishes this from an ordinary pipeline format. A graph where the implementation node may write source files and the review node may not is expressing an authority model, not just an order of operations.

Edges, decisions, and gates

Edges are control-flow dependencies, which makes the graph acyclic by construction and its execution order derivable rather than declared. Two node kinds deserve separate mention because they are where the format earns its place over a plain task list.

Decision nodes branch on an outcome. Ready or needs work, with different downstream paths. This is what lets a graph express remediation loops without becoming a cycle: the remediation path rejoins rather than looping back.

Gates hold for an explicit human decision. Placing a gate before the first irreversible action, or before an expensive parallel fan-out, is the single most valuable structural choice available in a graph.

The canonical example in the specification illustrates the pattern well: audit, then define an API, then a human approval gate, then three parallel implementation nodes, then verification, then a release-readiness decision, then a publish approval before any side effects. The gates are placed exactly where a person would want to look, which is before the expensive part and before the irreversible part.

Capability tiers without naming models

The intelligence field declares a normalized tier and optional hints rather than a model identifier, and this is a genuinely good design decision worth dwelling on.

A graph that names a specific model is stale the moment that model is deprecated, and it is unusable on a harness configured with a different provider. A graph that says a node requires frontier-level capability with code generation hints remains valid indefinitely, and each harness resolves it against whatever it has.

The economic consequence is the one the specification names. Declaring capability demand per node is what allows a harness to route the audit step to a standard model and the architectural decision to the strongest available. Without the declaration, the harness has no basis for the distinction and applies one model uniformly, which is wrong in one direction or the other on almost every node.

This is the same argument the models layer makes about tiering calls, expressed as a portable document rather than as configuration. The graph author knows which step is hard; the harness knows which models are available. Separating those two pieces of knowledge is what lets both change independently.

Success conditions and who evaluates them

The specification is specific that success conditions are evaluated by the harness rather than asserted by the model, and that constraint carries most of the weight of the whole format.

A model asked whether it completed a task will usually say yes. Not from dishonesty, but because assessing your own work against a criterion you also interpreted is not a reliable operation. Agentic systems that depend on self-reported completion accumulate silent failures: a step that half-worked is reported as done, and the next step builds on it.

Moving evaluation outside the model changes the character of the system. A condition that says the test suite passes, or that the output contains these fields, is checked by running something. A condition that is human-readable but not machine-checkable is at least written down, which means a reviewer knows what to look at.

The practical advice that follows is to write success conditions that are checkable wherever the effort is reasonable, and to accept human-readable ones elsewhere rather than skipping them. An unchecked criterion is still better than an unstated one, because it tells a reviewer what the node was supposed to achieve.

Failure handling as a declared field

Most workflow formats treat failure as an operational concern handled by the runtime. AGS puts it in the document, and the reason is specific to agentic work.

An agentic node fails in ways a deterministic step does not. It can produce output of the right shape that is wrong. It can fail a success condition it nearly met. It can fail for a reason that would not recur, such as a transient tool error, or for a reason that will recur every time, such as an impossible brief. Retrying blindly is correct for the first and wasteful for the second.

Declaring the handling per node lets the document express which case it expects. Four mechanisms cover most of it:

• Retry with feedback. Not a plain retry. The failure information from the previous attempt goes into the next one, so the agent knows what it got wrong. A retry that repeats the identical prompt usually produces the identical failure.
• Fallback. An alternative approach when the primary one does not work. Often a different capability tier, since some failures are capability failures.
• Escalation. Handing the problem to a different node, or to a stronger tier, rather than continuing to attempt the same thing.
• Human checkpoint. Stopping and asking, which is the correct handling for anything where a wrong automated recovery would be worse than a delay.

Writing this down has a secondary benefit that shows up during review. A node with three retries, a fallback to a stronger tier, and an escalation path is expensive in the worst case, and seeing that in the document prompts the question of whether the brief should be clearer instead. Failure handling declared in a plan makes the cost of unreliability visible; failure handling buried in a runtime does not.

What you learn before running

A validated graph can be planned without executing anything, and the plan answers questions that are expensive to answer afterwards.

• Dependency order. What runs when, and what can run in parallel.
• Reachability. Which nodes are actually reachable from the declared entry points, which surfaces orphaned work.
• Worst-case bounds. What happens if every retry path is taken, which is the number that matters for a budget rather than the happy path.
• Cost and tier summary. How much of this needs an expensive model, and roughly what the run will cost.
• Unsupported features. What this environment cannot do with this document, reported explicitly rather than discovered at step nine.
• A digest. A stable identifier for the plan, which is what makes it citable in a review and comparable across revisions.

The last two are the ones a broker cares about, and they are why read-only planning is valuable even in a component that never executes graphs.

When a graph is worth writing

Structure has a cost, and applying it everywhere is a common way to make an idea useless.

A graph earns its place when the work has real structure worth reviewing: branches, approval points, parallelism, and consequences. Release processes, migrations, incident response, and multi-stage builds all qualify. So does any work expensive enough that reviewing the plan before paying for it is worthwhile.

A graph does not earn its place for conversational or exploratory work. A question with an unknown shape cannot be decomposed in advance, and forcing it into nodes produces a document that is wrong by the second step. That work belongs in an ordinary agent session.

The honest tension is that explicit structure reduces the room an agent has to improvise, which is exactly the point in high-consequence work and exactly the loss in exploratory work. Reserving graphs for processes where the steps genuinely matter, and leaving open-ended work open-ended, is a better rule than treating either style as correct everywhere.

Where it fits in an open stack

AGS occupies the work-shape position in the standards layer, alongside skills for capability, MCP for reach, and profiles for identity.

The precedent worth naming is from data engineering, where separating pipeline definitions from execution engines turned out to be enormously valuable. A pipeline as a document can be reviewed, versioned, diffed, run by different engines, and reasoned about without running it. The same argument transfers directly: when the shape of the work is a document rather than a call stack, you can think about it before it happens.

It also composes with profiles in a specific way worth noticing. A profile says what an agent may do in general. A graph node says what this particular step requires. A harness granting the intersection of the two produces per-step authority that is narrower than the agent's standing permissions, which is stronger than either mechanism alone.

Gotchas worth knowing

• Over-decomposition is the common mistake. Twenty nodes where four would do produces coordination overhead and context loss at every boundary. A node should be a unit of work an agent can complete, not a single action.
• Briefs that assume context will fail. The requirement that a brief stand alone is not stylistic. A node may run in parallel with the ones that would have provided the context.
• Unchecked success conditions are documentation. Useful documentation, and not a check. Know which of yours are which.
• Budgets need to reflect the worst case. Retries and fallbacks multiply cost. Plan against the worst-case bound rather than the expected path.
• Gates in the wrong place. A gate after the expensive fan-out has already spent the money. Place them before irreversibility and before cost.
• Graphs go stale. A document referring to tools or systems that changed is confidently wrong. Validate them in continuous integration the way you would any other artifact.
• Harness support varies. Some implementations validate and plan without executing. Check what your runtime actually does with a graph before depending on it.

How it scores on openness

• Replaceable. Strong. Apache licensed, implementation-neutral by design, with a published schema and support libraries.
• Inspectable. Very strong. A graph is readable YAML that a reviewer can follow without running anything, which is the format's central claim.
• Portable. Strong. Capability tiers rather than model names, and declared rather than assumed tool requirements, are both deliberate portability choices.
• Bounded. Strong. Per-node permissions, budgets, and human gates express authority as part of the plan.
• Grounded. Partial. Typed inputs and outputs and harness-evaluated success conditions ground completion in checks rather than claims.
• Auditable. Very strong. A digest-identified plan, reviewed before execution, is an unusually good audit artifact because it records intent rather than only outcome.

What it is not

AGS is not an execution engine. It describes work; harnesses run it. A graph is inert on its own, which is what makes it portable.

AGS is not a general workflow language. It is specifically about decomposing work into agentic loops, with fields such as capability tier and success conditions that only make sense in that context. Using it for deterministic pipelines would be a poor fit in both directions.

AGS is not a replacement for an agent's own planning. Within a node, the agent still decides how to proceed. The graph bounds the unit of work, states what success means, and declares what the node may use. What happens inside remains an agentic loop.