Graph Engineering for AI agents

Graph Engineering is the practice of designing an AI system as explicit, inspectable graphs instead of one opaque agent loop. Nodes represent agents, tools, deterministic steps, artifacts, decisions, policies, or evaluations. Edges define dependency, routing, provenance, authority, and feedback.

The phrase is new and still carries several overlapping meanings. In current agent systems it usually refers to one or more of these layers:

1. Execution graphs — state, nodes, fixed or conditional edges, parallel branches, loops, interrupts, and termination.
2. Knowledge or context graphs — entities, relationships, memories, and the provenance used to assemble context for the next action.
3. Evidence graphs — the connection from an instruction to an agent, tool call, approval, artifact, evaluation, and outcome.
4. Improvement graphs — feedback loops in which metrics, evaluators, policies, humans, and rollback paths constrain one another.

Revka is graph-engineered across all four layers. It is not merely a visual DAG editor and it is not a GraphRAG library with an agent UI attached.

The four graphs in Revka

Execution graph

Declarative workflows define typed steps and depends_on edges. The validator rejects broken references and cycles, then topologically orders the graph. Conditional routes, guarded goto loops, parallel joins, map-reduce, supervisors, group chat, handoffs, and human gates are explicit runtime primitives.

Versioned knowledge graph

Kumiho stores items as immutable revision chains connected by typed edges. Workflows, sessions, goals, skills, artifacts, outcomes, trust records, and provenance remain addressable by revision-aware kref values.

Evidence graph

Workflow state, RunLog JSONL, tool calls, approvals, outputs, artifacts, costs, trust outcomes, and the SHA-256 audit chain create a traceable path from declared intent to observed result.

Reactive graph

A Kumiho revision tag can emit revision.tagged and launch matching downstream workflows. Work can therefore advance because graph state changed, without an external cron job or glue webhook.

This gives Revka two coupled forms of state: the execution state of the workflow currently moving through its nodes, and the knowledge state that persists across runs. The output of one can revise the other; a revision can in turn trigger the next graph.

What the source actually implements

Graph Engineering capability	Revka implementation
Explicit nodes and edges	Typed StepType values and depends_on edges in operator-mcp/operator_mcp/workflow/schema.py
Graph validation	Duplicate-ID checks, dependency validation, cycle detection, and topological ordering in workflow/validator.py
Branching and cycles	conditional and guarded goto steps with bounded iteration
Parallel topology	parallel with all, any, or majority joins; map-reduce fan-out; dependency waves
Human control nodes	human_approval and human_input pause and resume workflow state
Durable continuation	Checkpoints preserve running, failed, and paused state for resume or retry
Multi-agent edges	Supervisor delegation, group chat, structured handoff, and HANDED_OFF_TO provenance edges
Versioned graph state	Kumiho items, immutable revisions, artifacts, bundles, typed edges, and revision tags
Reactive dataflow	on_kind + on_tag triggers launch workflows from Kumiho revision events
Verifiable evidence	Per-agent RunLog JSONL plus a SHA-256 chained audit log with verification
Feedback	Outcomes update agent trust; trust can inform later supervisor selection and refinement behavior

Source-grounded positioning

These are current runtime behaviors, not a future architecture diagram. The canonical implementation lives in the Revka repository, especially the workflow schema, validator, executor, event listener, Kumiho integration, and security audit modules.

Where Revka is ahead of a typical agent graph

Many graph runtimes stop at execution topology: state + nodes + routing. Revka adds operational continuity around that graph:

• The graph remembers its own history. Workflow definitions and outputs can be pinned to immutable Kumiho revisions instead of only the latest state.
• The knowledge graph is active. Revision tags can become workflow triggers; memory is both substrate and event source.
• Provenance is operational data. Handoffs, artifacts, outcomes, trust, and run records remain connected instead of disappearing into a trace viewer.
• Governance is in the topology. Approvals, bounded loops, allowlisted tools, checkpoints, retries, E-Stop, and policy surfaces are first-class.
• Evidence is independently verifiable. The audit chain detects later modification rather than treating observability logs as unquestioned truth.

That combination — execution graph + versioned knowledge graph + reactive edges + audit evidence — is Revka’s strongest Graph Engineering distinction.

Honest gaps and boundaries

Revka should not claim that every graph-shaped AI problem is already solved.

• Not a GraphRAG indexing engine. Revka does not itself run Microsoft GraphRAG-style entity extraction, community detection, hierarchical community summaries, or global/local graph retrieval. Those systems can be integrated as tools or data sources.
• No general reducer-based state API. The workflow DSL has structured outputs, variables, and typed step configuration, but it is not a drop-in equivalent to LangGraph’s arbitrary shared-state schemas and reducers.
• Resume is not full time travel. Revka checkpoints support crash recovery, approval continuation, and retry. It does not currently expose a general UI or API for forking execution from any historical checkpoint and replaying an alternate branch.
• Graph-wide evaluation is early. Trust scores and quality checks provide feedback, but causal credit assignment, frozen evaluation anchors, counter-metrics, and graph-level optimization remain areas to deepen.
• The graph planes are coupled, not one universal graph. Workflow topology, Kumiho knowledge, RunLogs, and the audit chain have deliberate boundaries. A unified query spanning every plane is not yet a single built-in language.

These are useful product boundaries: Revka is a governed runtime for building and operating graph-engineered agents, not a claim to replace every graph database, retrieval pipeline, evaluator, or state-machine library.

How this differs from adjacent ideas

Term	Primary concern	Relationship to Revka
Prompt engineering	Instructions inside a model call	Prompts live inside explicit workflow nodes
Loop engineering	Keeping one agent acting, observing, and correcting	Loops are bounded nodes or subgraphs inside the larger system
Agent orchestration	Coordinating models, tools, and agents	One plane of Revka’s Graph Engineering model
GraphRAG	Building/querying a knowledge graph for retrieval	Complementary; can supply context to Revka workflows
Context graph	Persisting entities, relationships, and reasoning traces	Kumiho provides Revka’s versioned context/knowledge graph
Graph Engineering	Designing execution, knowledge, evidence, and feedback topology	The umbrella discipline Revka operationalizes

External technical references

• LangGraph Graph API — state, nodes, edges, conditional routing, parallel supersteps, interrupts, and commands.
• LangGraph persistence — checkpoint-backed human-in-the-loop and fault-tolerant execution.
• Microsoft GraphRAG overview — entity/relationship extraction, communities, summaries, and vector embeddings.
• Neo4j Agent Memory — graph-native agent memory and context graphs.
• Graph Engineering beyond single feedback loops — work graphs, improvement graphs, counter-metrics, governance, and external anchors.

Continue exploring

Workflow overview The declarative execution graph and runtime lifecycle.

Graph data model Items, immutable revisions, artifacts, typed edges, and krefs.

Runs and approvals Checkpoints, pause/resume, retries, and human gates.

Audit logging The tamper-evident chain and verification surface.