How to Create Archify Workflow Diagrams for Agent Tool Calls: A Complete Guide

Archify converts typed JSON workflow descriptions into interactive, shareable diagrams that visualize agent tool-call loops through lanes for planning, approval, execution, and recovery.

You can create archify workflow diagrams for agent tool calls by defining a structured JSON Intermediate Representation (IR) that captures tool invocations, policy gates, and exception handling, then processing that IR through Archify’s CLI toolchain to generate browser-ready HTML artifacts. The tt-a1i/archify repository provides the schema definitions, validation logic, and rendering engine needed to turn complex agent orchestration flows into deterministic visual documentation.

Understanding the Archify Workflow Model for Agent Tool Calls

Agent tool-call diagrams in Archify rely on a lane-based architecture that separates concerns horizontally. Each lane represents a distinct phase of the agent lifecycle—such as planning, approval, execution, recovery, and reporting—while gates enforce policy checkpoints between phases.

The model captures four essential components:

• Tool-call nodes: Executable steps that invoke external commands or APIs
• Policy gates: Decision points that determine flow based on validation rules
• Exception edges: Directed connections that route errors and evidence back to recovery lanes
• Orthogonal connectors: Clean crossings that maintain readability when edges span multiple lanes

This structure maps directly to the JSON schema defined in archify/schemas/workflow.schema.json, which requires every node and edge to carry deterministic IDs for reproducible rendering.

Step-by-Step: Creating Your First Agent Tool-Call Diagram

The Archify CLI entry point at archify/bin/archify.mjs provides four sequential commands to move from raw JSON to a delivered artifact.

1. Generate the Workflow JSON

Create the typed IR by either hand-crafting JSON or using the CLI’s natural-language generator. The JSON must declare an id, type: "workflow", a presentation block, and multilingual metadata.

To generate from a prompt:

node archify/bin/archify.mjs guide "Agent tool-call loop" --json

Alternatively, author the JSON directly. Save the following as agent-tool-call.workflow.json:

{
  "id": "agent-tool-call",
  "type": "workflow",
  "proof": "agent-tool-call",
  "presentation": {
    "preset": "signal-flow",
    "motion": "trace",
    "views": "recommended"
  },
  "en": {
    "title": "Agent tool‑call loop",
    "question": "How does an agent plan, get permission, act, recover, and report?",
    "summary": "A lane‑based agent loop with policy gates, tool execution, exception recovery, evidence, and final response.",
    "useWhen": "Explaining agent runtimes, MCP/tool orchestration, approvals, retries, or observability.",
    "avoidWhen": "When only static component boxes are needed.",
    "include": [
      "request and planning",
      "policy or approval gate",
      "tool execution",
      "exception and evidence handling",
      "final response"
    ],
    "prompt": "Show the agent planning lane, the approval gate, the tool‑call lane, the recovery lane, and the reporting lane."
  },
  "nodes": [
    { "id": "plan",   "label": "Plan request", "lane": "plan" },
    { "id": "gate",   "label": "Policy gate", "lane": "approve" },
    { "id": "tool",   "label": "Tool call",   "lane": "execute" },
    { "id": "recover","label": "Recovery",   "lane": "recover" },
    { "id": "report", "label": "Report",      "lane": "report" }
  ],
  "edges": [
    { "from": "plan",    "to": "gate",    "label": "plan → gate" },
    { "from": "gate",    "to": "tool",    "label": "allow → tool" },
    { "from": "tool",    "to": "report",  "label": "result → report" },
    { "from": "tool",    "to": "recover", "label": "error → recover", "type": "exception" },
    { "from": "recover", "to": "report",  "label": "recovered → report" }
  ]
}

2. Validate the Schema

Before rendering, run the deterministic validator to check schema conformity, layout rules (minimum clearance, no overlapping anchors), and edge connectivity. Errors return as a JSON receipt with supportedFixes.

node archify/bin/archify.mjs validate workflow agent-tool-call.workflow.json --quality showcase --json

3. Preview Changes Live

Start the lightweight local server to watch the JSON file and reload only after passing validation. This preserves the last good artifact on failure, enabling rapid iteration.

node archify/bin/archify.mjs preview workflow agent-tool-call.workflow.json /tmp/workflow.html --quality showcase

4. Deliver the Final Artifact

Bundle the HTML with all CSS/JS dependencies, optionally opening it in the browser immediately. The resulting file can be hosted on GitHub Pages or exported to PNG/SVG/WebM.

node archify/bin/archify.mjs deliver workflow agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

The Signal-Flow Preset for Agent Workflows

For agent tool-calls, Archify’s signal-flow preset (used in the built-in “Agent tool-call loop” example) renders lanes as horizontal bands with nodes anchored to lane centers. This visualization employs orthogonal edges that cross lanes only at designated clearance points, making policy checkpoints and exception routes instantly readable.

Set this preset in the presentation block:

"presentation": {
  "preset": "signal-flow",
  "motion": "trace",
  "views": "recommended"
}

The motion field supports trace for animated flow lines, static for still diagrams, or omission for default behavior. Static exports remain unaffected by animation settings.

Key Implementation Files

The following source files define the workflow architecture:

• archify/bin/archify.mjs: Core CLI entry point implementing guide, validate, preview, and deliver commands
• archify/schemas/workflow.schema.json: JSON-Schema definition for the workflow IR, enforcing typed IDs and layout constraints
• examples/workflow-agent-tool-call.html: Rendered HTML artifact demonstrating the complete agent loop
• docs/start.html: Interactive start page containing embedded JSON source in a <script id="start-data"> element

Summary

• Archify transforms typed JSON into interactive workflow diagrams for agent tool-calls through a deterministic four-stage pipeline: Generate, Validate, Preview, and Deliver.
• The signal-flow preset optimizes readability for agent workflows by organizing nodes into horizontal lanes and using orthogonal edge routing.
• Every node and edge requires a deterministic ID, ensuring that identical source JSON always produces identical diagrams.
• Validation produces machine-readable error receipts with suggested fixes, allowing iterative refinement without rewriting the entire diagram.
• Final artifacts are single HTML files supporting theme toggling, zoom, and guided stories, suitable for hosting on any static site platform.

Frequently Asked Questions

What is the minimum JSON structure required for an Archify workflow?

A valid workflow JSON requires an id, type: "workflow", a presentation object with a preset value, at least one language block (e.g., en with title and summary), and arrays of nodes and edges. Each node must have an id, label, and lane property, while edges require from, to, and optionally a type for exception handling.

How do I handle error paths and recovery flows in agent tool-call diagrams?

Define exception routes using edges with "type": "exception" that connect tool-call nodes to recovery lanes. In the JSON structure, these edges route from the execution node to a recovery node, then back to the reporting lane, creating a closed loop that captures evidence handling and retry logic visually.

Can I export Archify diagrams to static image formats?

Yes. The deliver command generates a bundled HTML artifact that can be exported to PNG, SVG, or WebM formats. The interactive HTML file remains the primary artifact, supporting zoom and theme toggling even when hosted statically on platforms like GitHub Pages.

Where is the workflow validation logic implemented in the Archify source code?

The validation engine resides in the CLI tool chain accessed through archify/bin/archify.mjs, which references the strict JSON-Schema defined in archify/schemas/workflow.schema.json. This schema enforces layout rules such as minimum clearance between lanes and ensures every edge connects to defined node IDs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}