Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fai%2Fguardrails%2Fguard_api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fai%2Fguardrails%2Fguard_api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Guard API

The `guard()` method provides full control over message history, making it ideal for multi-turn conversations and complex guardrail scenarios.

## Methods overview[​](#methods-overview "Direct link to Methods overview")

### `guard_prompt()`[​](#guard_prompt "Direct link to guard_prompt")

Guards user input before sending to the LLM. See [Getting Started with Guardrails](https://docs-docusaurus.kinsta.page/user-guides/ai/guardrails/getting_started/.md) for examples.

### `guard_response()`[​](#guard_response "Direct link to guard_response")

Guards LLM output after generation. Optionally accepts the original prompt for context-aware analysis. See [Getting Started with Guardrails](https://docs-docusaurus.kinsta.page/user-guides/ai/guardrails/getting_started/.md) for examples.

## The `guard()` method[​](#the-guard-method "Direct link to the-guard-method")

The `guard()` API accepts a list of messages with conversation context:

```
await guardrails.guard(

    messages=messages,

    guardrails=config,

    target=GuardrailsTarget.PROMPT,  # or GuardrailsTarget.RESPONSE

)
```

### Parameters[​](#parameters "Direct link to Parameters")

| Parameter    | Type                        | Description                                      |
| ------------ | --------------------------- | ------------------------------------------------ |
| `messages`   | `list[Message \| dict]`     | Conversation history as Message objects or dicts |
| `guardrails` | `list[GuardrailConfigType]` | List of guardrail policies to apply              |
| `target`     | `GuardrailsTarget`          | What to guard: `PROMPT` or `RESPONSE`            |

### Target types[​](#target-types "Direct link to Target types")

* `GuardrailsTarget.PROMPT` — Guards the latest user message in the conversation.
* `GuardrailsTarget.RESPONSE` — Guards the latest assistant message (must be the last message).

## Basic usage[​](#basic-usage "Direct link to Basic usage")

Guard a user prompt with conversation context:

```
import asyncio

from cx_guardrails import Guardrails, PII, PromptInjection, GuardrailsTarget, GuardrailsTriggered



async def main():

    guardrails = Guardrails()



    messages = [

        {"role": "system", "content": "You are a helpful assistant."},

        {"role": "user", "content": "What is machine learning?"},

        {"role": "assistant", "content": "Machine learning is a subset of AI..."},

        {"role": "user", "content": "Can you explain neural networks?"},

    ]



    async with guardrails.guarded_session():

        try:

            await guardrails.guard(

                messages=messages,

                guardrails=[PII(), PromptInjection()],

                target=GuardrailsTarget.PROMPT,

            )

            print("✓ Prompt passed")

        except GuardrailsTriggered as e:

            print(f"✗ Blocked: {e}")



asyncio.run(main())
```

Expected output:

```
✓ Prompt passed
```

## Conversations with tool calls[​](#conversations-with-tool-calls "Direct link to Conversations with tool calls")

When your LLM uses tools/functions, include tool messages in the conversation history. Tool call details and tool results should be in the `content` field:

```
import asyncio

from cx_guardrails import Guardrails, PII, PromptInjection, GuardrailsTarget, GuardrailsTriggered



async def main():

    guardrails = Guardrails()



    messages = [

        {"role": "system", "content": "You are a helpful assistant with access to tools."},

        {"role": "user", "content": "What's the weather in San Francisco?"},

        {"role": "assistant", "content": '[tool_call: get_weather({"location": "San Francisco"})]'},

        {"role": "tool", "content": '{"temperature": 65, "condition": "sunny"}'},

        {"role": "assistant", "content": "The weather in San Francisco is sunny with a temperature of 65°F."},

        {"role": "user", "content": "Thanks! Now what about New York?"},

    ]



    async with guardrails.guarded_session():

        try:

            await guardrails.guard(

                messages=messages,

                guardrails=[PII(), PromptInjection()],

                target=GuardrailsTarget.PROMPT,

            )

            print("✓ Prompt passed")

        except GuardrailsTriggered as e:

            print(f"✗ Blocked: {e}")



asyncio.run(main())
```

### Building tool call conversations incrementally[​](#building-tool-call-conversations-incrementally "Direct link to Building tool call conversations incrementally")

```
messages = [

    {"role": "user", "content": "What's the weather in Paris?"},

]



messages.append({"role": "assistant", "content": '[tool_call: get_weather({"location": "Paris"})]'})

messages.append({"role": "tool", "content": '{"temperature": 18, "condition": "cloudy"}'})

messages.append({"role": "assistant", "content": "The weather in Paris is cloudy with a temperature of 18°C."})
```

## Using the `Message` class[​](#using-the-message-class "Direct link to using-the-message-class")

For type safety and better IDE support, use the `Message` class instead of plain dicts:

```
from cx_guardrails import Guardrails, Message, Role, PII, GuardrailsTarget



async def main():

    guardrails = Guardrails()



    messages = [

        Message(role=Role.SYSTEM, content="You are a helpful assistant with access to tools."),

        Message(role=Role.USER, content="What's the weather in San Francisco?"),

        Message(role=Role.ASSISTANT, content='[tool_call: get_weather({"location": "San Francisco"})]'),

        Message(role=Role.TOOL, content='{"temperature": 65, "condition": "sunny"}'),

        Message(role=Role.ASSISTANT, content="The weather in San Francisco is sunny with a temperature of 65°F."),

    ]



    async with guardrails.guarded_session():

        await guardrails.guard(

            messages=messages,

            guardrails=[PII()],

            target=GuardrailsTarget.PROMPT,

        )
```

### Available roles[​](#available-roles "Direct link to Available roles")

| Role             | Description                |
| ---------------- | -------------------------- |
| `Role.SYSTEM`    | System instructions        |
| `Role.USER`      | User messages              |
| `Role.ASSISTANT` | LLM responses              |
| `Role.TOOL`      | Tool/function call results |

## Full guarded conversation example[​](#full-guarded-conversation-example "Direct link to Full guarded conversation example")

```
import asyncio

from openai import AsyncOpenAI

from cx_guardrails import Guardrails, Message, Role, PII, PromptInjection, GuardrailsTarget, GuardrailsTriggered



async def main():

    guardrails = Guardrails()

    openai_client = AsyncOpenAI()



    messages = [

        Message(role=Role.SYSTEM, content="You are a helpful assistant."),

        Message(role=Role.USER, content="What is AI observability? Explain in one sentence."),

    ]



    async with guardrails.guarded_session():

        try:

            await guardrails.guard(

                messages=messages,

                guardrails=[PII(), PromptInjection()],

                target=GuardrailsTarget.PROMPT,

            )

            print("✓ User input passed")

        except GuardrailsTriggered as e:

            return print(f"✗ Blocked: {e}")



        openai_messages = [{"role": m.role.value, "content": m.content} for m in messages]

        response = await openai_client.chat.completions.create(

            model="gpt-4o-mini",

            messages=openai_messages,

        )

        llm_response = response.choices[0].message.content



        messages.append(Message(role=Role.ASSISTANT, content=llm_response))



        try:

            await guardrails.guard(

                messages=messages,

                guardrails=[PII()],

                target=GuardrailsTarget.RESPONSE,

            )

            print("✓ LLM response passed")

        except GuardrailsTriggered as e:

            return print(f"✗ Response blocked: {e}")



        print(f"\n📝 AI RESPONSE:\n{llm_response}")



asyncio.run(main())
```

Expected output:

```
✓ User input passed

✓ LLM response passed



📝 AI RESPONSE:

AI observability refers to the tools and practices used to monitor, analyze, and understand the behavior and performance of AI models and systems in real-time.
```

## Error types[​](#error-types "Direct link to Error types")

| Exception                       | When it's raised                 | Recommended action                           |
| ------------------------------- | -------------------------------- | -------------------------------------------- |
| `GuardrailsTriggered`           | A guardrail detected a violation | Block the request, log the violation         |
| `GuardrailsAPITimeoutError`     | Request exceeded timeout         | Retry or implement fail-open/fail-closed     |
| `GuardrailsAPIConnectionError`  | Network connectivity issues      | Retry with backoff, alert on-call            |
| `GuardrailsAPIResponseError`    | API returned non-2xx status      | Log error, check API status                  |
| `GuardrailsConnectionTestError` | `test_connection()` failed       | Check credentials and endpoint configuration |

To disable exception throwing on guardrail trigger (fail-open behavior):

```
export DISABLE_GUARDRAILS_TRIGGERED_EXCEPTION=true
```

## Next steps[​](#next-steps "Direct link to Next steps")

Continuously assess the quality and safety of your AI outputs with [Evaluations](https://docs-docusaurus.kinsta.page/user-guides/ai/evaluations/.md).