0.3.0

agentviz

Real-time 3D visualization for multi-agent AI systems. Drop one decorator on your agent functions and watch them appear as robots in a live 3D scene — calls, responses, token streams, errors, and latency all rendered as they happen.

pip install agentviz
agentviz serve

---

How it works

1. You run agentviz serve — starts a local FastAPI server + opens the 3D UI in your browser
2. You decorate your agent functions with @agentviz.trace
3. Every call, response, error, and token stream is sent to the server and rendered live

The server can be self-hosted anywhere (Linode, Railway, Docker). Multiple agents on different machines can all connect to the same room.

---

Quick start

Simplest — one decorator

import agentviz

agentviz.init(server="http://localhost:8000")

@agentviz.trace
async def fetch_data(query: str) -> str:
    return await db.query(query)

@agentviz.trace(name="Planner", to="orchestrator", color="#9B59B6")
async def plan(goal: str) -> str:
    return await llm.plan(goal)

That's it. Run your agents — they show up in the UI automatically.

Environment variables (zero code changes)

export AGENTVIZ_SERVER=http://localhost:8000
export AGENTVIZ_PROJECT=my-team

Then just use @agentviz.trace with no init() call.

WebSocket SDK (full control)

from agentviz import AgentVizClient

async with AgentVizClient(
    server="ws://localhost:8000/agent-ws",
    name="DataFetcher",
    color="#E74C3C",
) as client:
    call_id = await client.emit_call(to="orchestrator", message="Fetching records…")
    result  = await do_work()
    await client.emit_response(to="orchestrator", call_id=call_id, result=result)

HTTP client (serverless / AWS Lambda / Cloud Run)

from agentviz import HttpAgentVizClient

client = HttpAgentVizClient(server="https://my-agentviz.railway.app", name="Lambda")

call_id = client.emit_call(to="orchestrator", message="Processing event…")
result  = process(event)
client.emit_response(to="orchestrator", call_id=call_id, result=result)

Token streaming

async for chunk in llm.stream(prompt):
    await client.emit_token(chunk.delta)
await client.emit_stream_end()

Tokens accumulate in a speech bubble above the robot in real-time.

---

Features

• @agentviz.trace — works on any async or sync function, no boilerplate
• Trace trees — nested calls automatically build a parent→child hierarchy (via contextvars)
• Token streaming — live speech bubble above each robot as the LLM generates
• Error visualization — red glow + shake animation on agent errors
• Latency labels — floating ms labels between agents, color-coded by speed
• Dynamic agents — robots spawn and despawn as agents connect and disconnect
• 5 layouts — semicircle, pipeline, star, mesh, grid — switch live from the UI
• Room isolation — ?room=project-name separates teams on the same server
• Session recording — SQLite-backed, replay any past session from the UI
• No orchestrator required — works for peer-to-peer autonomous agent systems

---

Integrations

LangChain

from agentviz.integrations.langchain import AgentVizCallbackHandler
from agentviz import HttpAgentVizClient

client  = HttpAgentVizClient(server="http://localhost:8000", name="LangChainAgent")
handler = AgentVizCallbackHandler(client)

chain.invoke({"input": "..."}, config={"callbacks": [handler]})

LangGraph

from agentviz.integrations.langgraph import get_langgraph_callbacks

callbacks = get_langgraph_callbacks(client)
graph.invoke(state, config={"callbacks": callbacks})

OpenAI Agents SDK

from agentviz.integrations.openai_agents import patch_openai_agents
import agentviz

agentviz.init(server="http://localhost:8000")
patch_openai_agents()   # patches globally — all agents auto-traced from here

OpenTelemetry

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from agentviz.integrations.otel import AgentVizSpanExporter

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(AgentVizSpanExporter()))

Every OTEL span becomes a call/response/error event in the 3D scene automatically.

MCP server (Claude Desktop / Cursor)

Add to your MCP host config:

{
  "mcpServers": {
    "agentviz": {
      "command": "python",
      "args": ["-m", "agentviz.mcp_server"],
      "env": {
        "AGENTVIZ_SERVER": "http://localhost:8000"
      }
    }
  }
}

Then use agentviz_emit_call, agentviz_emit_response, agentviz_emit_token etc. as tools from within Claude.

---

Self-hosting

Docker

docker build -t agentviz .
docker run -p 8000:8000 agentviz

docker-compose

docker-compose up

Railway / Render / Fly.io

Push the repo and set the start command to:

agentviz serve --host 0.0.0.0 --port $PORT --no-browser

---

CLI

agentviz serve                         # start server, open browser
agentviz serve --port 9000             # custom port
agentviz serve --no-browser            # headless (for servers)
agentviz serve --demo                  # also start demo agents
agentviz --version

Or:

python -m agentviz serve

---

Multi-room / multi-team

Each URL ?room=<name> gets its own isolated scene, agent registry, and session history. Share a single deployed server across multiple teams:

https://agentviz.mycompany.com/?room=search-team
https://agentviz.mycompany.com/?room=billing-team

---

License

MIT