# Connect your agents (/docs/govern/connect-your-agents)

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](/docs/govern/understand) regardless of how it got there.

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

Connecting is the only setup step. Everything in the Trust Loop
([Understand](/docs/govern/understand), [Prevent](/docs/govern/prevent),
[Fix](/docs/govern/fix), [Remember](/docs/govern/remember)) operates on the
decisions that flow in once an agent is connected.

## Which path should I use? [#which-path-should-i-use]

<Cards>
  <Card title="SDK" description="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." />

  <Card title="Multi-provider proxy" description="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." />
</Cards>

For the complete proxy guide (the coding-CLI connect script, the per-provider
reference, and enforcement semantics), see
[Proxy integration](/docs/govern/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                       |

<Callout intent="note" title="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.
</Callout>

## Option A: SDK [#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.)

<Steps>
  <Step title="Install">
    ```bash
    pip install "aisquare[explainability]"
    ```
  </Step>

  <Step title="Configure">
    Values come from your workspace settings. See
    [Authentication](/docs/getting-started/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.

    ```bash
    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.
  </Step>

  <Step title="Name your agent">
    Every trace routes by &#x2A;*(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`:

    ```python
    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](/docs/govern/agent-identity).
  </Step>

  <Step title="Wrap your agent">
    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.

    ```python
    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](/docs/govern/agent-identity).
  </Step>

  <Step title="Turn on enforcement (optional)">
    Add a pre-tool policy gate, checked before each tool runs. The verdict it
    produces is the same one you see on the [Prevent](/docs/govern/prevent) page.
    `enforce=True` requires the two environment variables from the Configure step.

    ```python
    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
    )
    ```
  </Step>
</Steps>

**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 [#option-b-multi-provider-proxy]

The quickest way to begin, with <Badge variant="status">no new dependency</Badge> 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](/docs/govern/proxy-integration).

<Steps>
  <Step title="Get your two values from the Connectors page">
    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.
  </Step>

  <Step title="Point your base URL at AISquare and add the header">
    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`.

    ```python
    # 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](/docs/govern/proxy-integration#per-provider-reference).
  </Step>

  <Step title="Run your agent unchanged">
    Every call is now traced, cost-extracted, PII-screened, and policy-evaluated,
    and with your Rule Book in Live, it enforces in real time.
  </Step>
</Steps>

**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.

<Callout intent="info" title="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.
</Callout>

### Already running OpenTelemetry? [#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](/docs/govern/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 [#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](/docs/govern/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](/docs/govern/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 [#a-practical-rollout]

<Steps>
  <Step title="Start with visibility">
    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.
  </Step>

  <Step title="Turn on enforcement where it matters">
    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.
  </Step>

  <Step title="Scale">
    Bring the rest of the fleet onto whichever path each team prefers. Every run
    lands in the same place, so nothing is redone.
  </Step>
</Steps>

## Next steps [#next-steps]

<Cards>
  <Card title="Agent identity" href="/docs/govern/agent-identity" description="The naming contract: how traces route, per integration path." />

  <Card title="Proxy integration" href="/docs/govern/proxy-integration" description="The full proxy guide: CLI connect script, per-provider reference, enforcement." />

  <Card title="Understand" href="/docs/govern/understand" description="See why an agent decided what it did, on the reasoning graph." />

  <Card title="Prevent" href="/docs/govern/prevent" description="Enforce policy at the decision point, before an action runs." />

  <Card title="Quickstart" href="/docs/getting-started/quickstart" description="Make your first authenticated request." />
</Cards>