aisquare 1.0.6

Explainability SDK for tracing, graphing, and policy auditing of AI agents

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]

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:

Tracer	Purpose
AgentRunTracer	Wraps a full agent run as the root span
LLMCallTracer	Records an LLM inference call with I/O and token counts
ToolCallTracer	Records a tool invocation with parameters, result, and errors
RetrievalTracer	Records a RAG retrieval with documents and scores
HumanInterventionTracer	Records a human-in-the-loop review or correction
RoutingTracer	Records a routing/delegation decision with selected and rejected paths
DecisionTracer	Records a general decision point with options, selected, and rejected paths
PolicyGateTracer	Records a policy-gate evaluation with the policies checked and the allow/deny outcome
MemoryTracer	Records memory read/write operations

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

Variable	Description
EXPLAINABILITY_GATEWAY_URL	Gateway base URL for trace ingest
EXPLAINABILITY_API_KEY	API key for trace ingest
EXPLAINABILITY_AGENTS	Comma-separated agent names registered at init; must match your AgentRunTracer / framework agent names
AISQUARE_AGENT_NAME	The SDK's default agent identity, in two roles: the identity used for policy checks, and (since 1.0.6) the fallback trace identity stamped on spans that would otherwise be rootless so the trace still routes. Keep it equal to your agent_name.

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