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

> Learn to create Archify workflow diagrams for agent tool calls. Visualize agent loops for planning, approval, execution, and recovery with this complete guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/agent-tool-call.workflow.json):

```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`.

```bash
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.

```bash
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.

```bash
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:

```json
"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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)**: JSON-Schema definition for the workflow IR, enforcing typed IDs and layout constraints
- **[`examples/workflow-agent-tool-call.html`](https://github.com/tt-a1i/archify/blob/main/examples/workflow-agent-tool-call.html)**: Rendered HTML artifact demonstrating the complete agent loop
- **[`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.