Developer Quick Start: Your First Governed AI Call

This guide takes you from zero to a governed AI call in under ten minutes. You will start the Keeptrusts gateway, point an LLM request at it, trigger a policy, and inspect the resulting decision event.

Use this page when

• You are making your first AI call through the Keeptrusts gateway.
• You need a minimal policy-config.yaml to start the gateway with a working policy.
• You want to see policy enforcement in action (a block) and inspect the resulting decision event.
• You are validating that your local setup (CLI, API key, provider) works end to end.

Primary audience

• Primary: Developers starting with Keeptrusts for the first time
• Secondary: AI Engineers evaluating the gateway, DevOps Engineers validating deployment

Prerequisites

• Keeptrusts CLI installed (kt binary on your PATH)
• An OpenAI API key (or any OpenAI-compatible provider key)
• Python 3.9+ with openai package, or curl

Step 1 — Write a Minimal Policy Config

Create a file called policy-config.yaml:

gateway:
  listen_port: 41002
providers:
  targets:
  - id: openai
    provider: 
    base_url: https://api.openai.com/v1
    secret_key_ref:
      env: OPENAI_API_KEY
policies:
- name: block-pii-output
  type: output_filter
  action: block
  pattern: '\b\d{3}-\d{2}-\d{4}\b'
  message: 'Response blocked: contains SSN-like pattern'
- name: log-all
  type: observe
  action: log

This configuration tells the gateway to block any response containing an SSN-like pattern and log every request.

Step 2 — Start the Gateway

export OPENAI_API_KEY="sk-..."
kt gateway run --policy-config policy-config.yaml

The gateway starts on http://localhost:41002 and is fully OpenAI-compatible. Any SDK that talks to the OpenAI API can point at this address instead.

Step 3 — Send a Request with curl

curl http://localhost:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Summarize the benefits of AI governance in two sentences."}
    ]
  }'

You get back a standard OpenAI-format JSON response — the gateway is transparent to the caller.

Step 4 — Send a Request with Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:41002/v1",
    api_key="sk-...",  # your real key; the gateway forwards it
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Explain zero-trust AI governance."}
    ],
)

print(response.choices[0].message.content)

The only change from standard OpenAI usage is base_url. Everything else — models, parameters, streaming — works identically.

Step 5 — Trigger a Policy Block

Ask the model something that might generate an SSN-like pattern:

curl http://localhost:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Generate a fake US social security number for testing."}
    ]
  }'

If the model output matches the SSN regex, you get a 409 Conflict response:

{
  "error": {
    "type": "policy_violation",
    "message": "Response blocked: contains SSN-like pattern",
    "policy": "block-pii-output",
    "code": "output_blocked"
  }
}

Your application receives a clear, structured error instead of leaked PII.

Step 6 — Inspect Decision Events

Every request that flows through the gateway produces a decision event. Query them through the control-plane API:

curl http://localhost:8080/v1/events?limit=5 \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN"

{
  "events": [
    {
      "id": "evt_01J...",
      "timestamp": "2026-04-23T10:15:32Z",
      "model": "gpt-4o",
      "provider": "openai",
      "policy_decisions": [
        {"policy": "block-pii-output", "action": "block", "matched": true}
      ],
      "status": "blocked"
    }
  ]
}

Events include the model, provider, every policy evaluation result, latency, and token counts — giving you full observability without changing application code.

Step 7 — Tail Events in Real Time

Use the CLI to stream events as they happen:

kt events tail --follow

This prints each decision event to stdout in real time — useful during development to see exactly what the gateway is doing.

What Just Happened

1. You wrote a two-policy config (block + observe).
2. You started a local gateway that speaks the OpenAI API.
3. You sent requests with curl and Python — zero SDK changes beyond base_url.
4. A policy blocked unsafe output and returned a structured 409 error.
5. You queried and tailed decision events for full audit trail.

Next steps

• OpenAI Python SDK Patterns — streaming, async, function calling
• TypeScript SDK Patterns — Node.js and Vercel AI SDK
• Error Handling — graceful handling of 409 blocks and 429 rate limits
• Streaming Patterns — SSE and chunked transfer through the gateway

The gateway is a drop-in proxy. Every example in this guide series works by changing a single URL — no vendor lock-in, no proprietary SDKs, no agent required.

For AI systems

• Canonical terms: kt gateway run, policy-config.yaml, decision event, output filter policy, observe policy, OpenAI-compatible gateway, base_url.
• CLI commands: kt gateway run --policy-config policy-config.yaml, kt events tail --follow.
• Gateway listens on http://localhost:41002 by default. Any OpenAI-compatible SDK works by changing base_url.
• Best next pages: OpenAI Python SDK Patterns, TypeScript SDK Patterns, Error Handling.

For engineers

• Prerequisites: kt CLI on PATH, an OpenAI API key (or any OpenAI-compatible provider key), Python 3.9+ or curl.
• Start with a two-policy config: one output_filter (block) and one observe (log) to see both enforcement and logging.
• The gateway is fully OpenAI-compatible — change only base_url in any SDK to route through it.
• Use kt events tail --follow during development for real-time visibility into what the gateway is doing.
• A blocked response returns HTTP 409 with a structured error envelope explaining which policy triggered.

For leaders

• The gateway is a transparent drop-in proxy — no proprietary SDKs, no vendor lock-in, no agent installation required.
• Developers adopt governance by changing a single URL in their existing code.
• Decision events provide full audit trail from day one without application-level instrumentation.
• The 10-minute quick start demonstrates the complete value prop: policy enforcement + observability + zero code change.