Skip to main content
This guide explains how to use a safety model hosted on Fireworks as a guardrail in the TrueFoundry AI Gateway. The gateway sends each guarded prompt or response to your Fireworks safety model through the Fireworks chat completions API and enforces the model’s verdict.

​
How the integration works

Two model types are supported:
  • gpt-oss-safeguard classifies content against a policy you write. The policy goes in the system message, the content to classify goes in the user message, and the guardrail adds an instruction asking for a JSON verdict ({"violation": 0 or 1, "policy_category": ...}), so do not ask for another answer format in the policy.
  • Llama Guard classifies content against Meta’s fixed hazard categories. The model answers safe, or unsafe followed by the violated category codes. The policy field is ignored.
The guardrail runs as a Validate-only guardrail: content is classified and can be blocked, but it is never rewritten or redacted.

​
Prerequisites

  • A Fireworks API key.
  • A safety model running on a Fireworks on-demand (dedicated) deployment. See the Fireworks on-demand deployment guide to create one.
  • A deployment that stays running. Fireworks returns a 503 while a deployment scaled to zero starts up and does not queue requests, so set the deployment’s minimum replicas to at least 1 (or turn scale-to-zero off). See Fireworks autoscaling.
  • Network access from the AI Gateway to api.fireworks.ai.

​
Add the Fireworks guardrail

1

Pick Fireworks from the guardrail registry

From AI Gateway → Guardrails → Registry, select Fireworks under External Providers. See Get started with guardrails for the end-to-end flow of adding any guardrail.
2

Fill in the Fireworks form

A gpt-oss-safeguard guardrail without a policy fails every request with a guardrail error, because there is nothing for the model to apply.
3

Bind the guardrail to models with a rule

Attach the guardrail through a Guardrail Rule on the hooks you want: llm_input_guardrails, llm_output_guardrails, mcp_tool_pre_invoke_guardrails and mcp_tool_post_invoke_guardrails. See Guardrails Configuration for the full policy reference.

​
Enforcing strategy

Use Enforce for a guardrail that must not fail open.
Validate guardrails run in parallel with the model request, so a prompt that is later rejected has already reached the model. To run guardrails before the model, turn off Run Guardrails in Parallel with Model Request in the gateway guardrail settings.

​
Verify the integration

Select the guardrail on a request with the X-TFY-GUARDRAILS header, using the <group>/<guardrail-name> selector:
A rejected request carries a category-only message, for example Fireworks safety model policy violation (categories: hate speech). For gpt-oss-safeguard the category is shown only when it matches a line of your policy, and for Llama Guard it is the category name for the returned code. The message never includes the content, the model’s reasoning or the policy. You can inspect the full guardrail evaluation in AI Gateway → Monitor → Request Traces.

​
Limits

  • Output inspection is skipped for streamed responses.
  • Only text is classified. A request that is only an image or file, and a completion that is only tool calls, have nothing to classify, so no Fireworks call is made and the request passes.
  • At most 120,000 characters are sent per call. The content being classified must fit, otherwise the call is a guardrail error handled by your enforcing strategy; use the x-tfy-guardrails-scope request header to classify fewer messages in a long conversation. On the output hook the conversation context is trimmed, oldest first, to fit.
  • The guardrail timeout is the gateway-wide guardrail timeout, 5 seconds by default, and it is not configured per guardrail. The guardrail asks the model for low reasoning effort. A timeout is a guardrail error, so raise the gateway guardrail timeout if your model needs longer.
  • Llama Guard judges only the final turn of the conversation it is given, so when several messages are classified the guardrail folds them all into that final turn. An MCP tool result is sent as a user message, because Llama Guard conversations start with a user turn.

​
Reference