AISquare Explainability SDK

Lightweight Python SDK for tracing, graphing, and policy auditing of AI agents. Captures execution traces from any Python agent (Agno, LangChain, plain Python) and delivers them to the AISquare Explainability Gateway.

Installation

pip install aisquare[explainability]

For Agno auto-instrumentation:

pip install aisquare[explainability,agno]

For Google ADK auto-instrumentation:

pip install "aisquare[adk]"

Quick start

Every trace needs an agent identity on its root span — agent_name is the key the gateway routes traces by. Name your agent explicitly and pre-register it:

# .env: EXPLAINABILITY_GATEWAY_URL, EXPLAINABILITY_API_KEY,
# EXPLAINABILITY_AGENTS=support-bot   <- pre-registers; must equal agent_name below
import aisquare.explainability as sdk

sdk.init_from_env()

with sdk.AgentRunTracer(agent_name="support-bot"):
    with sdk.LLMCallTracer(model="gpt-4o", provider="openai") as llm:
        ...  # your agent logic — nested spans inherit the run's routing identity

# IMPORTANT for short-lived scripts: flush ensures traces reach the gateway
# before the process exits. Long-running services don't need this.
sdk.flush()

Using a framework instead of manual tracers? The identity contract is the same — the agent's explicit name becomes agent.name on the root span: Agno Agent(name="support-bot"), LangChain metadata={"agent_name": "support-bot"}, or GovernedAgent(..., agent_name="support-bot").

What the SDK captures

The SDK collects two layers of signal:

Auto-instrumentation (zero tracing code): The AgnoAdapter installs openinference-instrumentation-agno, which automatically wraps every Agno agent run, LLM call, and tool invocation as an OTel span. The Agno Agent(name=...) becomes the trace's routing identity — always name your agents.

Manual tracers (governance-grade): Nine context-manager tracers you can add to any Python code — framework-agnostic:

Decorators are also available: @trace_tool and @trace_retrieval.

Manual instrumentation (any framework)

Leaf tracers (LLM, tool, routing, ...) always run nested inside an AgentRunTracer — its agent_name is stamped as agent.name on the root span, the attribute the gateway routes the trace by. A trace with no agent identity is rejected at ingest (409 no_agent_identity).

import aisquare.explainability as sdk

sdk.init_from_env()

with sdk.AgentRunTracer(agent_name="MyAgent", run_id="abc-123") as run:
    run.set_input("User query")

    with sdk.LLMCallTracer(model="gpt-4o-mini", provider="openai") as llm:
        response = call_openai(...)
        llm.set_input_messages([{"role": "user", "content": "..."}])
        llm.set_output_messages([{"role": "assistant", "content": response}])
        llm.set_token_counts(prompt=100, completion=50)

    with sdk.RoutingTracer(decision_type="tool_selection") as rt:
        rt.set_selected("web_search", reason="Query requires fresh data")
        rt.set_rejected([{"name": "cached_search", "reason": "Cache is stale"}])

    run.set_output("Agent final answer")

sdk.flush()

Environment variables

Multiple agents: name each agent in code (AgentRunTracer(agent_name=...) or the framework equivalent) — that per-run name is what routes each trace. AISQUARE_AGENT_NAME holds a single name and is a single-agent convenience only; it cannot distinguish between agents in the same process.

Diagnostics

The SDK ships a built-in health checker:

explainability-doctor

Its agent_identity check warns when no agent identity is configured (the classic precondition for 409 no_agent_identity ingest rejections), and its delivery_backlog check surfaces traces stuck in the local inbox after gateway 409s — with the remediation for each rejection code.

License

MIT