Metadata-Version: 2.4
Name: agentviz
Version: 0.3.0
Summary: Real-time 3D visualization for multi-agent AI systems
License: MIT
Project-URL: Homepage, https://github.com/tonystark3110/AGENTVIZ
Project-URL: Repository, https://github.com/tonystark3110/AGENTVIZ
Project-URL: Issues, https://github.com/tonystark3110/AGENTVIZ/issues
Project-URL: Change Log, https://github.com/tonystark3110/AGENTVIZ/releases
Keywords: ai-agents,multi-agent,visualization,mcp,llm,observability,tracing,opentelemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: websockets>=12.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.1.0; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai>=0.28.0; extra == "crewai"
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.0.3; extra == "openai-agents"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
Provides-Extra: mcp
Provides-Extra: all
Requires-Dist: langchain-core>=0.1.0; extra == "all"
Requires-Dist: langgraph>=0.1.0; extra == "all"
Requires-Dist: crewai>=0.28.0; extra == "all"
Requires-Dist: openai-agents>=0.0.3; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"

# 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

```python
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)

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

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

### WebSocket SDK (full control)

```python
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)

```python
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

```python
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

```python
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

```python
from agentviz.integrations.langgraph import get_langgraph_callbacks

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

### OpenAI Agents SDK

```python
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

```python
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:

```json
{
  "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

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

### docker-compose

```bash
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
