agent-html

Turn structured agent output into polished, self-contained HTML artifacts.

One conversation in. One shareable HTML file out.

---

Why

AI conversations are great for exploration but terrible for sharing. Chat transcripts are long, unstructured, and die in the thread. agent-html gives you a one-line way to turn any structured data into a professional, self-contained HTML report that anyone can open.

Works with any agent framework: LangGraph, OpenAI Agents, Claude Code, CrewAI, or plain Python.

Install

pip install agent-html

Quick Start

from agent_html import Report, Section

report = Report(
    title="Weekly Summary",
    subtitle="Engineering — Aug 14-21, 2026",
    metadata={"messages": 142},
)

report.add_section(Section(
    title="Overview",
    content="Team focused on infrastructure stability after the outage.",
    style="highlight",
))

report.add_section(Section(
    title="Decisions",
    icon="✅",
    items=["Shut down UAE region", "Migrate to EU-West by Q3"],
))

report.add_section(Section(
    title="Architecture",
    mermaid="graph TD\n  A[Client] --> B[Gateway] --> C[Service]",
))

report.save("summary.html")

Output: a single summary.html file with all CSS/JS inlined. No external dependencies. Double-click to open.

CLI

# From JSON
agent-html render --input data.json --output report.html

# From Markdown
agent-html render --input notes.md --title "Design Review" --output report.html

# Dark theme
agent-html render --input data.json --theme dark --output report.html

# Pipe from stdin
echo '{"title":"Quick","sections":[{"title":"Note","content":"Hello"}]}' | agent-html render --stdin --output note.html

# Preview server
agent-html serve ./reports/

Features

• Single-file output — all CSS/JS inlined, no external deps
• Themes — light, dark, or auto (respects system preference)
• Mermaid diagrams — flowcharts, sequence diagrams, state machines
• Syntax highlighting — language-aware code blocks with copy button
• Table of contents — auto-generated with scroll-spy
• Collapsible sections — <details>/<summary> for long content
• Callout blocks — note, warning, danger, tip
• Tables — from structured data
• Badges/pills — for tags, participants, status
• Print-optimized — clean PDF via browser print
• Accessible — semantic HTML, ARIA labels, keyboard nav

Section Styles

Section(title="Info", content="...", style="highlight")        # Accent-bordered
Section(title="Note", content="...", style="callout-note")     # Blue info box
Section(title="Warn", content="...", style="callout-warning")  # Yellow warning
Section(title="Error", content="...", style="callout-danger")  # Red danger
Section(title="Tip", content="...", style="callout-tip")       # Green tip
Section(title="Tasks", items=[...], style="checklist")         # Checkbox list

Integration Examples

LangGraph / LangChain Tool

from langchain_core.tools import tool
from agent_html import Report, Section

@tool
def create_report(title: str, sections: list[dict]) -> str:
    """Generate a shareable HTML report."""
    report = Report(title=title)
    for s in sections:
        report.add_section(Section(**s))
    report.save(f"/tmp/reports/{report.id}.html")
    return f"Report: http://localhost:8080/reports/{report.id}"

FastAPI

from fastapi.responses import HTMLResponse
from agent_html import Report, Section

@app.post("/reports")
async def create(data: ReportRequest):
    report = Report(title=data.title)
    for s in data.sections:
        report.add_section(Section(**s.dict()))
    return HTMLResponse(report.to_html())

JSON Input Format

{
  "title": "My Report",
  "subtitle": "Optional subtitle",
  "metadata": {"key": "value"},
  "sections": [
    {"title": "Overview", "content": "Markdown content here", "style": "highlight"},
    {"title": "Items", "items": ["one", "two", "three"], "icon": "📋"},
    {"title": "Diagram", "mermaid": "graph TD\n  A --> B"},
    {"title": "Code", "code": "print('hello')", "code_language": "python"},
    {"title": "Table", "table": {"headers": ["A","B"], "rows": [["1","2"]]}}
  ]
}

Inspiration

Built on ideas from:

• ThariqS/html-effectiveness (Apache-2.0) — demonstrating HTML as an AI output medium
• The "Unreasonable Effectiveness of HTML" thesis by Thariq Shihipar

License

Apache-2.0