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.

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

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.
• Live enforcement. Your Rule Book 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

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

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

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)

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

Works in any language, no SDK. 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 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):

# 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

# 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

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

# 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

The tightest integration. 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:

# .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. Use this path when you want instrumentation beyond what the transparent proxy captures. See Connect your agents for the SDK path in full.

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

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.

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

• 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