Skip to Content

How Cygnal Works

How your agent checks requests and responses with Cygnal, picks a policy for each request, and handles violations

Cygnal checks your agent's traffic against a policy. Your agent keeps calling its LLM provider directly. At the points you choose, it sends the conversation to the Cygnal Monitor API at /cygnal/monitor. Cygnal checks the conversation against the policy, records the result in Activity, and returns a verdict. Your agent's code then decides whether to continue, block the response or only log it.

Because Cygnal sits beside your LLM call rather than in front of it, you don't change providers, SDKs or credentials, and you choose exactly which messages Cygnal sees.

Request flow

Your agent makes every call and gets a result back from each. Both Cygnal checks are optional: check the input, the output, or both. Cygnal never sits between your agent and the LLM provider, and records every check in Activity.
  1. Your agent receives a request. A user sends your agent a message.
  2. Check the input (optional). Before calling the model, your agent sends the conversation to /cygnal/monitor. If Cygnal reports a violation, your agent returns the policy's block message and stops.
  3. Call the model. Your agent calls its LLM provider and gets back the response, including any tool calls the model wants to make. Don't run the tool calls yet.
  4. Check the output (optional). Before the response reaches the user, or before a tool call runs, your agent sends the updated conversation to /cygnal/monitor again.
  5. Respond. If there's no violation, your agent returns the response or runs the tool call.

Both checks are optional. You can check only the input, only the output, or both. Each call to Cygnal returns its result to your agent, and your agent's code decides what to do with it.

Cygnal works alongside any guardrails you already run, such as your LLM provider's content moderation. Your agent can call them one after another or in parallel, and block the request if any of them flags it.

Where to check

You decide where your agent calls Cygnal, and you don't have to check everywhere. These are the places most agents check:

  • Input: The user's message, before the model sees it. Catches harmful requests and jailbreak attempts early, before you pay for a model call.
  • Output: The model's response, before it reaches the user. In an agent, also check each tool call before it runs.
  • Tool results: Content that tools bring back, such as web pages, files and API responses. Send these as role: "tool" messages so Cygnal can flag indirect prompt injection. The ipi field in the response is true when it finds one.

Each check adds latency to the request. Keep reasoning_mode set to off, the default, for production traffic. See Reasoning mode.

Send a check

Send a POST request to /cygnal/monitor on your Gray Swan API base URL, with your Gray Swan API key in the grayswan-api-key header. The body holds the content to check and the policy to check it against.

The examples on this page use https://api.grayswan.ai, the base URL of the hosted Gray Swan Platform. If you self-host Gray Swan, use your deployment's base URL instead.

import os
import requests

GRAYSWAN_API_KEY = os.environ["GRAYSWAN_API_KEY"]

response = requests.post(
    "https://api.grayswan.ai/cygnal/monitor",
    headers={"grayswan-api-key": GRAYSWAN_API_KEY},
    json={
        "messages": [
            {"role": "user", "content": "How can I hack into a computer system?"},
            {"role": "assistant", "content": "Here are some tips for hacking..."},
        ],
        "policy_id": "your-policy-id",
    },
)

result = response.json()
print(f"Violation score: {result['violation']}")
print(f"Observe-only signal: {result.get('observe_violation')}")

Request parameters

ParameterTypeDescription
messagesarrayOpenAI-compatible message objects to check. Each content can be a string or an array of content parts.
textstringPlain text to check, instead of messages. If you send both, Cygnal checks text.
policy_idstringThe policy to check against. Required. See Select a policy for each request.
rulesobjectExtra rules for this request, as rule names mapped to descriptions. They supplement the policy's rules.
reasoning_modeoff (default), hybrid or thinkingWhether Cygnal reasons before deciding. See Reasoning mode.

Content parts

Each messages[].content can be a plain string or an array of content parts, such as { "type": "text", "text": "..." } or { "type": "input_text", "text": "..." }. You don't need to flatten content parts into a single string first. Cygnal joins the text values of a message's parts, in order, before checking it.

{
  "messages": [
    {
      "role": "system",
      "content": [{ "type": "text", "text": "You are a helpful assistant." }]
    },
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Hello" },
        { "type": "text", "text": "Need help planning a trip." }
      ]
    }
  ],
  "policy_id": "your-policy-id",
  "reasoning_mode": "off"
}

For this request, Cygnal checks the user message as:

Hello
Need help planning a trip.

Reasoning mode

reasoning_mode controls whether Cygnal reasons internally before deciding whether content violates the policy. The reasoning isn't returned in the response, but it can improve detection quality.

  • off (default): Fastest, with no extra reasoning tokens. Recommended for most production traffic.
  • hybrid: Cygnal reasons when it needs to. Latency increases moderately. A good balance for higher-risk contexts.
  • thinking: Cygnal always follows guided reasoning before deciding. Highest latency and token usage. Use it when detection quality matters more than speed, such as offline analysis or security reviews.
{
  "text": "How can I hack into a computer system?",
  "policy_id": "your-policy-id",
  "reasoning_mode": "hybrid"
}

Select a policy for each request

Every request to the Monitor API must include a policy_id. Cygnal doesn't apply a default policy: a request without one returns 400 No policy specified.

Because you send the policy ID with each request, different agents can apply different policies even when they share code. For example, a support assistant and an internal coding agent can share a codebase but send different policy IDs. Create one policy for each agent or use case, store each policy ID in configuration, and choose the right one when you build the request.

To attribute requests to an agent in Activity, also send the agent's ID in the agent-id header. The agent ID doesn't replace policy_id: Cygnal enforces only the policies you send in policy_id, not the policies attached to the agent.

You can also send rules to add rules for a single request. These rules supplement the policy's rules. If a rule name appears in both, the policy's rule is used.

response = requests.post(
    "https://api.grayswan.ai/cygnal/monitor",
    headers={"grayswan-api-key": GRAYSWAN_API_KEY},
    json={
        "messages": [
            {"role": "user", "content": "I just won the lottery. What investments should I make?"}
        ],
        "rules": {
            "inappropriate_language": "Detect profanity and offensive language",
            "financial_advice": "Flag content that provides specific financial recommendations",
        },
        "policy_id": "your-policy-id",
    },
)

To find a policy ID, go to Cygnal → Policies, hover over the policy and select ⋯ → Copy Policy ID. To write your own policies, see Create and Manage Policies.

Handle violations in your agent

Cygnal reports violations. Your agent's code decides what happens next. These response fields drive that decision:

FieldUse it to
violationDecide whether to block. A score from 0 to 1, where higher means a violation is more likely.
violated_rule_descriptionsLog or show which rules were violated.
ipiDetect indirect prompt injection in tool results.
block_messageShow the user the policy's block message instead of the model's output.
observe_violationTrack violations of rules set to Observe without blocking.

Rules set to Observe don't raise violation. If every violated rule is an Observe rule, violation is 0.0 and observe_violation holds the original score, so the request goes through and the violation is still logged in Activity. If any violated rule is set to Block, observe_violation isn't used: rely on violation.

Response fields

FieldTypeDescription
violationnumberLikelihood of a violation, from 0.0 to 1.0, after Observe rules are suppressed.
observe_violationnumber, nullThe original score when every violated rule is an Observe rule. Otherwise null.
violated_rulesarrayIndices of the violated rules.
violated_rule_descriptionsarrayThe rule number, name and description of each violated rule.
mutationbooleanWhether Cygnal detected text formatting or mutation.
ipibooleanWhether Cygnal detected indirect prompt injection. Only set for tool messages.
applied_policiesarrayThe policy applied to the request, as an object with id and name.
block_messagestring, nullThe policy's block message, or null if the policy has none.
{
  "violation": 0.92,
  "observe_violation": null,
  "violated_rules": [2, 3],
  "mutation": false,
  "ipi": true,
  "violated_rule_descriptions": [
    { "rule": 2, "name": "Rule Name", "description": "Rule text" },
    { "rule": 3, "name": "Rule Name", "description": "Rule text" }
  ],
  "applied_policies": [{ "id": "your-policy-id", "name": "Your Policy" }],
  "block_message": "Message was blocked"
}

Block or allow

Decide what your agent does if Cygnal returns an error or doesn't respond in time. An error can come back as a failed HTTP status, or as a successful response with error set to true and the reason in error_message. Treat both the same way:

  • Fail closed: Block the request. Choose this when an unchecked response or tool call carries real risk.
  • Fail open: Let the request through and log it. Choose this when availability matters more than enforcement.

This example checks the input and the output of a chat request, and returns the block message when either check finds a violation. It fails closed:

import os
import requests
from openai import OpenAI

GRAYSWAN_API_KEY = os.environ["GRAYSWAN_API_KEY"]
POLICY_ID = os.environ["GRAYSWAN_POLICY_ID"]
BLOCK_THRESHOLD = 0.5  # Tune for your use case
FALLBACK_MESSAGE = "Sorry, I can't help with that."

llm = OpenAI()


def check(messages):
    """Return Cygnal's result, or None if the check failed or timed out."""
    try:
        response = requests.post(
            "https://api.grayswan.ai/cygnal/monitor",
            headers={"grayswan-api-key": GRAYSWAN_API_KEY},
            json={"messages": messages, "policy_id": POLICY_ID},
            timeout=10,
        )
        response.raise_for_status()
        result = response.json()
    except requests.RequestException:
        return None
    # Cygnal can return HTTP 200 with error set when it couldn't run the check
    if result.get("error"):
        return None
    return result


def blocked(result):
    if result is None:
        return True  # Fail closed. Return False here to fail open.
    return result.get("violation", 0.0) >= BLOCK_THRESHOLD


def block_message(result):
    return (result or {}).get("block_message") or FALLBACK_MESSAGE


def chat(messages):
    # 1. Check the input
    result = check(messages)
    if blocked(result):
        return block_message(result)

    # 2. Call your LLM provider as usual
    completion = llm.chat.completions.create(model="gpt-5", messages=messages)
    reply = completion.choices[0].message.content

    # 3. Check the output
    result = check(messages + [{"role": "assistant", "content": reply}])
    if blocked(result):
        return block_message(result)

    return reply

Best practices

  • Keep your agent's instructions in the system message. Put security rules, mode instructions and other agent-level prompts in the system message. Don't prepend them to the user's message. Cygnal reads everything in a user message as user input, so added instructions there can affect detection.
  • Check outputs, not only inputs. Input checks can't catch everything, such as a harmless-looking request that leads the model to an unsafe answer. Output checks matter most when your agent can take actions, such as running commands or calling APIs.
  • Send tool results. Indirect prompt injection arrives through content your agent reads, not through the user. Cygnal can only flag it if you send the tool messages.
  • Scope each policy to one agent. A policy written for what a specific agent should and shouldn't do is more accurate than one broad policy shared across agents. The Policy Assistant drafts rules from your agent's system prompt and tools.
  • Review Activity. Check Activity regularly, especially Observe violations, to see whether a rule is ready to block or needs rewording.

Next steps

On this page