Show, Not Just Tell

Agent diagrams with zero local renderers

The Gap

Agents can describe a system in words — but words can't show it

An Amplifier agent describes architectures, sequences, and schemas fluently. Describing isn't showing — and no picture appears.

The diagrams tool lets an agent render the diagram it authors — without installing a single renderer.

An agent can describe an architecture in prose
It can describe a sequence, step by step
It can describe a schema, table by table
But prose alone never becomes a diagram

Proof

This is a real, working prototype — not slideware

~1,650 lines of Python: 1,015 in source, 635 in tests. A 35-test suite runs, with 34 passing in a clean environment.

So the mechanism ahead isn't hypothetical — it already runs. Start with what the agent actually feeds it.

~1,650

Lines of Python (src + tests)

1,015

Source lines

635

Test lines

34/35

Tests passing (clean env)

The Input

The agent's input is diagram DSL it authors

Three accepted formats — Mermaid, PlantUML, or D2 — across 8 curated diagram types the tool exposes.

The agent already writes this DSL. The only missing step is turning it into a picture.

Mermaid PlantUML D2

flowchart sequence class erd architecture mindmap gantt state

The Cost

Rendering that DSL yourself drags in heavy local installs

Standing up a real renderer traditionally means Java, Node.js, GraphViz, or PlantUML on the machine — exactly what nobody wants on an agent's box.

The module says it plainly: "Zero Dependencies: No Java/Node.js installation required."

✕ Java runtime
✕ Node.js
✕ GraphViz
✕ PlantUML

The Move

The KrokiClient POSTs the DSL — no local renderer runs

The client posts the diagram content to kroki.io over plain HTTP and gets rendered bytes back. Rendering is offloaded, not installed.

One HTTP call resolves the tension — the heavy dependency lives on Kroki, not on the machine.

# KrokiClient.render_diagram
client.post(
  f"{base_url}/{kroki_type}/{kroki_output}",
  # Content-Type: text/plain
)
# base_url = "https://kroki.io"
# → rendered bytes back

Sharing

To share, it packs the DSL into one openable GET URL

The client zlib-compresses and base64-encodes the DSL into a single GET URL anyone can open — the agent never holds rendering state.

Whether it's raw bytes or a link, the same idea holds: describe, then offload.

# KrokiClient.get_diagram_url
zlib.compress(content)
base64.urlsafe_b64encode(...)
# → one GET URL, anyone can open

Payoff

Hand off pure DSL over one HTTP call, get a picture back

The agent describes; the tool offloads. Only httpx and pydantic sit on the machine — zero Java, Node, or GraphViz.

Describe-and-offload delivers rendered diagrams with zero local rendering dependencies.

2

Runtime deps: httpx + pydantic

0

Java / Node / GraphViz installs

4

Operations: generate, validate, render, get_url

14

Starter templates shipped

The Pattern

Eight curated types are a deliberate starting surface

Kroki advertises 25+ diagram types; this module exposes 8. Describe-and-offload is a pattern with room to grow.

The idea to keep: offload the heavy dependency, expose a curated surface.

Working single-commit prototype

8

Types exposed by the module

25+

Types Kroki advertises

Sources

Research Methodology

Data as of: 2026-01-21 (single-commit prototype, commit 923ca3b)

Feature status: Working single-commit prototype — full module with Kroki HTTP client (retry + exponential backoff), pydantic models, template loader, two tools, 14 templates, 35-test suite. Not yet iterated beyond the initial drop.

Repository: amplifier-module-tool-diagrams — sole author Sam Schillace. License: MIT.

Commands run:

Line counts: git ls-files '*.py' | xargs wc -l | tail -1 → 1,650 total (src 1,015 / tests 635)
Diagram types: cat src/amplifier_diagrams/models.py (DiagramType enum) + bundle.yaml enum → 8 types
Input formats: cat src/amplifier_diagrams/models.py (DiagramFormat enum) → mermaid, plantuml, d2
Operations: cat src/amplifier_diagrams/models.py (DiagramOperation enum) → generate, validate, render, get_url
Rendering: cat src/amplifier_diagrams/kroki_client.py → POST to https://kroki.io; GET URL via zlib + base64
Dependencies: grep -nE 'Zero Dependencies|No Java|httpx|pydantic' bundle.yaml → httpx>=0.24.0, pydantic>=2.0
Templates: git ls-files 'templates/*' | wc -l → 14
Tests: grep -rn 'def test_' tests/ | wc -l + PYTHONPATH=src pytest -q → 35 tests, 34 passed
History: git log --all --format='%ad | %an | %s' --date=short; git rev-list --all --count → 1 commit
Kroki 25+ claim: grep -n '25' README.md (line 7)

Gaps: "Natural language to diagram" is story framing only — the tool's content parameter takes DSL text, not free-form English. The single failing test (test_diagram_get_url) is an AsyncMock wiring issue in the test, not a runtime defect. Tests run only with PYTHONPATH=src.

Primary contributor: Sam Schillace (sole author — 100% of the single initial commit).