# Integration Examples

This page shows common ways to integrate Highflame into your application: **Gateway integration** for centralized model traffic control, and **SDK integration** for direct, in-code guardrails. Choose the pattern that fits your architecture — or combine both.

***

## SDK Integration — Direct Guardrails

Guard prompts, tool calls, and model responses directly from your application code. The SDK calls Shield's API and enforces Cedar policies inline.

### Guard a Prompt (Python)

```python
from highflame import Highflame, Shield, BlockedError

client = Highflame(api_key="hf_sk_...")
shield = Shield(client)

@shield.prompt(mode="enforce")
def chat(message: str) -> str:
    return openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": message}],
    ).choices[0].message.content

try:
    reply = chat("Summarize the quarterly report")
except BlockedError as e:
    print(f"Blocked: {e.response.policy_reason}")
```

### Guard a Prompt (TypeScript)

```typescript
import { Highflame, Shield, BlockedError } from "@highflame/sdk";

const client = new Highflame({ apiKey: "hf_sk_..." });
const shield = new Shield(client);

const chat = shield.prompt(async (message: string) => {
  const resp = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: message }],
  });
  return resp.choices[0].message.content;
});

try {
  const reply = await chat("Summarize the quarterly report");
} catch (err) {
  if (err instanceof BlockedError) {
    console.error("Blocked:", err.response.policy_reason);
  }
}
```

### Guard a Tool Call

```python
@shield.tool(mode="enforce")
def run_query(sql: str, database: str) -> str:
    return db.execute(sql, database)

# All arguments (sql, database) are sent as tool context to Shield
result = run_query("SELECT * FROM users", "production")
```

### Guard a Model Response (Hallucination Detection)

```python
from highflame import GuardRequest

resp = client.guard.evaluate(GuardRequest(
    content=model_output,
    content_type="response",
    action="process_prompt",
    mode="enforce",
    contexts=[original_prompt, *rag_chunks],  # reference material for grounding
))

if resp.decision == "deny":
    print(f"Blocked: {resp.policy_reason}")
```

### Framework Integrations (Python)

```python
# LangGraph
from highflame.integrations.langgraph import HighflameMiddleware
middleware = HighflameMiddleware(client, mode="enforce")
app = graph.compile(middleware=[middleware])

# CrewAI
from highflame.integrations.crewai import HighflameCrewHooks
with HighflameCrewHooks(client, mode="enforce"):
    crew.kickoff()

# AWS Strands
from highflame.integrations.strands import HighflameStrandsHooks
agent = Agent(model=model, tools=tools, hooks=[HighflameStrandsHooks(client)])
```

For full SDK documentation, see [Python SDK](https://github.com/highflame-ai/highflame-docs/blob/main/api-reference/sdk/shield/python-sdk.md) and [TypeScript SDK](https://github.com/highflame-ai/highflame-docs/blob/main/api-reference/sdk/shield/typescript-sdk.md).

***

## Gateway Integration — Centralized Protection

Route LLM traffic through the Highflame Agent Gateway to apply guardrails, observability, and governance without changing application code.

You will need:

* a Highflame API key
* a route or gateway configuration in Highflame
* the upstream provider credential your application already uses

### Example 1: Keep Your OpenAI-Compatible Client

This is the fastest path when your application already speaks the OpenAI Chat Completions API. Point your client at Highflame and add the `x-highflame-api-key` header.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=f"{os.environ['HIGHFLAME_BASE_URL']}/v1",
    default_headers={
        "x-highflame-api-key": os.environ["HIGHFLAME_API_KEY"],
    },
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize the top three launch risks."},
    ],
)

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

What changes:

* `base_url` points to Highflame instead of the upstream provider
* `model` uses the `provider/model` format
* `x-highflame-api-key` identifies your Highflame project and policies

### Example 2: Use TypeScript With the OpenAI SDK

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: `${process.env.HIGHFLAME_BASE_URL}/v1`,
  defaultHeaders: {
    "x-highflame-api-key": process.env.HIGHFLAME_API_KEY!,
  },
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Summarize the top three launch risks." },
  ],
});

console.log(response.choices[0]?.message?.content);
```

### Example 3: Route Different Providers Through One API

Highflame accepts OpenAI-style requests and uses the `provider/model` value to route traffic to the correct upstream provider.

Examples: `openai/gpt-4o`, `anthropic/claude-sonnet-4-20250514`, `azure/my-gpt-4o-deployment`, `gemini/gemini-2.0-flash`, `groq/llama-3.3-70b-versatile`

```bash
curl "${HIGHFLAME_BASE_URL}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ANTHROPIC_API_KEY}" \
  -H "x-highflame-api-key: ${HIGHFLAME_API_KEY}" \
  -d '{
    "model": "anthropic/claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "Draft a project update for leadership."}
    ]
  }'
```

### Example 4: Responses API Through Highflame

```bash
curl "${HIGHFLAME_BASE_URL}/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${OPENAI_API_KEY}" \
  -H "x-highflame-api-key: ${HIGHFLAME_API_KEY}" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "Create a short summary of the weekly incident review."
  }'
```

### Example 5: Azure OpenAI

```bash
curl "${HIGHFLAME_BASE_URL}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${AZURE_OPENAI_API_KEY}" \
  -H "x-highflame-api-key: ${HIGHFLAME_API_KEY}" \
  -d '{
    "model": "azure/gpt-4o-production",
    "messages": [
      {"role": "user", "content": "Draft a customer-safe incident summary."}
    ]
  }'
```

### Example 6: AWS Bedrock

| Endpoint                           | Method | Description                                                      |
| ---------------------------------- | ------ | ---------------------------------------------------------------- |
| `/model/{model-id}/{apivariation}` | POST   | Route requests to a specific AWS Bedrock model and API variation |

**Path Parameters:**

* `model-id`: The Bedrock model identifier
* `apivariation`: `invoke`, `invoke-stream`, `converse`, `converse-stream`

```bash
curl -X POST "https://api.highflame.ai/v1/model/anthropic.claude-3-sonnet-20240229-v1:0/invoke" \
  -H "Content-Type: application/json" \
  -H "X-Highflame-apikey: $HIGHFLAME_API_KEY" \
  -H "X-Highflame-route: $HIGHFLAME_ROUTE_BEDROCK" \
  -d '{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 100,
    "messages": [
      {
        "content": "What is the capital of France?",
        "role": "user"
      }
    ]
  }'
```

***

## Combining Both Patterns

Use Gateway integration for centralized model traffic protection and SDK integration for guarding tool calls and agentic workflows:

```python
# Gateway handles: prompt → model → response guardrails automatically
# SDK handles: tool execution guardrails in your agent loop

@shield.tool(mode="enforce")
def execute_tool(name: str, args: dict) -> str:
    return tool_registry[name](**args)

# Model calls go through Gateway (guardrails applied at infrastructure level)
# Tool calls are guarded inline by Shield SDK
```

## How To Choose

Use the **gateway examples** on this page when you want the least disruptive integration path with centralized routing, observability, and governance.

Use the [Shield SDK](https://github.com/highflame-ai/highflame-docs/blob/main/api-reference/sdk/shield/README.md) when you want per-step enforcement inside agent workflows — guarding prompts, tool calls, model responses, or file operations directly in code.

## Next Steps

* [Securing Agents](/getting-started/securing-agents.md) — choose between SDK, gateway, and observability-first patterns
* [Testing Guide](/getting-started/testing-guide.md) — write tests for your Shield integration
* [Shield REST APIs](https://github.com/highflame-ai/highflame-docs/blob/main/api-reference/rest-endpoints/shield-rest-apis.md) — direct runtime guardrail evaluation
* [Multi-Protocol Gateway](/agent-gateway/ai-gateway.md) — provider configuration, routes, and MCP overview


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/getting-started/securing-agents/custom-agents/gateway-integration-examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.