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