A capable coding model can inspect a repository, change files, and run tests. But a real engineering workflow needs more than one capable turn. It needs a way to decide who works next, preserve evidence, constrain permissions, recover from failure, and show the human what is happening.
That gap is the reason I built Agent Graph. It treats the language model as an intelligent participant inside a software-controlled system—not as the system itself.
One chat window is not an engineering system
A single assistant can answer a question quickly. Complex work is different. Architecture, implementation, database changes, security review, repository compliance, testing, and deployment readiness have different responsibilities and different definitions of success.
If these responsibilities are placed into one long conversation, the context grows while ownership becomes less clear. Earlier instructions are replayed, intermediate output is mistaken for current work, and the model may decide that it completed a task that another specialist still needs to verify.
Agent Graph converts the conversation into a ticket. The Manager Agent selects the required specialists, writes one focused assignment for each, chooses a start agent and a final quality gate, and submits the issue through MCP. From that point forward, the Dispatcher owns execution state.
MCP is the control plane
The built-in Manager Agent and trusted external agents use the same MCP tools. They can inspect models and the roster, create or reopen issues, build a graph, read chat and issue history, update durable knowledge, and inspect worker-image health.
This matters because the agent does not need private knowledge of extension internals. MCP is the boundary. Inputs have schemas. Runtime state has one owner. A model can propose a plan, but only the runtime can validate it, persist it, and execute it.
Dynamic graph execution, with a loop that stays bounded
A static pipeline is easy to understand but often too rigid. Real engineering work discovers new needs. A backend agent may ask for database review. A reviewer may find a defect and return the issue to architecture. A final agent may decide that the implementation needs one more correction pass.
Agent Graph therefore uses a dynamic graph. Each agent has a roster-level allow_nodes list. Each issue selects a smaller team from that roster. Before a worker starts, the Dispatcher computes the overlap: only agents that are both allowed by the current worker and selected for this issue become possible next workers.
The worker receives that effective list with short role descriptions. It may return zero, one, or several {agent, prompt} suggestions. Those are proposals—not commands. The Dispatcher validates every target and prompt before changing the queue.
Every Manager-selected specialist enters the durable issue queue with its own focused assignment. An early worker cannot silently skip the rest of the team.
The Dispatcher launches one detached Docker worker and captures its structured result and machine stream.
Each proposed next agent must belong to the issue and the current agent’s effective allow-list.
If a target is waiting, the new focused prompt is consolidated into that queued turn. If it is already working or previously completed, a new queue entry enables a deliberate loop.
The final agent reviews evidence and returns either solved or a focused correction for the start agent. The Dispatcher schedules the bounded loop and repeats final review.
Three controls prevent a dynamic graph from becoming an uncontrolled conversation: max_steps bounds the whole run, max_agent_visits bounds repeated visits to one specialist, and max_rework_cycles bounds final-review bouncebacks.
Latest assignment first; context only when needed
Another source of drift is excessive context. If every worker receives the complete transcript, it may repeat prior output instead of doing its own work. Agent Graph puts only the newest focused assignment under Your work is. Earlier discussion stays in reference files with a description of when each file is useful.
Direct response
Greetings, expertise checks, and readiness reports receive no filesystem paths. The agent answers from the assignment and role, while the Dispatcher ignores accidental handoff proposals.
Evidence-based work
Implementation and final review can consult the workspace, issue discussion, related tickets, chat history, and private same-agent notes as optional evidence.
Each roster role also has a protected canonical instruction file outside the worker mount. Before a new worker starts, the Dispatcher restores the visible copy. A worker can write private notes, hints, and memory, but it cannot permanently rewrite its own governing role.
Three histories for three audiences
Raw model streams are useful for debugging but poor reading material. A short chat message is useful to a human but may omit evidence needed by the next specialist. Agent Graph separates them:
- Chatroom: concise, useful updates for the human.
- Issue JSONL: Manager instructions, Dispatcher routes, agent reports, decisions, and handoff context for later agents.
- Raw issue log: machine events, commands, tool calls, provider output, and failures for diagnosis.
The user sees a readable conversation and ticket. The next agent gets durable engineering context. The runtime keeps the complete audit trail.
Docker is the execution boundary
Graph workers run as pinned Codex CLI processes inside a versioned Docker image. A project issue mounts its workspace read/write, its issue archive read-only, and the current agent’s private directory read/write. System-level issues get ephemeral scratch rather than a host project.
The same runtime supports an OpenAI-compatible vLLM Responses endpoint or an isolated Codex subscription. Subscription credentials live under the Agent Graph root and never reuse or modify the user’s normal Codex home. Docker bridge and host networking are explicit settings because the correct route depends on the local infrastructure.
Failure belongs to the runtime, not the story
Provider streams disconnect. Schemas are rejected. Containers outlive an extension host. A worker asks for context that does not matter. These are orchestration cases, and the Dispatcher should handle them without making the graph agent understand the orchestration system.
Workers run detached so the extension can reattach after reload. Queue state is durable. Output schemas are validated before launch. Runtime failures are classified and reported to the Manager. A blocked issue stays inspectable and can be reopened with a corrected graph rather than copied into a chain of retry tickets.
Agent Graph and Agent Runner
Agent Runner and Agent Graph share a belief in deterministic state around probabilistic models, but they focus on different operating patterns. Agent Runner is an always-on server workspace with mailboxes, groups, agenda, and long-running coordination. Agent Graph is an editor-native, issue-scoped execution system: a visible team graph, a durable per-issue queue, isolated workers, explicit final review, and MCP as the control plane.
What version 0.1.6 demonstrates
The current release is intentionally serialized: one active issue and one active graph worker at a time. This makes ordering, recovery, resource ownership, and human observation clear. Dynamic branching and looping still work, but they become queue operations rather than uncontrolled parallel conversations.
The release test rebuilds the extension and exact Docker image, reloads the MCP runtime, discovers the tool contract as an external client, and sends a root-system issue through every configured specialist. The issue passes only when every required agent contributes and the final agent returns a solved verdict.
That is the larger idea behind Agent Graph. Multi-agent engineering should not mean giving several models a shared transcript and hoping collaboration emerges. It should mean constructing an environment where roles are explicit, evidence is durable, routes are validated, loops are bounded, and the human can see the system work.