Connect your agents

Two ways to send your agents to AISquare, the SDK and the multi-provider proxy. Both give full observability, governance, and runtime enforcement. They differ on where the gate runs.

Your agents keep running exactly as they do today. AISquare connects alongside them, recording each run as a trace, extracting the reasoning, evaluating it against your policies, signing the result, and surfacing cost. You connect one of two ways, and you can mix them across teams: every run lands in the same reasoning graph regardless of how it got there.

Your agent  ->  AISquare . trace . screen PII . evaluate policy . sign  ->  Your dashboard

Connecting is the only setup step. Everything in the Trust Loop (Understand, Prevent, Fix, Remember) operates on the decisions that flow in once an agent is connected.

Which path should I use?

SDK

A drop-in, OpenTelemetry-native library. Full fidelity plus an in-process gate: block, improve, or warn on a tool call before it runs. Best for custom spans, enrichers, and inline governance.

Multi-provider proxy

Point your provider base URL at AISquare. Zero code, no new dependency. Full observability plus live Rule Book enforcement on every call. Best for the fastest start across a fleet.

For the complete proxy guide (the coding-CLI connect script, the per-provider reference, and enforcement semantics), see Proxy integration.

What matters to you	Proxy	SDK
Setup effort	About 5 minutes, a base URL and a header	Install, name your agent, wrap
Agent code change	None	Minimal (a wrapper)
Agent identity	X-Agent-Name header (defaults applied)	Required: agent_name / AgentRunTracer — the routing key
New dependency	No	Yes, one package
How runs are captured	At the network boundary (zero code)	In your code (both emit OpenTelemetry spans)
Traces, reasoning, and cost	Yes	Yes
PII / PHI / PCI detection at ingest (redact via the mask policy)	Yes	Yes
Policy verdicts	Yes	Yes
Signed audit record plus AIBOM	Yes	Yes
Runtime enforcement	Yes: block / improve / warn / gate-in	Yes: block / improve / warn
Where the gate runs	At the LLM call, on AISquare's side	Inside the agent, at the tool boundary
Best starting point for	Fast, zero-code governance	Custom spans and in-process gating

A note on enforcement

Both paths give you full governance: every run is evaluated against your policies, each verdict (pass or block, with a reason and a citation) is recorded on the run, and both can enforce at runtime. They differ on where the gate runs.

The SDK runs a policy gate inside the agent, at the tool boundary, so a rule can block, improve, or warn on a tool call at runtime, before it fires.
The proxy enforces at the LLM-call boundary, on AISquare's side. With its Rule Book switched to Live, it can block an unsafe tool call (the agent is handed the reason and re-plans), improve a non-compliant reply by rewriting it, warn by flagging the run, and gate-in by checking tool outputs for prompt injection before the model sees them. In Audit, it records and flags but never alters a run.

The proxy is the fastest way to put observability and enforcement across your fleet on day one, with zero code changes. Choose the SDK when you want the gate in-process, or instrumentation beyond what the transparent proxy captures: custom spans, enrichers, and inline governance.

Option A: SDK

The SDK is OpenTelemetry-native: it auto-instruments your agent, batches spans, retries on failure, and ships them to your AISquare workspace. There is no proprietary wire format to adopt: if you already emit OpenTelemetry, the SDK attaches to your existing TracerProvider. It supports Agno and LangChain with automatic tool interception, plus custom agents and direct OpenAI SDK callers via GovernedAgent.wrap and the gate API. (For the direct Anthropic SDK, use the proxy below.)

pip install "aisquare[explainability]"

Values come from your workspace settings. See Authentication for where to find your ingest key. The URL is the base gateway URL, with no path — the SDK appends the ingest route itself.

export EXPLAINABILITY_API_KEY="<your workspace ingest key>"
export EXPLAINABILITY_GATEWAY_URL="https://<your-workspace>.aisquare.studio"
export EXPLAINABILITY_AGENTS="support-bot"  # pre-registers; must equal the agent_name used in code

The governance surface (GovernedAgent, policy checks) also accepts AISQUARE_API_KEY and AISQUARE_INGEST_URL as aliases, but the pair above is read by every part of the SDK — use it. If you set AISQUARE_AGENT_NAME for policy checks, keep it equal to your agent_name: from SDK 1.0.6 it also serves as the fallback trace identity when no explicit name is set.

Every trace routes by (workspace, agent name) to a studio and a Rule Book — the name is the routing key, and setting it explicitly is the contract. For a raw pipeline, the name goes on the AgentRunTracer:

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:
        ...
sdk.flush()

For framework agents, one line each: Agno agents must be named (Agent(name="support-bot", ...)); LangChain callers pass config={"metadata": {"agent_name": "support-bot"}} on invoke; custom agents get agent_name= on the GovernedAgent wrapper in the next step. The full contract — multiple agents, naming rules, and what failure looks like — is on Agent identity.

No behavioural change. Traces ship automatically. from_agno requires the Agno agent to be named — either name the agent itself or pass agent_name= on the wrapper.

from aisquare import GovernedAgent

my_agent = Agent(name="support-bot", ...)     # Agno agents must be named
agent = GovernedAgent.from_agno(my_agent)     # or: from_agno(my_agent, agent_name="support-bot")
# run your agent exactly as before

For custom and OpenAI-wrapped agents, GovernedAgent.wrap(my_agent, agent_name=...) auto-traces .run() and .arun() (SDK 1.0.6). Streaming or generator-shaped run methods are not auto-traced — open an AgentRunTracer(agent_name=...) around the code that consumes the stream. See Agent identity.

Add a pre-tool policy gate, checked before each tool runs. The verdict it produces is the same one you see on the Prevent page. enforce=True requires the two environment variables from the Configure step.

agent = GovernedAgent.from_agno(
    my_agent,
    rule_book="your-rule-book",  # your synced policies
    enforce=True,                # check each tool before it runs: block / improve / warn
)

What you get: full traces with flow, graph, and plain-English narrative views; structured reasoning (claims, evidence, assumptions, and the policies each run triggered); policy verdicts; a signed, tamper-evident audit record with an AIBOM per run; and cost, plus the pre-tool enforcement gate.

Option B: Multi-provider proxy

The quickest way to begin, with no new dependency and no agent code change. Point your provider base URL at AISquare and send your workspace key as a header. Every LLM call then flows through a thin shim that traces it, screens it for PII, evaluates your policies (and, in Live, enforces them), and forwards the call to the real provider (streaming supported; in Live, streamed turns are checked before release).

This section is the short version; the full walkthrough, including the one-command connect script for the Claude Code and Codex CLIs and the per-provider reference, is at Proxy integration.

You get both from the dashboard Connectors page: generate your workspace API key (AIS_...) there — it is shown once, at creation — and the proxy URL is in the setup guide on the Proxy connector card.

Your provider key stays exactly where it is and still authenticates the model. The X-AISquare-Key header tells the proxy which workspace and Rule Book govern the run; with most SDKs, set it once in default_headers.

# Anthropic shown; OpenAI, Azure OpenAI, and Gemini work the same way
from anthropic import Anthropic

client = Anthropic(
    base_url="https://<proxy-host>",
    default_headers={"X-AISquare-Key": "AIS_<your-key>"},
)  # your ANTHROPIC_API_KEY passes through

The exact base URL and enforced paths for each provider (OpenAI, Azure OpenAI, Gemini) are in the per-provider reference.

Every call is now traced, cost-extracted, PII-screened, and policy-evaluated, and with your Rule Book in Live, it enforces in real time.

What you get: traces, cost, PII screening, policy verdicts, and live Rule Book enforcement (block / improve / warn / gate-in) on every run, with zero code.

How the proxy handles your provider key

The proxy sits inline in your live LLM path. Ungoverned agents and workspaces in Audit stream straight through untouched; a governed workspace in Live holds each turn just long enough to check it against your Rule Book (streamed turns are buffered, checked, then released). It uses your provider key only to forward the call, never written to a trace or stored. Auth and gateway outages fail closed for agents the proxy has seen enforcing, so a governed Live agent is never silently un-governed; Audit workspaces keep recording.

Already running OpenTelemetry?

The SDK attaches to your existing OpenTelemetry TracerProvider: install it, set the environment variables above, and call aisquare.explainability.init_from_env() — the spans your instrumentation already emits are captured as-is, no re-instrumentation. Those spans still need an agent identity to route: open an AgentRunTracer(agent_name=...) around the run, or set AISQUARE_AGENT_NAME as the single-agent fallback. (A direct OTLP ingest endpoint is not available today; the SDK is the integration path for existing OpenTelemetry setups.)

What your team will see

Once you are connected, every run shows up in your dashboard:

Traces, several ways. Each run as a flow diagram, a graph, and a plain-English narrative.
Reasoning. The claims the agent made, the evidence behind them, the assumptions it filled in, and the policies it triggered, structured, not a wall of transcript. See Understand.
Policy verdicts. Each run evaluated against your rule book; pass or block with a written reason and a citation to the exact rule. See Prevent.
Auditability. Each verdict cryptographically signed, plus an AIBOM (AI Bill of Materials) per run.
Cost. Per run, per agent, and per provider and model, with per-step cost in the flow view.

PII / PHI / PCI detection runs at ingest, before anything is persisted. Detection defaults to alert-only; set your data policy to mask to redact in place, or block to reject the trace. The policy is set per workspace, under Settings -> Security.

A practical rollout

Point your provider base URL at AISquare — zero code change — or add the SDK to an existing OpenTelemetry setup (one init call), with your rule books in Audit. You immediately get traces, reasoning, policy verdicts, and cost on every agent, and nothing is altered at runtime.

Flip the rule books that matter to Live and arm the actions you want on the agents that handle sensitive data or take irreversible actions. For an in-process gate at the tool boundary, or instrumentation beyond what the proxy captures, add the SDK to those agents. Same traces, no rework.

Bring the rest of the fleet onto whichever path each team prefers. Every run lands in the same place, so nothing is redone.

Connect your agents

Which path should I use?

SDK

Multi-provider proxy

Option A: SDK

Option B: Multi-provider proxy

Already running OpenTelemetry?

What your team will see

A practical rollout

Next steps

Agent identity

Proxy integration

Understand

Prevent

Quickstart

On this page