AI gateway quickstart for Python — OpenAI & Anthropic compatible
Track, govern, and secure autonomous agents with exactly 1 line of code. Zero data-plane refactoring required.
New Kimss gateway integration starts at control-plane ONBOARDING.md. This repo is a tutorial demo of the invisible-proxy pattern — not a second contract.
Put an enforcement and observability layer between your Python application and OpenAI or Anthropic — identity, audit logging, spend limits, and kill switches — without rewriting your app.
Before → After
Before — call the provider directly:
from openai import OpenAI
client = OpenAI(api_key=OPENAI_API_KEY)
After — route through an AI gateway (one-line change):
from openai import OpenAI
client = OpenAI(
base_url="https://api.kimss.ai/v1",
api_key=KIMSS_API_KEY,
)
Your application keeps using the native OpenAI SDK. No model migration. No application rewrite. The gateway becomes the control point.
Try it now — no account required
Clone and run a local gateway simulator (no Kimss signup, no provider key, no network beyond localhost):
git clone https://github.com/kimss-ai/kimss-python-quickstart.git
cd kimss-python-quickstart
pip install -r requirements.txt
python demo_local_gateway.py
Expected output:
[ok] Request authenticated
[ok] Agent identified
[ok] Policy evaluated
[ok] Request routed
[ok] Audit event recorded
--- assistant reply ---
This reply came from the local gateway simulator — no provider was called.
Note: demo_local_gateway.py simulates the gateway contract on loopback. It is not Kimss itself and does not call any model provider. Use the 3-step setup below to route real traffic.
Try enforcement modes:
KIMSS_DEMO_MODE=kill_switch python demo_local_gateway.py # 403 agent_disabled
KIMSS_DEMO_MODE=exhausted python demo_local_gateway.py # 429 governed_requests_exhausted
Why this exists
AI agents increasingly have access to production APIs, databases, and internal tools. The model is only one part of the system.
This quickstart demonstrates how to insert an enforcement and observability layer between your application and the model provider — without rewriting the application. Kimss provides the gateway implementation; this repo shows the integration pattern.
Start here
1. OpenAI SDK — zero-refactor gateway (recommended)
example_02_openai_override.py — point the official openai client at the gateway with base_url + Agent-Id headers.
python example_02_openai_override.py
Then explore
3-step setup (real gateway)
1. Sign In & Vault
Create Free Account →. Open Governance → Connected Infrastructure and vault your provider endpoint + key.
2. Mint Key
Gateway → Generate Key at https://kimss.ai/app/keys. Copy kimss_... into KIMSS_API_KEY (alias KIMSS_WORKSPACE_KEY). Pick a stable agent_id slug for X-Kimss-Agent-Id — the Agents inventory row appears after the first attributed call (JIT). You do not need to pre-register the agent in the UI.
3. Route Traffic (zero refactoring)
git clone https://github.com/kimss-ai/kimss-python-quickstart.git
cd kimss-python-quickstart
pip install -r requirements.txt
cp .env.example .env # KIMSS_WORKSPACE_KEY / KIMSS_API_KEY, KIMSS_AGENT_ID, KIMSS_MODEL
python example_02_openai_override.py
Open Gateway → Recent calls to see the governed audit trail.
Dual-listener: OpenAI (/v1/chat/completions) and Anthropic (/v1/messages). Keep your native SDK.
import os
from openai import OpenAI
client = OpenAI(
base_url=os.getenv("KIMSS_GATEWAY_URL", "https://api.kimss.ai/v1"),
api_key=os.getenv("KIMSS_API_KEY") or os.getenv("KIMSS_WORKSPACE_KEY"),
)
resp = client.chat.completions.create(
model=os.getenv("KIMSS_MODEL", "custom:your-vaulted-model"),
messages=[{"role": "user", "content": "Hello via Kimss"}],
extra_headers={
"X-Kimss-Agent-Id": os.getenv("KIMSS_AGENT_ID", "my_agent"),
"X-Kimss-Agent-Name": os.getenv("KIMSS_AGENT_NAME", "My Agent"),
},
)
Troubleshooting
| Symptom | Likely cause | Fix |
|---|
401 / invalid API key | Wrong or missing KIMSS_WORKSPACE_KEY | Mint a new key under Gateway → Generate Key |
400 / missing agent | No X-Kimss-Agent-Id header | Set KIMSS_AGENT_ID and pass it via extra_headers |
403 / agent_disabled | Kill switch is on | Re-enable the agent under Agents (/app/agents) |
429 / governed_requests_exhausted | Monthly allowance reached | Wait for reset or upgrade at kimss.ai/pricing |
| Model not found | Model not vaulted | Vault the provider endpoint + model under Governance → Connected Infrastructure |
Related
License
MIT — see LICENSE.
