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)

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)

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

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

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)

# 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 and TypeScript SDK.

---

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.

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

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

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

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

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

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:

# 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 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 — choose between SDK, gateway, and observability-first patterns

• Testing Guide — write tests for your Shield integration

• Shield REST APIs — direct runtime guardrail evaluation

• Multi-Protocol Gateway — provider configuration, routes, and MCP overview