arbis

Runtime workflow observation for agent systems.

Arbis instruments SDK boundaries, collects execution events, and infers workflow graphs from observed behavior. It reconstructs what happened during representative executions without requiring manual instrumentation of every call.

Install

pip install arbis

Quick Start

import arbis

# Start observing — instruments OpenAI, Anthropic, Gemini, Bedrock,
# OpenRouter, LiteLLM, LangChain, CrewAI, AutoGen, LlamaIndex, and more.
tracker = arbis.discover()

# ... run your agent code as normal ...

# Stop and get the inferred workflow graph.
tracker.stop()
graph = tracker.graph()
print(f"{len(graph.nodes)} nodes, {len(graph.edges)} edges")

That's it. No decorators required for basic observation — discover() patches supported SDK boundaries automatically.

What Gets Captured

Supported Providers & Frameworks

LLM Providers:

• OpenAI (Chat Completions, Responses API, Embeddings)
• OpenAI Agents SDK
• Anthropic Messages
• Google Gemini (google.generativeai and google.genai)
• AWS Bedrock (Converse / Converse Stream)
• OpenRouter
• LiteLLM

Orchestration Frameworks:

• LangChain / LangGraph
• CrewAI
• AutoGen
• LlamaIndex

Transport:

• httpx and requests (HTTP-level LLM detection and tool execution spans)

Explicit Context API

For richer graphs, add structure with decorators:

import arbis

tracker = arbis.discover()

@arbis.workflow("loan_processing")
def process_loan(application):

    @arbis.agent("underwriter")
    def underwrite():
        # LLM calls here are automatically grouped under this agent
        ...

    @arbis.tool("credit_check")
    def check_credit(applicant_id):
        # Tool execution captured as a first-class span
        ...

    underwrite()
    check_credit(application["id"])

process_loan(app)
tracker.stop()

Persistence

Save workflow runs for later analysis:

# SQLite (default file-based)
tracker = arbis.discover(store="workflows.sqlite")

# JSON directory
tracker = arbis.discover(store="output/", store_backend="json")

# PostgreSQL (requires: pip install 'arbis[postgres]')
tracker = arbis.discover(store="postgresql://user:pass@host/db", store_backend="postgres")

# HTTP ingest to the Arbis backend (minted workflow_id / agent_id on @workflow / @agent)
tracker = arbis.discover(store_backend="http", org_id=ORG_ID, project_id=PROJECT_ID)

See minted-identities.md for attaching dashboard UUIDs and for identity-force-mode ingest warnings.

Export to OpenTelemetry

Mirror runs to OpenTelemetry as traces (the workflow → agent → llm_call → tool span tree, for Jaeger/Tempo/Honeycomb/Datadog) and/or metrics (token usage, latency, call/error/retry counts) — independently of, or alongside, Arbis's own stores. Requires pip install 'arbis[otel]'.

import arbis

# Arbis-owned OTLP export to a collector/Jaeger
tracker = arbis.discover(otel=True, otel_endpoint="localhost:4317")

# Add metrics, and/or plug into your existing OpenTelemetry providers
from opentelemetry import trace, metrics
tracker = arbis.discover(
    otel=True, otel_metrics=True,
    otel_tracer_provider=trace.get_tracer_provider(),
    otel_meter_provider=metrics.get_meter_provider(),
)

Spans follow OTel GenAI semantic conventions plus an arbis.* namespace. See the OpenTelemetry section of the guide for setup, both export modes, and the attribute/metric reference.

Workflow Viewer (TUI)

Browse workflow definitions, run history, and agent topology in the terminal:

pip install textual rich
python -m arbis.viewer

The viewer launches with realistic demo data by default. To connect to a live PostgreSQL store:

# Set connection details
export ARBIS_POSTGRES_DSN="postgresql://user:pass@host/db"
export ARBIS_PROJECT_ID="your-project-uuid"

# Initialize the database (first time only)
psql -d arbis -f scripts/init_db.sql
# Or reset from scratch:
./scripts/reset_db.sh

# Launch
python -m arbis.viewer --store "$ARBIS_POSTGRES_DSN" --project-id "$ARBIS_PROJECT_ID"

Viewer keybindings:

Three-pane layout:

• Left: Workflow definitions (named or auto-discovered)
• Middle: Run history for the selected workflow
• Right: Run detail — agent groups, handoffs, tool calls, thinking traces, token usage, and event timeline

Workflow Diffing

Compare how workflows evolve over time:

import arbis

diff_result = arbis.diff(graph_a, graph_b)
# Returns structural fingerprint comparison, agent/tool changes, topology deltas

In the viewer, press d on a workflow with multiple versions to see agent prompt changes, topology edits, and performance deltas.

Optional Dependencies

pip install 'arbis[postgres]'         # PostgreSQL storage backend
pip install 'arbis[otel]'             # OpenTelemetry traces + metrics export
pip install 'arbis[dev]'              # Development & testing
pip install 'arbis[arbis-litellm]'    # LiteLLM support
pip install 'arbis[arbis-frameworks]' # LangChain + AutoGen
pip install 'arbis[arbis-crewai]'     # CrewAI
pip install 'arbis[arbis-llamaindex]' # LlamaIndex
pip install 'arbis[arbis-bedrock]'    # AWS Bedrock
pip install 'arbis[arbis-gemini]'     # Google Gemini SDK

Documentation

All documentation is bundled inside the installed package. After pip install arbis:

from importlib.resources import files

# Get the path to bundled docs
docs = files("arbis") / "docs"

# Read a specific doc
print((docs / "guide.md").read_text())

Bundled docs:

License

MIT. See LICENSE.