> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# guard • AI Agent SDK

> Global guard that blocks real model requests.

# guard

<Badge color="blue">AI Agent</Badge>

Global guard that blocks real model requests.

A test suite that stubs the model in *most* places still bills a provider (and
goes flaky) the moment one path slips through. This module is the single switch
that turns that silent slip into a loud failure::

from praisonaiagents.model\_harness import allow\_model\_requests

# conftest.py -- nothing in this suite may reach a provider

allow\_model\_requests(False)

Once blocked, the two request paths an :class:`~praisonaiagents.agent.Agent`
uses -- `LLM`/LiteLLM (Chat Completions and Responses, sync, async and
streaming) and the OpenAI-native client -- raise :class:`ModelRequestBlocked`
before any network I/O, and the message names the call site in *your* code that
triggered it.

Scope: this covers the agent's own turn-taking. Auxiliary model calls made by
other subsystems (memory scoring, embeddings) hold their own clients and are
not routed through these two paths.

A :class:`~praisonaiagents.model_harness.ScriptedModel` answers from its script
without touching either path, so scripted tests keep passing while the guard is
on. That is the intended pairing: block globally, script explicitly.

The initial state can also be set from the environment, which is handy for CI
without touching test code::

PRAISONAI\_ALLOW\_MODEL\_REQUESTS=0 pytest

Design note -- why :class:`BaseException`: the agent's tool loop wraps model
calls in broad `except Exception` handlers that degrade a failure into a
`None` result. A guard that can be swallowed is not a guard, so this error
follows the precedent pytest sets with its own outcome exceptions and derives
from `BaseException`.

## Import

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.model_harness import guard
```

## Classes

<CardGroup cols={2}>
  <Card title="ModelRequestBlocked" icon="brackets-curly" href="../classes/ModelRequestBlocked">
    Raised when a real model request is attempted while requests are blocked.
  </Card>
</CardGroup>

## Functions

<CardGroup cols={2}>
  <Card title="allow_model_requests()" icon="function" href="../functions/allow_model_requests">
    Allow or block real model requests process-wide.
  </Card>

  <Card title="model_requests_allowed()" icon="function" href="../functions/model_requests_allowed">
    Return whether real model requests are currently permitted.
  </Card>

  <Card title="no_model_requests()" icon="function" href="../functions/no_model_requests">
    Block real model requests for the duration of the `with` block.
  </Card>

  <Card title="check_model_request()" icon="function" href="../functions/check_model_request">
    Raise :class:`ModelRequestBlocked` if real model requests are blocked.
  </Card>
</CardGroup>

### Constants

| Name            | Value                                                         |
| --------------- | ------------------------------------------------------------- |
| `_PACKAGE_ROOT` | `os.path.dirname(os.path.dirname(os.path.abspath(__file__)))` |
| `_STDLIB_ROOT`  | `os.path.dirname(os.__file__)`                                |