pyagent-studio

Pillar 4 of the PyAgent production stack for multi-agent LLM systems — CLI + web control plane for designing, simulating, debugging, and governing agent systems.

Architecture Pillar: 📊 Observability The control plane of the Observability pillar — a kubectl-style CLI and FastAPI web dashboard for simulating workflows, exploring recorded traces, diffing blueprint versions, and monitoring provider health and costs. Part of the full stack: install pyagent-all for all pillars.

Install

pip install pyagent-studio

Depends on: pyagent-blueprint, pyagent-trace, pyagent-providers, click, rich, litellm, fastapi, uvicorn, jinja2.

Quick Start

# Load and validate a blueprint
pyagent apply blueprint.yaml

# List agents
pyagent get agents blueprint.yaml

# Simulate a workflow (MockLLM, no API keys needed)
pyagent simulate blueprint.yaml support "Help me with billing"

# Simulate with real LLMs (set OPENAI_API_KEY, etc.)
pyagent simulate blueprint.yaml support "Help me with billing" --live

# Launch the web dashboard
pyagent dashboard

CLI Commands

Web Dashboard

Launch with pyagent dashboard. Built with FastAPI + HTMX + Pico CSS (zero JS build step).

Provider Setup

pyagent-studio uses LiteLLM for multi-provider LLM access. Set API keys via environment variables:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=...

No custom configuration needed — LiteLLM supports 100+ providers out of the box.

Services (Headless API)

Use the services layer for scripting and CI:

from pyagent_studio import BlueprintService, SimulationService, GovernanceService, ProviderService

# Load and validate
svc = BlueprintService()
spec = svc.load("blueprint.yaml")
issues = svc.validate()
print(svc.summary())

# Run simulation
import asyncio

sim = SimulationService()
result = asyncio.run(sim.run(spec, "support", "I can't see my invoice"))
print(result.output)

# Governance
gov = GovernanceService()
report = gov.check_compliance(spec)
print(gov.format_report(report))

# Provider health check
provider = ProviderService()
asyncio.run(provider.health_check())

Architecture

flowchart TD
    subgraph CLI Layer
        CLI[pyagent CLI] -->|commands| SVC[Service Layer]
    end

    subgraph Web Layer
        WEB[FastAPI + HTMX + Pico CSS] -->|routes| SVC
        WEB -->|SSE| TRACE[Live Trace Stream]
    end

    subgraph Service Layer
        SVC --> BS[BlueprintService]
        SVC --> SS[SimulationService]
        SVC --> GS[GovernanceService]
        SVC --> PS[ProviderService]
        SVC --> TS[TraceService]
    end

    subgraph PyAgent Ecosystem
        BS -->|load/validate/compile| BP[pyagent-blueprint]
        SS -->|run patterns| PAT[pyagent-patterns]
        SS -->|use providers| PRV[pyagent-providers]
        TS -->|consume events| TRC[pyagent-trace]
        GS -->|check compliance| BP
    end

Studio is structured in three layers:

• CLI layer — Click-based commands (pyagent apply, pyagent simulate, etc.) for terminal workflows
• Web layer — FastAPI + HTMX + Pico CSS dashboard (zero JS build step, all server-rendered)
• Service layer — Headless Python services usable from CLI, web, or programmatic scripts

Web Dashboard Pages in Detail

Trace Visualization

The /traces page provides two modes of trace inspection:

Live Mode — Server-Sent Events (SSE) stream from an active TraceEventBus. Events appear in real time as agents execute, showing:

• Agent start/end with input/output previews
• LLM calls with model name, token counts, cost, and latency
• Pattern lifecycle (start → agent calls → end)
• Compression events with savings percentages
• Cost accumulation in real time

Historical Mode — Browse JSONL trace files produced by JsonlExporter or Recorder. Filter and search by:

• Event type (agent_start, llm_call, cost, compression, error)
• Agent name
• Pattern name
• Time range
• Cost threshold

Governance & Compliance

The governance page runs BlueprintValidator checks and presents:

• Compliance score — percentage of checks passing (0–100%)
• Issue breakdown — grouped by severity (ERROR, WARNING, INFO)
• Validation checks — dangling refs, hardcoded secrets, unrealistic SLAs, unwired observability/context
• Diff view — compare current blueprint against a baseline to detect breaking changes

Services (Headless API) — In Depth

BlueprintService

Central service for blueprint lifecycle management:

from pyagent_studio import BlueprintService

svc = BlueprintService()
spec = svc.load("blueprint.yaml")  # Load and parse
issues = svc.validate()  # Static analysis
graph = svc.compile()  # Compile to RuntimeGraph
summary = svc.summary()  # Human-readable summary
agents = svc.list_agents()  # Agent inventory
workflows = svc.list_workflows()  # Workflow inventory
mermaid = svc.render_mermaid()  # Mermaid diagram string

SimulationService

Run workflows with MockLLM or live providers:

from pyagent_studio import SimulationService
import asyncio

sim = SimulationService()

# MockLLM simulation (no API keys needed)
result = asyncio.run(sim.run(spec, "support", "I can't see my invoice"))
print(result.output)
print(result.metadata)  # Pattern-specific metadata
print(result.duration_seconds)

# Live simulation with real providers
result = asyncio.run(sim.run(spec, "support", "I can't see my invoice", live=True))

TraceService

Load and query trace data:

from pyagent_studio import TraceService

traces = TraceService()
spans = traces.load("traces/run_001.jsonl")

# Query specific event types
llm_calls = traces.query(event_type="llm_call")
errors = traces.query(event_type="error")

# Cost summary from trace data
print(traces.summary())
# {"total_cost_usd": 0.0189, "total_tokens": 3950, "events": 12}

GovernanceService

Check compliance and generate reports:

from pyagent_studio import GovernanceService

gov = GovernanceService()
report = gov.check_compliance(spec)
print(gov.format_report(report))
# Compliance Score: 85%
# ERRORS (1): dangling agent ref in workflow 'support'
# WARNINGS (2): unwired observability, unrealistic SLA

Integration with PyAgent Ecosystem

Studio integrates with every PyAgent package:

Comparison

Other packages in this pillar

• pyagent-trace — TraceEventBus, OTel spans, cost tracking, record/replay

Full stack

Install all pillars at once: pip install pyagent-all

→ pyagent.org for full documentation.

Full Documentation

See pyagent.org for full API reference and integration guides.

The PyAgent ecosystem

PyAgent is a production stack for multi-agent LLM systems. Each package is independent — install only what you need, or get everything with pip install pyagent-all.

Learn more: Design patterns · Cookbook · Get started