Agent Graph

Agent Graph is a graph engineering workspace for designing, coordinating, and observing multiple agents without leaving Visual Studio Code.

Requires VS Code or Code Server 1.127 or newer with a Node 22.19-or-newer extension host.

See the whole system

Open Agent Graph from the Activity Bar to see how your agents connect and how work moves between them. The graph canvas gives every agent a clear place in the workflow—from orchestration and research to implementation, review, and delivery.

The sidebar is divided into Chat, Projects, Agents, and Graph. Chat opens the system-scoped Manager conversation, Projects manages named registered folders, Agents is the compact roster, and Graph shows routing across the full subview.

Features

• Explore agents and their connections on an interactive graph canvas.
• Ask system-level questions, manage the global roster, or dispatch a task graph from the Manager chat above Projects. Its history is kept under ~/.agent-graph/chatroom, with system tickets under ~/.agent-graph/issues.
• Register project folders from the Projects view with the native folder picker.
• Rename or remove registered projects from their rows, and open each Manager Agent chatroom or issue list in editor tabs. Removing a registration keeps the workspace and Agent Graph history.
• Restore open Chatroom and Issues editors after a browser refresh or window reload.
• See the Manager Agent's ready, working, or error state from its green, yellow, or red status dot.
• Keep posting while the Manager Agent is busy; project messages are saved immediately and consolidated into a fair project-scoped turn without changing queue priority.
• Drop files onto the chat composer or use its attachment button; uploads appear as #filename references and are stored privately for the Manager and graph workers.
• See a temporary Manager Agent Working or Queued row directly in the transcript while a turn is active.
• Restore project conversations from text-only daily history files.
• Preserve reusable project hints, prohibitions, and mandatory rules in dedicated knowledge files.
• Browse the global roster from Agents and its full-width routing canvas from Graph.
• Start with a connected architect, backend, frontend, review, test, and deployment template graph.
• Run a persistent Manager Agent session directly inside the extension host.
• Read sanitized Markdown and fenced Mermaid diagrams directly in project chat.
• Track newest-first project tickets, unfold activity cards with planned graphs, and expand dispatcher output into readable issue history.
• Configure one production vLLM Responses endpoint and API key for both the Manager Agent and graph workers without touching local Codex authentication.
• Run every graph worker in the bundled local Docker image, with the registered project and private agent memory writable and project issues read-only.
• Ask the Manager Agent to inspect or rebuild that image with validated extra Debian packages and global npm CLI tools while built-in Codex remains fixed.
• Let the Manager Agent query the current safe vLLM model catalog through runtime MCP before assigning worker models.
• Let the Manager Agent translate user requests into detailed issues with an execution graph built for each issue.
• Cancel queued or running tickets from the Issues editor, or ask the Manager Agent to stop one explicitly; only that issue's Docker worker is terminated.
• Let the Manager Agent inspect the active project read-only, then send actionable work to runtime MCP instead of modifying the workspace itself.
• Show the Manager Agent's useful response in chat while keeping issue-creation tool details in the issue audit trail.
• Show stable issue numbers in chat headers without exposing internal issue IDs or repeating task titles.
• Run graph agents sequentially in the registered project path, show concise outcomes in chat, and keep detailed work reports and handoffs in each issue's readable History.
• Let each worker assign one or more allowed next workers with a specific prompt while dispatcher validates and queues every handoff.
• Consolidate prompts from multiple workers when their target is still queued, while allowing bounded loops to revisit working or completed agents.
• Give each worker its assigned role and only the effective intersection of its roster allow_nodes with the issue-selected team. Workers may recommend one or multiple useful next agents; runtime or invalid-routing errors block for Manager review.
• Keep graph writes and issue reporting behind the private runtime API; only the Manager Agent can create issues.
• Route Manager Agent and process control-plane operations through private structured MCP tools.
• Give the Manager Agent packaged instructions for roster changes, issue construction, and durable knowledge capture.
• Model each agent's permitted dynamic routes through one allow_nodes list.
• Inspect an agent’s role, model, and node identifier.
• Add agents through the Command Palette.
• Keep the global agent roster in a stable, deterministic agents.json format.
• Refresh runtime state without leaving the graph.
• Use the interface with light, dark, and high-contrast VS Code themes.
• Navigate graph nodes with the keyboard.

How to use

1. Set up your vLLM endpoint and API key. Select the Agent Graph icon in the Activity Bar, open Settings from the Projects header, and enter the vLLM URL and key. Select Connect, Load the available models, then Save the Manager Agent model and reasoning depth. Leave the URL blank to use https://api.openai.com/v1.
2. Open Chat, then select Manager Agent. Ask the Manager Agent to query the current agents and graph, explain how work is routed, or optimize the Agent Graph for your workflow. It can also create a system task graph—such as asking every agent to report its status—without adding a project. The Manager Agent can inspect the live model catalog and roster and apply a validated, atomic graph update for you.
3. Open Agents to review the resulting roster and model assignments. Open Graph to inspect its routes, or select Refresh there to rebuild and fit the layout.
4. In Settings → Docker, confirm the Docker path and select Save. Agent Graph checks the daemon and builds its versioned Codex worker image.
5. Add a project from Projects, then use its Chatroom for project work and its Issues view to follow dispatched tasks and agent activity.

Docker is the only graph-worker runtime. The first image build can take a few minutes. Workers use the same configured vLLM endpoint through a private in-container compatibility proxy. The provider key is removed before Codex starts, and only the two required shell tools are exposed to graph workers. Plain HTTP worker endpoints must use an explicit private-network IP; use HTTPS for every other endpoint.

Agent Graph loads its roster and project registry only from ~/.agent-graph. The registry lives at ~/.agent-graph/projects/projects.json, beside one path-safe scope folder per registered project. Each scope keeps daily chat in chatroom/, per-issue JSONL in issues/, durable project notes in knowledge/, and runtime execution artifacts. It does not touch the open workspace during activation, refresh, or project registration. Graph workers use the registered project path as their working directory only while executing an issue.

The Manager Agent continues its session from ~/.agent-graph/sessions and uses the Agent Graph root as its working directory. It does not select the open workspace implicitly.

You can also open the Command Palette and run:

• Agent Graph: Open Agent Graph
• Agent Graph: Add Project
• Agent Graph: Open Settings
• Agent Graph: Open Manager Chat
• Agent Graph: Add Agent
• Agent Graph: Refresh Views
• Agent Graph: Open Agent Roster

Local runtime access

Agent Graph provides an MCP Streamable HTTP endpoint at http://127.0.0.1:47831/mcp for trusted local clients. Read the active URL and random bearer token from the owner-only ~/.agent-graph/status.json, then send the token as Authorization: Bearer <token>. The port is configurable through agentGraph.apiPort.

MCP is the canonical contract and control plane for both the built-in Manager Agent and trusted external client agents. Both use the same runtime tools, schemas, validation, and persistence services. The Manager uses an in-process MCP connection; external clients use authenticated Streamable HTTP. The dispatcher remains the deterministic execution authority, and Docker graph workers never receive MCP access or its token.

Trusted MCP clients and the Manager Agent can call list_projects to read each registered project's stable ID, display name, and workspace path. Adding, renaming, or removing a project remains an explicit sidebar action. They can use list_chat for bounded project/root conversation history, list_issues for ticket summaries, and get_issue for one ticket's readable details. Runtime resolves all paths from project and issue IDs.

The same loopback server retains these JSON compatibility endpoints:

• POST /add_agent adds one canonical agent object.
• POST /del_agent deletes the agent named by { "name": "..." }.
• POST /chat sends a project-scoped user message to the shared Manager Agent and returns its reply.
• POST /report_issue appends a structured agent report to an existing issue.
• POST /close_issue closes an existing completed or blocked issue with a resolution.
• POST /update_knowledge appends a classified durable note for a registered project.

Every MCP and compatibility JSON control request requires the same random 256-bit activation token. The non-secret GET /healthz readiness/version probe is the only unauthenticated route. The status file also keeps the configured vLLM URL, API key, loaded model catalog, Manager Agent default model, depth, and Docker worker image. Runtime API/MCP entries are refreshed each activation and removed when the server stops; the vLLM settings remain. Treat both keys as secrets. The runtime is the only writer for issue graphs, chat, issue, error, and status files.

Graph workers never receive the API token. The Manager Agent creates issues through its embedded tool using a compact team-and-route plan. Runtime fills the selected agents' saved model, depth, and role and attaches the resulting immutable execution graph before the dispatcher starts. That issue snapshot is the only execution graph; Agent Graph does not create a reusable graph file in the project workspace.

The Manager Agent can also rebuild the global roster atomically through the private build_graph MCP tool. allow_nodes lists the agents each worker may assign next. For each issue, runtime intersects that roster list with the agents selected for the issue and passes only the resulting effective list to the current worker. The worker may choose one or multiple useful targets and must give each a specific prompt. Issue execution uses a durable SQLite queue: prompts merge while a target is queued, and bounded loops may schedule an agent again after it starts. It can inspect the Codex worker image through get_worker_image_status and rebuild it through build_worker_image. The validated additional tool catalog is persisted in agents.json as prebuilt_tools; Codex and the fixed entrypoint are always included. The baseline worker pins Codex 0.153.4 and also includes Node.js/npm, Python, uv/uvx, Git, ripgrep, curl, and native build tools.

Agent Graph does not read or change your normal Codex login. Graph workers use an ephemeral container Codex home and the configured vLLM Responses endpoint. Project workers receive /workspace and their private /agent folder read-write. Private memory is organized into durable memory, reusable hints, and work-specific notes; project /issues remains read-only. Root-system workers receive an ephemeral /workspace, private /agent, and root /issues read-only; no host workspace is mounted. Status, auth, and the rest of the Agent Graph root are never mounted.

Settings

• agentGraph.layout controls whether the graph uses a flow or radial layout.
• agentGraph.showInactiveAgents controls whether inactive agents appear on the canvas.

Agent Graph is at the beginning of its journey toward a complete multi-agent engineering platform. Future releases will expand execution telemetry, orchestration, and richer graph editing around the embedded manager runtime.