Guardrails

Guardrails are content safety and prompt protection mechanisms that can be applied to agents to control input and output. The platform supports two types of guardrails: simple guardrails (enabled/disabled by name) and parameterized guardrails (configured with key-value parameters).

info

All agent types (Tool, Task, RAG, and Graph RAG) support guardrails with the same configuration and merging behavior.

Overview

Guardrails are applied at two levels:

1. Agent Configuration — Guardrails defined when creating or updating an agent, applied to all invocations
2. Invocation Time — Additional guardrails passed in individual invocation requests, applied only to that request

When guardrails are specified at both levels, they are merged using these rules:

• The effective guardrail list is the union of both sets
• For parameterized guardrails with the same name, parameters are deep-merged, with invocation-level parameters taking priority

Discovering Available Guardrails

Use the GET /v1/guardrails endpoint to discover the full list of supported guardrails in your environment, including their descriptions, whether they're recommended, and their parameter schemas.

Endpoint

GET /v1/guardrails

Sample Response:

{
  "guardrails": [
    {
      "name": "HAIP-Profanity",
      "description": "Reduces vulgar, offensive, or obscene language in user input and AI responses to preserve a respectful tone. The result is a professional communication space that helps protect users from disruptive or degrading language.",
      "isRecommended": false,
      "parameters": null,
      "mode": "pre_call"
    },
    {
      "name": "HAIP-Topic-Guardrail",
      "description": "Limits discussion of predefined restricted topics to support organizational, legal, or policy boundaries. The outcome is targeted risk control without affecting unrelated or permitted conversations.",
      "isRecommended": false,
      "parameters": {
        "input": {
          "type": "object",
          "properties": {
            "forbidden_topics": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Array of topics that the guardrail should block. Example: ['movies', 'gaming']"
            }
          },
          "required": ["forbidden_topics"]
        },
        "output": null
      },
      "mode": "pre_call"
    },
    {
      "name": "HAIP-Grounding-Custom",
      "description": "Requires responses to rely on the provided source context and discourages external or fabricated information. The outcome is high factual integrity, transparency, and trust in AI-generated outputs.",
      "isRecommended": false,
      "parameters": {
        "input": null,
        "output": {
          "type": "object",
          "properties": {
            "haip_guardrail_check": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "guardrail_name": { "type": "string" },
                  "is_grounded": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "guardrail_name",
                  "is_grounded"
                ]
              },
              "description": "Grounding check result returned in the response body. Each object contains 'guardrail_name' (str) and 'is_grounded' (bool)."
            }
          },
          "required": []
        }
      },
      "mode": "post_call"
    }
  ]
}

Discovery Best Practice

Always call GET /v1/guardrails to discover the current list of available guardrails rather than hardcoding guardrail names. The list of available guardrails is dynamic and managed at the platform level and may change over time.

Simple Guardrails

Simple guardrails are enabled or disabled by name only, with no configuration parameters.

Example

"guardrails": ["HAIP-Profanity", "HAIP-Insults-High"]

Parameterized Guardrails

Parameterized guardrails accept configuration parameters that customize their behavior. You can specify parameters when creating/updating an agent, and optionally override or extend them at invocation time.

Format

Guardrails can be specified as:

• A string (simple guardrail, backward compatible)
• An object with name and config fields (parameterized guardrail)

"guardrails": [
  "HAIP-Profanity",
  {
    "name": "HAIP-Topic-Guardrail",
    "config": {
      "forbiddenTopics": ["politics", "sports"]
    }
  }
]

Input Parameters

Input parameters customize the guardrail's behavior before the LLM generates a response. The /v1/guardrails endpoint returns the schema for each guardrail's input parameters under parameters.input.properties.

Example: Topic Guardrail with Input Parameters

Agent configuration:

{
  "name": "safety-agent",
  "agentType": "tool",
  "config": {
    "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "systemPrompt": "You are a helpful assistant.",
    "tools": [],
    "guardrails": [
      {
        "name": "HAIP-Topic-Guardrail",
        "config": {
          "forbiddenTopics": ["politics", "military"]
        }
      }
    ]
  }
}

Output Parameters

Output parameters provide informational signals after the LLM generates a response. These are advisory and informational, designed to provide signals without disrupting workflows.

Example: Grounding-Custom with Output Parameters

The HAIP-Grounding-Custom guardrail includes output parameters that indicate whether the LLM response is grounded on provided context:

{
  "type": "response.chunk",
  "chunk": {
    "guardrails": {
      "HAIP-Grounding-Custom": {
        "haipGuardrailCheck": [
          {
            "guardrailName": "HAIP-Grounding-Custom",
            "isGrounded": true
          }
        ]
      }
    }
  }
}

You can act on output parameters (e.g., log, flag for review, adjust confidence scores) without blocking execution.

Using Guardrails in Agent Configuration

Include guardrails in the agent's config to apply them to all invocations:

{
  "name": "support-agent",
  "agentType": "tool",
  "config": {
    "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "systemPrompt": "You are a customer support agent.",
    "tools": [],
    "guardrails": [
      "HAIP-Profanity",
      "HAIP-Insults-High",
      "HAIP-Prompt_attack-Medium",
      {
        "name": "HAIP-Topic-Guardrail",
        "config": {
          "forbiddenTopics": ["internal_policies", "financial_data"]
        }
      }
    ]
  }
}

Using Guardrails at Invocation Time

Pass guardrails in the invocation request body to apply them to a specific request only. These are applied in addition to any guardrails defined in the agent config:

{
  "messages": [
    {
      "role": "user",
      "content": "What's the latest news?"
    }
  ],
  "guardrails": [
    "HAIP-Hate-High",
    {
      "name": "HAIP-Topic-Guardrail",
      "config": {
        "forbiddenTopics": ["politics"]
      }
    }
  ]
}

Guardrail Merging Behavior

Simple Guardrails

When guardrails are specified at both the agent configuration and invocation levels, the effective list is the union of both sets (duplicates removed):

Agent config:

"guardrails": ["HAIP-Profanity", "HAIP-Insults-High"]

Invocation:

"guardrails": ["HAIP-Hate-High", "HAIP-Profanity"]

Result:

["HAIP-Profanity", "HAIP-Insults-High", "HAIP-Hate-High"]

Parameterized Guardrails

For parameterized guardrails with the same name specified at both levels, parameters are deep-merged, with invocation-level parameters taking priority:

Agent config:

"guardrails": [
  {
    "name": "HAIP-Topic-Guardrail",
    "config": {
      "forbiddenTopics": ["politics", "sports"],
      "threshold": 0.8
    }
  }
]

Invocation:

"guardrails": [
  {
    "name": "HAIP-Topic-Guardrail",
    "config": {
      "forbiddenTopics": ["tech"],
      "extra": "value"
    }
  }
]

Result:

"guardrails": [
  {
    "name": "HAIP-Topic-Guardrail",
    "config": {
      "forbiddenTopics": ["tech"],
      "threshold": 0.8,
      "extra": "value"
    }
  }
]

For parameterized guardrails with the same name, the configs are deep-merged at the dictionary level:

• Array/list parameters like forbiddenTopics from invocation-level config replace those from the agent config
• Other parameters present only in the agent config (like threshold) are preserved
• New parameters from the invocation config (like extra) are added

Handling Guardrail Blocks

Streaming Responses

When a guardrail blocks content (either input or output) in a streaming response, the response stream ends early with an IncompleteChunk object:

{
  "type": "response.incomplete",
  "responseId": "resp_abc123",
  "incompleteDetails": {
    "reason": "content_filter",
    "message": "Content violates guardrail policy"
  }
}

Check incompleteDetails.reason:

• "content_filter" — The request or response was blocked by a guardrail
• "error" — Something else went wrong (e.g., rate limiting, context-window overflow, the model's output being cut off by the configured inferenceConfig.maxTokens limit, runtime error)

incompleteDetails.message provides a human-readable explanation.

Non-Streaming Responses

For non-streaming requests, a guardrail block results in an HTTP error response (typically 400 or 422 depending on whether it's input or output validation).