Metadata-Version: 2.4
Name: mistralai-agentic-security
Version: 0.1.0a7
Summary: Guardrails for Mistral Agents, and a typed client to manage Agentic Security rules, policies and alerts as code.
Author: Mistral
License: Apache-2.0
Project-URL: homepage, https://docs.mistral.ai/studio
Project-URL: documentation, https://docs.mistral.ai/studio
Keywords: ai,agentic,safety,guardrails,security,mistral,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.11.2
Provides-Extra: guardrails
Requires-Dist: mistralai-agents<2,>=1.1.2; (python_version >= "3.12" and python_version < "3.15") and extra == "guardrails"
Requires-Dist: mistralai-vibe-sdk[telemetry]<0.15,>=0.14.0; (python_version >= "3.12" and python_version < "3.15") and extra == "guardrails"

# mistralai-agentic-security

<!--
  Hand-owned README. The generated Speakeasy sections are opted out with
  `<!-- No <Section> [tag] -->` markers, so regeneration keeps this text.
  Examples follow agentic_safety/docs/. See clients/README.md.
-->

Agentic Security checks what your agents read and write against your rules, and acts on what
they catch: it redacts, blocks, asks a human, or unplugs a tool.

This package has two parts:

- **`Guardrails`**, a hook for [Mistral Agents](https://pypi.org/project/mistralai-agents/) that
  applies your policies to every turn and tool call.
- **`AgenticSafetyClient`**, a typed client to manage rules, policies and alerts as code.

## Install

```bash
uv add "mistralai-agentic-security[guardrails]" mistralai-agents
```

The `guardrails` extra needs Python 3.12 to 3.14. The client alone (`uv add
mistralai-agentic-security`) runs on Python 3.10 and later.

Both read your [Mistral API key](https://console.mistral.ai/api-keys) from the environment:

```bash
export MISTRAL_API_KEY="<your api key>"
```

## Protect an agent

Create a policy in [Mistral Studio](https://console.mistral.ai/agentic-safety/policies), then pass
its tag to `Guardrails`:

```python
import asyncio

from mistral.agentic_safety.guardrails import Guardrails
from mistralai.agents import agents


async def main() -> None:
    agent = agents.Agent(
        model="mistral-large-4-0",
        instructions="Answer in one sentence.",
        guardrails=[Guardrails(tags=["policy_id:01a1c12f-c1e6-7663-8d73-846c1833ea32"])],
    )

    result = await agent.run("Reply to: Bob was charged twice on card 4539 1488 0343 6467. He wants a refund.")
    print(result.text)


asyncio.run(main())
```

```text
Hi Bob, thanks for flagging this, we've confirmed the duplicate charge and sent a refund.
```

With a policy that redacts card numbers, the model drafts the reply without ever seeing the card
number. A turn that a rule blocks stops before the model runs.

## Manage rules as code

A **rule** says when to check (hooks), what to look for (scanners), and what to do (cases). A
**policy** groups rules and turns them on.

```python
import asyncio

from mistral.agentic_safety import AgenticSafetyClient, models


async def main() -> None:
    client = AgenticSafetyClient()

    rule = await client.rules.create_rule_async(
        name="Redact card numbers",
        hooks=[models.Hook(name="pre_agent_turn", ctx_last_user=True)],
        scanners=[
            models.PatternScanner(
                name="pii",
                patterns=[models.PatternEntry(label="credit_card", regex=r"\b(?:\d[ -]?){13,16}\b")],
            )
        ],
        cases=[
            models.Case(
                name="credit card",
                condition=models.Condition(
                    clauses=[
                        models.Comparison(
                            op=models.Op.GREATER_THAN_,
                            left=models.EvidenceOperand(scanner="pii", label="credit_card"),
                            right=models.NumberOperand(value=0),
                        )
                    ]
                ),
                verdict=models.Verdict.ALLOW,
                side_effects=[models.RedactSideEffect()],
            )
        ],
    )

    policy = await client.policies.create_policy_async(
        name="Card numbers",
        enabled=True,
        rule_ids=[rule.id],
    )
    print(policy.tags)  # pass these to Guardrails(tags=...)


asyncio.run(main())
```

## Concepts

| | |
| --- | --- |
| **Hook** | When a rule runs: `pre_agent_turn`, `post_agent_turn`, `pre_tool_call`, `post_tool_call`. `ctx_*` flags pick the content it reads. |
| **Scanner** | What to look for: `PatternScanner`, `EntityScanner`, `ModerationScanner`, `SimilarityScanner`, `LLMScanner`, or your own code with `HarnessScanner`. Each reports evidence named `<scanner>.<label>`. |
| **Case** | A condition on the evidence, a verdict, and side effects. |
| **Verdict** | `allow`, `human_validation`, `block`, `terminate`. The most restrictive matching case wins. |
| **Side effect** | `redact`, `unplug` a tool, `notify_user`, or `custom_callback`. |
| **Policy** | Groups rules, and applies to the agents that send its tags. |

## Configuration

| Environment variable | Default | Used for |
| --- | --- | --- |
| `MISTRAL_API_KEY` | | authentication |
| `AGENTIC_SAFETY_SERVER_URL` | `https://api.mistral.ai` | the server `Guardrails` calls |

`Guardrails` fails open: if the service can't be reached, the turn goes on. Pass
`fail_closed_on_error=True` to block it instead.

<!-- No Summary [summary] -->
<!-- No Table of Contents [toc] -->
<!-- No SDK Installation [installation] -->
<!-- No IDE Support [idesupport] -->
<!-- No SDK Example Usage [usage] -->
<!-- No Authentication [security] -->
<!-- No Available Resources and Operations [operations] -->
<!-- No Retries [retries] -->
<!-- No Error Handling [errors] -->
<!-- No Server Selection [server] -->
<!-- No Custom HTTP Client [http-client] -->
<!-- No Resource Management [resource-management] -->
<!-- No Debugging [debug] -->

<!-- Placeholder for Future Speakeasy SDK Sections -->
