VisibleAgent Python SDK

Plain-English observability for AI agents. VisibleAgent turns your agent's work into a story a human can read — every run, every step, every tool call, live-streamed to a dashboard with full replay — while capturing metadata only by default: never prompts, never customer content, unless you explicitly opt in.

Install

pip install visibleagent            # core SDK
pip install "visibleagent[langgraph]"  # + LangGraph auto-instrumentation

LangGraph: one line, zero node changes

from visibleagent import VisibleAgent
from visibleagent.integrations.langgraph import VisibleAgentTracer

va = VisibleAgent(api_key="...", base_url="https://your-visibleagent-host")

tracer = VisibleAgentTracer(
    client=va,
    source="MyApp",                       # "which app did this?" label
    display_names={                       # optional: human names per node
        "classify": "Classifying the message",
        "respond": "Drafting a reply",
    },
    descriptions={                        # optional: what each step does
        "classify": "Reads the message and works out what it's about",
    },
    narrate=my_narrator,                  # optional: plain-English outcomes
)

graph.invoke(state, config={"callbacks": [tracer]})

The tracer auto-derives the whole span tree from LangGraph's callbacks — nodes, model calls ("Thinking — …"), and tool calls — including model names, token usage, and latencies. It works with bare llm.invoke() calls inside your nodes (no config threading needed), never raises into your app, and is completely inert when unconfigured.

narrate(node_name, output_state) lets you turn structured state into human sentences — "Understood the message as a new order (94% confident)" — without ever exposing raw content.

Manual instrumentation

with va.start_run(name="Refund request #4521", attrs={"source": "MyApp"}) as run:
    with run.agent("support_agent", display="Support Agent") as agent:
        with agent.step("classify", display="Understanding the request"):
            ...
        with agent.tool("orders.lookup", display="Checking the order") as tool:
            order = lookup(order_id)
            tool.note(f"Found order {order_id}")
va.flush()

Spans emit .started / .completed / .failed automatically based on whether the block raises. Delivery is batched on a background thread and fail-open: a missing or unreachable VisibleAgent backend never affects your application.

Content safety

Metadata capture is the default and the contract: span attributes carry model ids, token counts, durations, statuses, and the labels you author — never prompt or completion text, never tool argument values. A separate explicit capture_content="full" mode exists for teams who want their own content in their own dashboard.

License

Apache-2.0