Agent Pipeline Designer

Design, trace, and improve agent workflows.

Agent Pipeline Designer turns privacy-safe VS Code agent-hook events into a live workflow graph. It is a standalone, domain-neutral developer tool with no application-specific runtime dependency.

Install

Install Agent Pipeline Designer from the Visual Studio Marketplace, or run:

code --install-extension pipeline-designer.agent-pipeline-designer

The stable VSIX is also published on the project release page for manual installation and checksum verification.

What it shows

• Parent-to-subagent handoffs and nested custom-agent workflows
• Running, completed, stopped, READY, BLOCKED, PASS, and FAIL states
• Tool activity, changed/read file attribution, and validation outcomes
• Session timeline with source, agent, tool, and file filters
• JSON and Mermaid export for workflow review and design discussions
• Multiple event sources in multi-root workspaces
• A pannable graph canvas with a bottom-right 50–160% scale control that remains stable as the view is resized
• Desktop and VS Code for the Web extension hosts
• A standalone browser application with one-click detection, start, and open
• Workspace custom-agent creation and section-based .agent.md editing
• A localhost Copilot conversation that prepares reviewable custom-agent drafts
• Weighted role-to-role relationships with inspectable delegation triggers
• Pipeline and editable Agents workbenches inside the VS Code extension view
• Ordered @agent routing contracts with expected-versus-observed run status
• Review-only Copilot revision of existing and legacy agent files
• Registered/custom tool access editing and confirmed agent deletion
• Project-wide main-agent editing through .github/copilot-instructions.md
• Inline hover context for custom-agent and instruction file metadata, sections, routes, and managed blocks
• A GitHub-backed Gallery for integrity-pinned, declarative agent packages
• Project-owned pipeline publication with versioned payloads and reviewed registry submissions

The graph updates whenever a matching JSONL event log changes. Raw prompts, terminal commands, tool responses, and transcript contents are intentionally excluded from the event schema.

Select any agent node in the pipeline to filter Activity to only the actions attributed to that agent. The Activity header shows the selected agent name and action count; select the same node again or choose Show all to return to the complete run. Connection selection similarly shows only that handoff's trigger events. Search applies inside the current agent or connection scope.

Node and connection clicks remain distinct from graph panning: pointer capture starts only after the pointer crosses a small drag threshold. A stationary click selects the bubble, while a drag pans without accidentally changing the Activity filter.

Relationship lines use fixed-size open-chevron markers so repeated calls can increase line weight without inflating the arrowhead. Every edge shows its call count above the path with a background halo, and selected relationships switch both the line and arrow to the accent color.

Repeated instances of the same custom-agent role are collapsed into one node. Handoff lines become thicker as one role calls another more often, while self-calls and mutual calls remain stable loops and cycles. Select a line to inspect the timestamped, privacy-safe delegation summaries and outcomes that produced that relationship.

The extension view includes the same Pipeline / Agents / Gallery navigation as the standalone app. Those navigation buttons keep identical dimensions and placement while switching views. In Agents, create a template or edit an existing file through separate Metadata, Opening Instructions, and Markdown section editors. Change heading levels and names, reorder or remove sections, add new sections, switch to raw source when needed, or open the file in the normal VS Code editor. Unsaved source survives live pipeline refreshes; an external file edit is surfaced before an overwrite.

Choose Open Agent Studio from the Agents toolbar to open the canonical full-width Agents workspace inside a VS Code editor tab. Agent Studio deep-links directly to Agents and provides the same agent list, structured editor, New Agent workflow, routing, tools, models, and workflows as the web version. The sidebar remains available for quick edits; Open Source opens the selected Markdown file, while all new agents are created in Agent Studio. Agent action rows wrap at constrained widths so save and discard commands remain fully visible.

Choose Open Full Pipeline from the Live Pipeline view title or Command Palette to open the pipeline workspace in an editor tab. The extension webview itself is pinned to the full iframe viewport. VS Code's optional workbench.experimental.modernUI setting adds outer margins and rounded framing to every sidebar, panel, and editor surface; set it to false in VS Code settings if you prefer the whole workbench to use edge-to-edge panes. Extensions cannot override that host-level spacing themselves.

Graph connections use an invisible wide hit path for easier pointer and keyboard selection, but browser focus never draws its rectangular SVG bounds. Keyboard focus follows the route with a translucent accent halo, while the selected route and arrow use the same orange accent in VS Code and the web version.

Event source

The default source is:

**/.github/agent-workflow-events.log

On first use, the extension shows a setup screen instead of loading the graph. Select Install Setup to install the privacy-safe recorder, lifecycle hook configuration, and .gitignore entry in a trusted workspace. The pipeline workspace and web-version action unlock only after both setup files are present.

Each line is one JSON object produced by documented VS Code agent hooks. The core fields are:

{
  "schemaVersion": 1,
  "timestamp": "2026-08-08T12:00:00.000Z",
  "hookEventName": "SubagentStart",
  "sessionId": "session-id",
  "agentId": "subagent-id",
  "agentType": "Reviewer",
  "status": "running",
  "summary": "SubagentStart",
  "files": [],
  "inputKeys": []
}

For exact tool attribution during parallel custom-agent work, agent-scoped hooks may add sourceAgent. Without that field, Agent Pipeline Designer attributes activity only when one agent is active; it does not guess between concurrent agents of the same type.

An agent-scoped tool hook can stamp that field without recording prompt content:

hooks:
  PreToolUse:
    - type: command
      command: 'node .github/agent-pipeline-designer/record-event.mjs'
      env:
        AGENT_PIPELINE_DESIGNER_AGENT_NAME: 'Reviewer'
  PostToolUse:
    - type: command
      command: 'node .github/agent-pipeline-designer/record-event.mjs'
      env:
        AGENT_PIPELINE_DESIGNER_AGENT_NAME: 'Reviewer'

Commands

• Agent Pipeline Designer: Refresh Pipeline
• Agent Pipeline Designer: Open Web Version
• Agent Pipeline Designer: Prepare Pipeline Package...
• Agent Pipeline Designer: Install Workspace Recorder...
• Agent Pipeline Designer: Open Event Log
• Agent Pipeline Designer: Export Pipeline as JSON...
• Agent Pipeline Designer: Export Pipeline as Mermaid...
• Agent Pipeline Designer: Clear Event Log...

Clearing a workspace log requires Workspace Trust.

Open Web Version opens an existing Agent Pipeline Designer server when one is detected. From desktop VS Code, it otherwise starts the standalone project on the first available port from 3000 through 3010. The served page is Agent Pipeline Designer itself, not a VS Code for the Web instance.

Custom agents

Open the Agents tab in the standalone application to browse .github/agents/*.agent.md files from every attached workspace. Select an agent to edit its YAML metadata, opening instructions, and named Markdown sections in place. Section order, heading level, heading text, and content are all editable; files with malformed frontmatter fall back to a raw-source repair editor.

Select New Agent to create a workspace agent. The form writes validated YAML frontmatter and instructions to .github/agents/<filename>.agent.md. It rejects invalid filenames, unsafe tool IDs, oversized fields, cross-origin writes, and attempts to overwrite an existing file.

Saving an existing agent uses the same validated document model in VS Code and localhost. The standalone endpoint accepts only same-origin writes to regular files directly inside .github/agents/; invalid YAML, missing descriptions, empty section headings, path traversal, symlinks, and oversized files are rejected.

When agent edits are unsaved, switching between Pipeline, Agents, and Gallery or selecting another agent opens a Save Changes / Discard / Keep Editing prompt. Save waits for the backend acknowledgment before navigating; failures keep the editor open. Closing or reloading the page also triggers the browser's native unsaved-changes warning. The VS Code view retains its context when merely hidden or collapsed.

Inline file context

When the extension is active in VS Code, hover over content in .agent.md, .instructions.md, or copilot-instructions.md files to see contextual explanations without changing the file. Supported hover targets include:

• Agent frontmatter such as description, tools, agents, model, invocation controls, handoffs, and hooks
• Instruction frontmatter such as applyTo and description
• Common sections including Constraints, Approach, Output Contract, Validation, Agent Routing, Expected Agent Workflow, and Custom Tools
• Managed Agent Pipeline Designer markers and data blocks
• Exact @Agent Name and #tool: references

Unknown Markdown headings receive a scope-aware explanation, while unrelated Markdown files are left untouched. The provider supports VS Code's native chatagent and instructions language modes plus Markdown fallbacks.

Main Agent Instructions

Main Agent Instructions represents .github/copilot-instructions.md. These plain Markdown instructions are always included for the main Copilot agent and should contain only concise, actionable guidance that applies to every workspace task. In a multi-root workspace, existing instruction files are detected first and redundant Not created cards are omitted.

If no attached workspace has an instructions file, each available creation target appears as Not created. Opening the Agents view does not create anything: enter instructions and select Save Changes to create the file explicitly. Once it exists, Open Source and review-only Auto Revise become available. Auto Revise uses a dedicated project-instructions contract and cannot add custom-agent YAML frontmatter, tool access, or agent workflow routes.

Tool Access, Agent Workflow, and Delete are intentionally hidden for the main entry. Use custom agents for isolated roles and tool restrictions; use Main Agent Instructions for project-wide coding standards, architecture notes, build/test commands, and conventions that apply everywhere.

Tool access and custom tools

The Tool Access section shows the seven built-in aliases and any tools already selected for the agent. Up to 1,000 tools currently registered through vscode.lm.tools are treated as extras: they appear in the same normal search results when you search by ID or description, but do not clutter the default list. Once selected, a registered tool remains visible after search is cleared. Existing external IDs remain editable even when their providing extension or MCP server is temporarily unavailable.

Choose Add Custom Tool to document a manual tool ID. Each definition includes the exact ID, purpose, and usage instructions. The ID is selected automatically and remains selected until its definition is removed. Saving writes selected IDs to YAML frontmatter and creates a managed Custom Tools section containing reviewable agent-tools data. Concrete tool IDs may contain letters, numbers, dots, colons, slashes, underscores, and hyphens. Selected tool access also accepts * or a trailing namespace wildcard such as metaler-web/*; custom definitions must still identify one concrete tool.

Auto Revise receives the available tool IDs and may propose tool-access improvements. Any changes remain part of the normal unsaved revision draft and require Save Changes.

Model access

The Model Access section controls the optional model: list for each custom agent. It shows Copilot models currently advertised by VS Code using readable Name (vendor) references, keeps existing selections visible when a model is temporarily unavailable, and accepts a manual reference for models not currently advertised. Leave every model unselected to use the default model behavior.

Selected models are pinned above unselected choices so current restrictions remain visible without scrolling. Remaining model choices stay alphabetized.

Select multiple models to write list metadata such as:

model:
  - GPT-5.6 Sol (copilot)
  - GPT-5.6 Terra (copilot)
  - GPT-5.6 Luna (copilot)

Legacy scalar model: Model Name metadata is accepted and normalized when edited. Model restrictions are available during agent creation, preserved by Auto Revise, validated on save, and editable in both the VS Code and standalone Agents views.

Delete agents

Select Delete on an existing agent and confirm the modal warning. Delete is disabled while edits are unsaved or Auto Revise is running. The extension requests trash-backed deletion when supported and falls back to the workspace filesystem after confirmation. The standalone app accepts only same-origin deletion of regular .agent.md files directly inside .github/agents/; path traversal and symlinks are rejected.

Auto Revise

Select an existing agent and choose Auto Revise. Copilot receives that selected agent file plus the names of available workspace agents and prepares a conservative modernization using current custom-agent conventions. It is instructed to preserve the agent's identity, purpose, custom metadata, and valid @agent workflow routes while improving discovery triggers, instructions, constraints, structure, tool minimality, and output contracts.

The result is validated as a complete .agent.md document before appearing in the editor. Agent Pipeline Designer shows the model and a concise list of proposed changes. The file is not written automatically: review every section, then select Save Changes or Discard. Auto Revise is disabled while manual edits are unsaved. A valid revision can also repair malformed legacy frontmatter.

Auto Revise is user initiated. Only the selected agent definition and available agent names are sent through the consent-aware VS Code Language Model API; workflow event logs, transcripts, terminal output, and hidden model reasoning are not included. The standalone app requires its authenticated VS Code Copilot bridge, while the extension invokes the same validated revision flow directly.

Expected agent workflows

In an agent's Agent Workflow section, select each agent it may call. Targets are written as exact @Agent Name routes. Every route can define:

• Whether it is required or optional
• The condition under which it should be selected
• The task sent to the target agent
• The required response format
• An optional structured outcome such as PASS or READY

Routes are ordered. Strict order treats an unexpected target as a failure at the current step; with strict order disabled, unlisted calls are ignored while required configured routes must still occur in order.

The delegation template is editable and must contain @{{agent}} and {{instruction}}; {{output}} is also available. On save, Agent Pipeline Designer expands that template for every route inside a managed Expected Agent Workflow section and adds the agent tool capability when needed. This makes the intended calls explicit to the model and reviewable in the raw .agent.md file.

Select a runtime node in Pipeline to compare that contract with observed delegation metadata. Each route is marked pending, passed, skipped, or failed. A strict wrong-agent call, missing required call after the owner stops, FAIL/BLOCKED result, expected-outcome mismatch, or call that never starts its target identifies the exact failed step. The graph outlines failed agents and includes a workflow-failure count.

The contract is instruction-level enforcement, while compliance reporting is evidence-based. It does not expose or infer private model reasoning, and it does not claim that a language model is mechanically prevented from deviating. Evaluation uses only agent names, lifecycle events, privacy-safe delegation summaries, and structured outcomes already captured by the recorder.

Agent routing diagnostics

Each custom agent includes a Routing diagnostic. Agent Pipeline Designer detects incoming calls from Main Agent Instructions, managed Agent Workflow routes, exact @Agent Name instruction mentions, agents: allowlists, and handoffs. The workspace-agent count also reports how many custom agents have no explicit call route.

The diagnostic keeps invocation concepts separate:

• Explicit route means another agent or Main Agent Instructions tells Copilot to call that exact agent.
• Subagent allowlist means the agent is available to a parent through agents:; it does not schedule a call.
• Handoff means a button is offered after a response. The user must select it; send: true submits the handoff prompt only after that selection.
• Model inference means Copilot may choose the agent from its description. By default, custom agents are model-invocable unless disable-model-invocation: true is set.
• Agent picker means a user can start the agent manually when user-invocable is not false.

VS Code does not provide a custom-agent field that automatically schedules an agent at the true end of every chat. For a finalizer such as @Folder and workspace Maintainer, add an explicit final call to Main Agent Instructions or a coordinator workflow and ensure the agent/agent/runSubagent tool is enabled. This makes the intended route visible and testable, but instructions remain model-guided.

Select Auto Route on an agent with no explicit call route to infer a reviewable Main Agent Instructions entry. Descriptions or instructions that mention end-of-chat, finalization, or finishing work produce a finalizer route; other agents receive a conditional route derived from their discovery description. The popup lets you edit the instruction and choose the target workspace before anything is written. New agents open this popup automatically after creation.

Accepted routes are stored in a managed Agent Routing section of .github/copilot-instructions.md. The operation is idempotent, creates the instructions file when approved, preserves existing content, rejects symlink targets, and does not run while either the custom agent or Main Agent Instructions has an unsaved structured draft.

For stronger enforcement, a workspace Stop hook can block the first stop attempt with a reason telling the main agent to invoke the finalizer. A Stop hook runs a command and can force the agent to continue; it cannot directly invoke a custom agent. Always check stop_hook_active and allow the second stop attempt to avoid a loop. Use a handoff instead when a human should approve the transition.

Draft with Copilot

New Agent is the single place to create custom agents. Describe the desired behavior in Draft with Copilot at the top of that form, or fill the same fields manually. The draft description requires at least 3 words and 10 characters and shows an inline error when that requirement is not met. Copilot can populate the name, filename, discovery description, minimal tool set, invocation visibility, and complete instructions. All values remain editable, and no file is written until Create Agent is selected.

The browser never receives Copilot credentials. An authenticated localhost queue sends the one-shot draft request to the extension, which uses the consent-aware VS Code Language Model API. The first request may display a Copilot access prompt in VS Code. Jobs remain in server memory for at most 15 minutes and are not written to disk. A manually started web server can browse and create agents, but Copilot drafting is enabled only when the extension starts or reconnects to that server.

If access has not yet been granted, the pending draft remains open and shows Grant Access in VS Code. That link focuses VS Code, opens the Copilot authentication flow, and resumes the same request after approval. Open Web Version also requests access while VS Code is already focused, before launching the browser.

Use the Copilot model selector in New Agent to choose any model currently exposed by your Copilot account, or leave it on Auto (recommended). The selection is remembered in the browser.

While a request runs, Process shows timestamped operational stages such as queued, received by VS Code, selected model, generating, validating, waiting for permission, and ready for review. This is execution status for transparency, not private model chain-of-thought or hidden reasoning.

Pipeline Gallery

The Gallery reads a static versioned catalog from GitHub. The default public catalog currently contains no packages; its repository publishes only protocol schemas, declaration files, non-runnable examples, and documentation. Package download, verification, preview, conflict handling, receipts, and workspace writes remain part of the private Agent Pipeline Designer product.

Browse the public catalog and publishing entry point at pipeline-designer.github.io.

The public site uses black product branding, an animated pipeline scene, and a dedicated Actions workspace. Prepare in VS Code opens package preparation, while a valid GitHub manifest URL enables Open installer and passes that exact URL into Agent Pipeline Designer's verified review flow. The website itself never reads or writes workspace files.

Version 1 packages may create only these declarative customization files:

• .github/agents/<name>.agent.md
• .github/instructions/<name>.instructions.md
• .github/prompts/<name>.prompt.md
• .github/copilot-instructions.md

Scripts, hooks, binaries, dependencies, arbitrary paths, traversal segments, percent escapes, cross-origin payloads, and symlinked path components are rejected. Registry, manifest, and file downloads must use HTTPS GitHub URLs. Every file declares an exact byte length and lowercase SHA-256 digest; all package files are fetched and verified before review.

The VS Code extension uses a modal confirmation listing every destination. The standalone app uses a short-lived, one-time preview token and shows the exact verified text for every file before enabling installation. Installation refuses existing destinations, writes the receipt last, and removes files already written if a later write fails. Receipts are stored under .github/agent-pipeline-designer/packages/.

Use Install from URL for a GitHub-hosted manifest that is not listed in the catalog. This does not bypass path, size, origin, content, integrity, preview, or conflict validation.

Save and switch pipelines

Each workspace can contain multiple installed and local-only pipelines. The Pipeline tab groups them under Saved pipeline, shows the saved count, and keeps Activity and Run selection separate. Use + to add another package from Gallery, choose any saved pipeline, then select Set Active. Agent Pipeline Designer derives package membership from the verified installation receipt, identifies its coordinator, and generates one managed .github/agents/apd-active-pipeline.agent.md file.

Saved pipelines coexist, but one pipeline per workspace is active at a time. The generated APD Active Pipeline agent preserves that coordinator's instructions while replacing its agents: frontmatter with exactly the selected package's specialist names. Coordinator routes outside the package are rejected. Switching packages replaces only this APD-managed agent and its restart-safe state; hash-pinned package files and user-authored agents are never changed. The generated files are added to .gitignore as local runtime state.

After activation, select Open Active and choose APD Active Pipeline from Copilot's agent picker. Inside that selected agent, the agents: allowlist mechanically prevents subagent calls outside the active pipeline. VS Code does not currently expose a stable API for an extension to force this agent onto unrelated Main-agent chats, so chats that do not select APD Active Pipeline are not globally constrained.

Select Delete to remove an old saved pipeline after reviewing the file-count confirmation. Deleting the active pipeline also removes the APD-managed active coordinator and state. Installed package files are checked against their receipt hashes before deletion; if an existing file was edited, deletion stops so those changes are not lost. Missing stale files do not prevent the remaining receipt and owned files from being cleaned up. Local-only pipelines remove their edited copies after explicit confirmation.

Local-only pipeline copies

Choose an installed pipeline in the Pipeline tab and select Copy for Editing to create a private workspace copy. Enter a unique custom ID such as local.my-review-flow; that ID is immutable and identifies the local pipeline independently from its source package. Local copies are marked Local · in the selector.

Agent Pipeline Designer creates namespaced .github/agents/apd-local-*.agent.md copies, rewrites their internal routes to the copied agent names, and disables normal picker/model invocation for those source agents. Select Edit Files to choose the copied coordinator or any specialist and open it in the editor. Select Save Local to validate every copied agent and route, preserve the custom ID, and increment the local revision.

Local manifests live under .github/agent-pipeline-designer/local-pipelines/. Both the manifests and copied agents are added to .gitignore, so they remain local workspace state. Activating a local copy uses its edited files to regenerate APD Active Pipeline with an exact allowlist of only that local pipeline's namespaced specialists.

Publish a project pipeline

Run Agent Pipeline Designer: Prepare Pipeline Package... or choose Publish Pipeline in Gallery. Select the agents, instructions, prompts, and main Copilot instructions that form the reusable pipeline, then enter the package metadata, public GitHub project repository, and immutable tag or commit.

Agent Pipeline Designer writes an atomic, versioned folder at:

.github/agent-pipeline-designer/publish/<package-id>/<version>/

The folder contains copied declarative payloads, pipeline-package.json, and a ready-to-review registry-entry.json. Each manifest file has its exact byte size and SHA-256 digest. Existing versions are never overwritten; publish a new semantic version instead.

Commit the generated folder, push the declared tag or commit, and use Copy Manifest URL or Open Submission Page. The public website passes the manifest URL to an owner-reviewed GitHub issue. Package payloads remain in the project repository and are not copied into the registry repository.

Settings

• agentPipelineDesigner.eventGlob: event-source glob
• agentPipelineDesigner.maxEvents: recent events parsed per source
• agentPipelineDesigner.maxLogBytes: maximum log tail parsed per source
• agentPipelineDesigner.registryUrl: HTTPS GitHub URL for the package registry

Release channels

• Production uses main, the stable VS Code release, and https://pipeline-designer.github.io/.
• Beta uses beta, VS Code pre-release packaging, and https://pipeline-designer.github.io/beta/.

Run npm run package:prod from main or npm run package:beta from beta. Both commands fail when run from the wrong branch. Before publishing tracked changes, Release Channel Reviewer inspects risk and validation evidence; the user must then explicitly choose Beta, Production, or Keep Unpublished.

See RELEASE_CHANNELS.md for promotion rules.

Development

npm run compile
npm test
npm run serve-web

Press F5 to launch an Extension Development Host.

npm run serve-web builds and starts the standalone Agent Pipeline Designer application on http://localhost:3000. It reads .github/agent-workflow-events.log from the current directory and refreshes the browser view every two seconds.

Privacy and limitations

VS Code exposes subagent and tool lifecycle metadata through preview hooks, not a public extension API for directly inspecting Copilot sessions. This extension therefore reads workspace-owned event logs. Hook APIs may evolve, and tool attribution is intentionally conservative when events are missing agent-scoped metadata.