AgentGlow

Live 3D views of your agent system, driven only by OpenTelemetry. Every agent is a glowing instance that is born when its span starts, pulses on each LLM call, fires tool/MCP/graph packets, delegates to subagents, and fades when its span ends. Works with LangChain, LangGraph (incl. langgraph-supervisor), deepagents, the OpenAI Agents SDK (agentglow[openai-agents]), Hatchet workflows, Claude Code (via hooks), and any agent framework that emits OTel spans.

7 themes:

neural	constellation	orbit
atom	flow	bubblechamber
fireworks

Quickstart

uvx agentglow serve                  # → http://localhost:8100 (gallery at /, scenes at /neural, /orbit, …)
uv add "agentglow[langchain]"        # in your agent project (or: uv pip install "agentglow[langchain]")
# pip install "agentglow[langchain]" also works

import agentglow
agentglow.watch()                    # call once, before your agents run

# ... run your LangGraph / deepagents / Hatchet code as usual

That's it. watch() reuses your global OpenTelemetry TracerProvider (Langfuse or other exporters keep working), or installs one, adds a LiveSpanProcessor that streams span starts and ends to the server in ~50 ms batches from a background thread (never blocks, drops silently if the server is down), and turns on the OpenInference LangChain and OpenAI Agents instrumentations, MCP trace-context propagation and Hatchet instrumentation when those packages are installed (extras: [langchain], [openai-agents], [mcp], [hatchet]).

What gets drawn

Optional attributes you can set on your own spans: agentglow.agent (mark a span as an agent, value = name), agentglow.run.id, agentglow.run.topic, agentglow.step, agentglow.final (final answer text).

Announce MCP servers before they are called: agentglow.register_mcp("analytics", {"snowflake": "warehouse", "spark": "spark"}).

Your whole backend (0.4.0)

agentglow.watch(app=fastapi_app)                 # FastAPI / Starlette (mounted sub-apps too): service node + req/s halo
agentglow.watch(broker=faststream_broker)        # FastStream: publish -> consume comets between services
agentglow.watch(mcp=fastmcp_server)              # FastMCP: its DB / HTTP calls become its backends
agentglow.pulse("billing", "invoice.paid", status=200, duration_ms=12)   # no OTel: POST /v1/events in the background

DB / cache / HTTP calls become resource nodes, requests open past 3 s become job nodes with a timer, replicas show as ×N, failed publishes fizzle. Backend mode is strict privacy by default: only route templates, methods, status codes, hosts, DB system / operation, message destinations, model names, token counts and agentglow.* labels leave the process (privacy="standard", allow=, allow_message_keys=, ignore=, scrub= to tune; docs/SPEC.md "Privacy").

Generic primitives for what a trace does not say: session, stage, progress, capacity, rejected, pool / lease, inference, job, link / complete, fallback, gate, backlog, lifecycle, metric, event, cache, mark_error / mark_outcome. One call each, numbers / ids / short labels only (docs/SPEC.md "Generic primitives").

Hand-written agent loops (manual API)

No framework? Wrap your own loop. Each call is a plain OpenTelemetry span with the hint attributes below, so it works with watch() (agents appear the moment they start, even if they live for minutes) and with OTLP exporters. Without any TracerProvider every call is a cheap no-op. Context rides in contextvars: asyncio tasks created inside inherit it.

import agentglow
agentglow.watch()

async def handle_call(call_id):                      # one asyncio task per phone call
    async with agentglow.run(topic="Inbound call", run_id=call_id, scope=clinic_id):
        async with agentglow.agent("receptionist") as a:
            a.llm(model="gpt-realtime", tokens_in=812, tokens_out=64)   # one finished turn (or `with agentglow.llm(...) as l: l.set_tokens(i, o)`)
            with agentglow.tool("lookup_patient", args={"phone": "+1-555-0100"}) as t:
                with agentglow.mcp("clinic-db", tool="query", resource="Postgres", kind="db"):
                    ...
                t.result("found")
            async with agentglow.agent("scheduler", task="find a slot") as s:  # nested agent = subagent
                with agentglow.graph("write", nodes=["Appointment"]): ...
                s.final("Tue 10:30")                  # subagent: result message to its parent
            a.final("Booked Tue 10:30")               # top-level agent: the run's final text

Text you pass (say, final, task, args) is shown in the UI after the secret scrub only: keep PHI/PII out of it.

Options

agentglow serve [--host 0.0.0.0] [--port 8100] [--falkor redis://localhost:6379/<graph>] [--secret S] [--ingest-key K]

Embed in your own React app: npm i agentglow → <AgentScene theme="neural" source="http://localhost:8100" />.

Show each user only their agents

with agentglow.scope(user.id):   # or agentglow.set_scope(user.id); tags every span started inside
    run_agents()
token = agentglow.make_token(os.environ["AGENTGLOW_SECRET"], scope=user.id)  # for <AgentScene scope token />

With --secret / AGENTGLOW_SECRET, /live/stream, /live/graph, /live/run and /live/approve need Authorization: Bearer <token> and each viewer sees only its token's scope (or run; no scope and no run = admin). Without a secret (dev), the X-AgentGlow-Scope / X-AgentGlow-Run headers or ?run= on the stream filter. Claude Code hooks: add ?scope=... to the hook URL. Token format and details: docs/SPEC.md "Scopes & auth".

Scale

Agents are always centered; graph and MCP servers are side resources that appear only when used. The camera batches spawns into one smooth zoom.

Above 12 live agents the scenes auto-group older runs into clickable clusters and keep the newest ~10 in full detail (~60 fps with 500 live agents).

Deploying

State is in memory (no Redis). Run exactly one server per environment - on Kubernetes a Deployment with replicas: 1 plus a Service; point every worker's AGENTGLOW_URL at that Service.

MIT licensed · https://github.com/Nideesh1/agentglow