# Proxy integration (/docs/govern/proxy-integration)

The proxy is a drop-in gateway that sits between your agent and the model
provider. Point your agent's base URL at it, add one header, and every call
flows through unchanged, while AISquare records it and applies your policies in
real time. It works for Anthropic, OpenAI (Chat Completions and Responses),
Azure OpenAI, and Gemini, plus the Claude Code and Codex CLIs. No changes to
your agent logic; connect in one line, disconnect just as fast.

```text
Your agent (app, CLI, pipeline)  ->  AISquare proxy (record + enforce)  ->  Model provider
```

## What you get [#what-you-get]

* **Full recording.** Every request, tool call, and reply becomes a Run in your
  dashboard, with tokens, cost, and the full reasoning trace. See
  [Understand](/docs/govern/understand).
* **Live enforcement.** Your [Rule Book](/docs/govern/prevent) can block an
  unsafe tool call, rewrite a non-compliant reply, or flag a run, the moment it
  happens.
* **Every provider.** Anthropic, OpenAI (Chat Completions and Responses),
  Azure OpenAI, and Gemini, plus the Claude Code and Codex CLIs.
* **Your keys stay yours.** Your provider API key passes straight through to
  the model. The proxy never stores it.

## Before you start [#before-you-start]

From the AISquare dashboard you need two things, and both come from the
**Connectors** page (the key is shown once, at creation; the proxy URL is in
the **Proxy connector** card's setup guide):

1. Your **workspace API key** (`AIS_...`).
2. Your **production proxy URL**.

Everywhere below, replace `<proxy-host>` and `AIS_<your-key>` with those
values.

## Two keys, one hop [#two-keys-one-hop]

Requests carry two credentials. Your provider key authenticates the model call
and is forwarded untouched. Your AISquare workspace key, sent as the
`X-AISquare-Key` header, tells the proxy which workspace and Rule Book govern
the run.

Headers on every request: `X-AISquare-Key: AIS_...` (workspace auth) plus your
existing provider key (`x-api-key` or `Authorization`), forwarded to the model.
The proxy also streams the run to your dashboard; nothing else leaves your
provider path.

## Three ways in [#three-ways-in]

Whichever path you choose, you keep your existing provider key and change
nothing about your agent's behavior.

### Option A: coding CLIs (Claude Code and Codex) [#option-a-coding-clis-claude-code-and-codex]

The Connectors page gives you a one-command script that configures both CLIs.
No hand-editing of `settings.json` or `config.toml`. In the dashboard, open
**Connectors -> Proxy connector**, paste your `AIS_` key, and download
`aisquare-connect.sh` — the key is embedded client-side and never travels in a
URL.

```bash
bash aisquare-connect.sh on       # route Claude Code + Codex through AISquare
bash aisquare-connect.sh status   # check state + connectivity
bash aisquare-connect.sh off      # disconnect and remove the AISquare settings
```

Then run `claude` or `codex` as usual. Every session shows up as a Run.
`off` restores Codex's previous model provider exactly; if you had pointed
Claude Code at a custom `ANTHROPIC_BASE_URL` of your own before connecting,
re-add it after disconnecting.

### Option B: backend or agentic pipeline [#option-b-backend-or-agentic-pipeline]

Works in <Badge variant="status">any language, no SDK</Badge>. Already calling
a provider from your own code? Point that SDK at the proxy and add one header,
the same `X-AISquare-Key` on every request. Your provider key still
authenticates the model. Two optional headers make runs cleaner:
`X-Agent-Name` (a stable [agent identity](/docs/govern/agent-identity) your
Rule Book can bind to; without it the proxy falls back to the pipeline id,
then to `claude-code`) and `X-Pipeline-Id` (groups a pipeline's calls into one
Run). Setup per provider (Python shown):

```python
# Anthropic (Claude)
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
```

```python
# OpenAI (Chat Completions + Responses, Codex)
from openai import OpenAI

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

```python
# Azure OpenAI (set your resource endpoint once in the dashboard first)
from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://<proxy-host>",   # the proxy, not your resource
    api_version="2024-10-21",
    api_key="<your-azure-api-key>",          # passes through
    default_headers={"X-AISquare-Key": "AIS_<your-key>"},
)
```

The `api-version` your client sends is forwarded verbatim to your Azure
resource; the version field on the dashboard's Azure card is informational.

```python
# Gemini (google-genai)
from google import genai

client = genai.Client(
    api_key="<your-gemini-key>",             # passes through
    http_options={"base_url": "https://<proxy-host>",
                  "headers": {"X-AISquare-Key": "AIS_<your-key>"}},
)
```

### Option C: Python SDK [#option-c-python-sdk]

The <Badge variant="status">tightest integration</Badge>. For richer control
(custom spans, enrichers, and inline governance), `pip install
"aisquare[explainability]"` and initialize it once. The minimal working shape
is an `AgentRunTracer` around your run, with your LLM calls traced inside it:

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

`agent_name` is the routing key — see
[Agent identity](/docs/govern/agent-identity). Use this path when you want
instrumentation beyond what the transparent proxy captures. See
[Connect your agents](/docs/govern/connect-your-agents) for the SDK path in
full.

## Per-provider reference [#per-provider-reference]

All providers carry the same `X-AISquare-Key` header and forward your provider
credentials unchanged. Only Azure needs one extra step: its per-workspace
resource endpoint is set once in the dashboard (the proxy stores the endpoint,
never a key).

| Provider                | Base URL                                      | Enforced paths                                                                       |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ |
| Anthropic + Claude Code | `https://<proxy-host>`                        | `/v1/messages`, stream and non-stream                                                |
| OpenAI + Codex CLI      | `https://<proxy-host>/v1`                     | `/v1/chat/completions`, `/v1/responses` (Codex)                                      |
| Azure OpenAI            | `https://<proxy-host>` (SDK `azure_endpoint`) | `/openai/deployments/.../chat/completions`; set your resource in the dashboard first |
| Gemini                  | `https://<proxy-host>`                        | `:generateContent`; streaming enforces with `?alt=sse`                               |

## What the Rule Book can do [#what-the-rule-book-can-do]

Each rule book has a **Live / Audit-only** switch on the dashboard's Rules
page. Audit records
and flags but never alters a run; start there. Live applies the actions below
in real time.

| Action    | What happens                                                                                                                                                                                                              |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `block`   | An unsafe tool call is withheld before it runs, and the agent is handed the reason, so it re-plans a safe alternative on the spot.                                                                                        |
| `improve` | A non-compliant reply is rewritten to comply (for example, a hard-coded secret becomes an env-var read). Runs on AISquare's side, so it works for every provider.                                                         |
| `warn`    | The run proceeds untouched but is flagged in the dashboard for review, for advisory policies.                                                                                                                             |
| `gate-in` | Tool outputs coming back into the agent are checked against your retrieval-scope rules (for example, a prompt-injection rule) and sanitized before the model sees them. Covers Anthropic, OpenAI, and Codex tool outputs. |

## Verify [#verify]

* Make one call through the proxy. It appears as a Run in your dashboard
  within seconds.
* With a blocking rule armed and its rule book in Live, trigger it. The
  enforcement event shows on the run with a before and after.

## Operate with confidence [#operate-with-confidence]

* **Reversible.** Disconnect any time (`off`, or remove the base URL). `off`
  removes the AISquare settings; Codex's previous provider is restored.
* **Low overhead.** Ungoverned agents and workspaces in Audit stream straight
  through untouched. A governed workspace in Live adds a policy check per
  gated turn, and streamed turns are held until they clear the gate, then
  released. Streaming is fully supported.
* **Fails safe.** 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. What happens when an improve rewrite cannot
  be produced is configurable per proxy deployment: fail open to the original
  reply (default) or withhold it.
* **Your data path is unchanged.** Provider keys pass through and are never
  stored; the only added destination is your own AISquare dashboard, over TLS.

## Next steps [#next-steps]

<Cards>
  <Card title="Connect your agents" href="/docs/govern/connect-your-agents" description="The proxy and the SDK side by side, and when to use which." />

  <Card title="Prevent" href="/docs/govern/prevent" description="Rule Books, verdicts, and enforcement at the decision point." />

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

  <Card title="Authentication" href="/docs/getting-started/authentication" description="Where your workspace keys live and how to rotate them." />
</Cards>