ACX AGENT GRAPH · acx.agent-graph/1

Give the team a shared information architecture¶

A CAL says what happens next. An Agent Graph says who owns the context, who can direct whom, where reports return, and where separate loops meet.

Describe the real shape of collaboration without turning it into another task board. Agent Graphs connect roles, knowledge responsibilities, reporting routes, and whole workflows in one signed, portable artifact.

Read the graph Author in Studio Compare with CAL

Read the graph¶

This example connects a Product Owner, a research council, and a developer team. The PO sends a delivery brief to the developers; developers return status and blockers. Research evidence and delivery reality arrive through separate loops, then converge into one product decision stewarded by the PO.

Product Ownerdirects →Developerscarries the delivery brief
Developersreport →Product Ownerreturns status, verification, and blockers
Product Ownerrequests →Researcherscarries the product intent and decision question
Researchersadvise →Product Ownerreturns evidence, uncertainty, and alternatives
Discovery loop + delivery loopconverge →Product decisionbounded synthesis; Product Owner is steward

Solid responsibilities, fuzzy descriptions: the moving routes show information flow, not task execution. The complete text equivalent follows.

Text equivalent¶

From	Relationship	To	Knowledge carried	Return / result
Product Owner	directs	Developers	delivery brief	developers report through the declared return route
Developers	reports to	Product Owner	progress, verified outcomes, risks, blockers	product context stays current
Product Owner	requests from	Researchers	product intent and decision question	researchers advise through the declared return route
Researchers	advises	Product Owner	evidence, uncertainty, counterarguments	evidence becomes decision-ready
Discovery loop + delivery loop	converge at	Product decision, stewarded by PO	research evidence + delivery status	one bounded, recorded decision

The arrows form reporting cycles on purpose. They do not dispatch work. A host may listen for declared events and route messages, but the graph itself grants no tool access, permissions, budget, or runtime authority.

Why this is not another workflow¶

Task graphs are precise about execution order. Teams also need a slower-moving map of responsibility: who should know what, who may give direction, where a response must come back, and which person or agent reconciles conflicting signals.

Question	CAL (`acx.cal/1`)	Agent Graph (`acx.agent-graph/1`)
What happens next?	nodes, gateways, conditions, completion	out of scope
Who performs a task?	participant bound to each task node	actors describe durable team seats
Who owns context?	RAC says what must be available	knowledge modules name stewards and audiences
Who talks to whom?	handoffs implied by control flow	explicit routes with purpose, obligation, triggers, and returns
Where do loops meet?	inside one workflow graph	convergence joins whole CALs, external loops, or informal loops
Are cycles allowed?	only as bounded execution cycles	reporting cycles are expected; required direction chains stay conflict-free

Use a CAL for a repeatable process. Use an Agent Graph for the information architecture around one or many processes. Link them with loops[].workflowRef when a loop is itself a signed ACX Workflow.

The six building blocks¶

Actors¶

Logical seats — agent, human, group, service, or mixed. A fuzzy selector can describe suitable roles, capabilities, and traits without naming a particular person or machine.

Knowledge modules¶

Metadata about intent, decisions, evidence, status, risk, tacit context, or artifacts. Each module names its stewards and audience. Actual knowledge content is invalid here.

Routes¶

Typed relationships such as direct, report, advise, review, or escalate, plus an open relationship label, prose purpose, obligation, triggers, carried knowledge, and expected return route.

Loop bindings¶

Connect knowledge imports and exports to an ACX Workflow, an external process, or an informal loop. Participant aliases can be mapped to durable actor seats.

Convergence¶

At least two distinct loops meet at a named steward. A policy explains how inputs become new decision knowledge; wait time and synthesis rounds are bounded.

Limits¶

maxPropagationHops and maxFanout bound graph-wide propagation. Each convergence also declares maxWaitMs and maxRounds.

Author one: fuzzy where useful, strict where needed¶

The graph is deliberately fuzzy at the human boundary and strict at the reference boundary:

Fuzzy: actor descriptions, capability selectors, relationship labels, route purpose, success, cadence, and the 0..1 communication weight.
Strict: stable ids, known actor and knowledge references, structured event/interval/manual triggers, declared return routes, no self-routes, unambiguous participant bindings, conflict-free required direction, publisher + SemVer + digest-pinned ACX Workflow references in public graphs, and positive bounds.

A direction route with an explicit reporting return

{
  "id": "po-directs-developers",
  "from": "product-owner",
  "to": ["developers"],
  "intent": "direct",
  "relationship": "directs",
  "obligation": "must",
  "authority": "delegated",
  "purpose": "Translate product intent into a clear delivery brief.",
  "carries": ["delivery-brief"],
  "returns": ["delivery-status"],
  "triggers": [{
    "type": "event",
    "events": ["work.requested", "scope.changed"]
  }],
  "expects": {
    "via": "developers-report-po",
    "withinMs": 86400000
  },
  "weight": 1
}

The reverse route is a separate object. That keeps “PO directs developers” distinct from “developers report status to PO,” even though together they form a healthy communication loop.

A workflow binding pinned to exact signed bytes

{
  "id": "delivery-loop",
  "kind": "acx-workflow",
  "description": "The bounded build and review loop.",
  "workflowRef": {
    "publisherId": "io.github.example",
    "id": "ship-a-feature",
    "version": "1.0.0",
    "digest": "sha256:…"
  },
  "imports": ["delivery-brief"],
  "exports": ["delivery-status", "verification-evidence"]
}

The publisher, id, version, and digest identify one workflow. A registry gate resolves that exact coordinate and refuses a missing or mismatched dependency; it never substitutes a newer version.

Two loops converging into decision knowledge

{
  "id": "product-steering",
  "inputs": [
    { "loop": "discovery-loop", "knowledge": ["research-evidence"] },
    { "loop": "delivery-loop", "knowledge": ["delivery-status"] }
  ],
  "steward": "product-owner",
  "policy": {
    "mode": "steward-synthesis",
    "description": "Reconcile evidence, delivery reality, and product intent."
  },
  "outputs": ["product-decision"],
  "trigger": "When either loop reports a material, decision-ready change.",
  "limits": { "maxWaitMs": 3600000, "maxRounds": 2 }
}

Start with sentences, then add structure

Write “PO directs developers with the current delivery brief; developers report progress and blockers back” first. Turn the nouns into actor and knowledge ids, then add triggers, a return route, and bounds. The prose remains valuable: it is what makes the graph understandable to a new team and matchable by an agent host.

Knowledge is described, never embedded¶

An Agent Graph manages implicit knowledge responsibility, not the knowledge itself. A module may say:

“Decision-relevant research evidence, uncertainty, counterarguments, and source-quality notes.”

It may name researchers as stewards, the PO as audience, freshness intent, sensitivity, and a metadata-only locator. It cannot include the roadmap, source material, credentials, private messages, or decision content. A receiving environment resolves the description through RAC, OKF, MCP, an artifact, or a human.

This keeps one signed graph reusable across organizations without turning it into a data-exfiltration channel.

# Validate the graph; --publish also checks discovery metadata.
acx graph lint product-delivery.agent-graph.json --publish

# Sign the canonical graph with Ed25519 + DSSE/in-toto.
acx graph sign product-delivery.agent-graph.json \
  --publisher io.github.yourhandle \
  --out product-delivery.signed.agent-graph.json

# Verify before using or listing it.
acx graph verify product-delivery.signed.agent-graph.json
acx graph inspect product-delivery.signed.agent-graph.json
acx graph digest product-delivery.signed.agent-graph.json

# Preview the canonical registry path, then prepare the focused diff.
acx share graph product-delivery.signed.agent-graph.json --dry-run
acx share graph product-delivery.signed.agent-graph.json

The public artifact media type is application/vnd.acx.agent-graph.v1+json. Signing excludes only the top-level integrity, canonicalizes the rest with RFC 8785/JCS, hashes it with SHA-256, and binds its id, version, publisher, and signing time in an in-toto Statement carried by a single-signature DSSE envelope.

Published graphs use the immutable identity publisherId + id + SemVer + digest and path:

registry/graphs/<publisherId>/<id>/<version>.agent-graph.json

A remix can keep a signed lineage.parents[] reference to its source:

{
  "artifactType": "agent-graph",
  "publisherId": "io.github.original",
  "id": "product-delivery",
  "version": "1.0.0",
  "digest": "sha256:…",
  "relation": "remix"
}

Lineage preserves attribution. It does not transfer trust, namespace control, licensing permission, or runtime authority. Studio imports a signed graph as an unsigned draft, removes the old integrity block, and adds this pinned parent; signing stays local.

Guardrails worth remembering¶

A graph does not grant authority. authority: delegated describes a relationship; the host and operator still decide what an actor may access or change.
Actors are roles, not people. A selector describes a seat. Staffing that seat is a separate host decision.
Reporting cycles do not auto-dispatch. They describe expected information movement. A runtime must opt in to triggers and enforce graph limits.
Required direction stays unambiguous. For the same knowledge and recipient, there cannot be two conflicting mandatory directors or a mandatory direction cycle.
Convergence fails visibly. Missing or contradictory inputs follow the declared failure mode; bounds prevent silent waiting forever.
Public metadata stays public. The publish profile rejects secret-like values and private key material before the graph can be signed or shared.

Conditional Agentic Loops — signed execution order and completion contracts.
Loop & context policy — the bounded loop inside one cartridge.
Knowledge & OKF — metadata-first knowledge interchange.
Share ACX — the pull-request path for agents, workflows, and Agent Graphs.