An explainable policy analyzer and enforcement gateway for AI agents.
Python
0
39 commits
updated Sep 15, 2026
A security control layer for AI agents.
English | 简体中文
Agent Guardrail checks model requests, model output, tool calls, and tool results before they proceed to the next step, then allows, records, or blocks them according to YAML rules.
It preserves relationships among messages, model calls, and tool calls, and produces masked findings, error messages, and audit records.
The current version is v0.1.0 alpha. The project provides in-process and HTTP Gateway integration, supports OpenAI, Anthropic, and MCP, and supports separate deployment of policy analysis.
Requirements: Python 3.12 or later and uv.
git clone https://github.com/cipeizheng/agent-guardrail.git
cd agent-guardrail
uv sync --frozen --extra gateway --dev
uv run python examples/secret_email_demo.py
The demo uses local model and tool implementations, so it needs no API key. The model call runs, while the email tool call is blocked before execution. The final lines are:
policy decision: block
model executions: 1
send_email executions: 0
Policies use the version-3 YAML format. This example checks a send_email call and blocks it before execution when its arguments contain a secret or other sensitive credential.
version: 3
scopes: [pending]
rules:
- id: prevent-secret-email
action: block
events:
call: {kind: tool_call_proposal, domain: pending}
where:
all:
- tool: {binding: call, name: send_email}
- detector:
id: secret_scan
capability: secrets
inputs:
- value: {field: [call, payload, arguments]}
encoding: canonical_json
finding:
code: secret_exfiltration
message: The proposed tool call contains secret material.
subjects: [call]
evidence: [{source: detector, id: secret_scan}]
The loader checks the format, references, resource limits, and available detection capabilities before activating a policy. See the Policy authoring guide for the complete syntax.
The default local profile provides the following local checks without model downloads or external services. The names in the table are used in policy files:
| What it checks | Purpose | Policy name |
|---|---|---|
| Secrets and credentials | Finds private keys, cloud credentials, and API tokens | secrets |
| Personal information | Finds fixed types such as email, phone, identity, and financial numbers | pii |
| Prompt injection signals | Finds high-signal instruction overrides, prompt disclosure, and role changes | prompt_injection |
| Invisible or confusing text | Finds Unicode controls, zero-width characters, and limited mixed-script tricks | unicode_security |
| Python code structure | Reports imports, risky calls, and syntax facts | python_ast_ipython |
| Hidden web content | Finds hidden HTML, comments, and bounded encoded content | hidden_content |
| Numeric or length ranges | Checks numbers, text, arrays, and objects against bounds | number_in_range, length_in_range |
| URL host allowlists | Checks whether an HTTP(S) URL uses an allowed host | url_host_allowed |
| Approximate text matching | Finds text within a bounded edit distance | fuzzy_contains |
Other detection capabilities, integration methods, and status are maintained in the capability matrix; detailed setup is in the capability reference and operations guide.
Detection results are signals. Rules should also use the data source, destination, authorization, and relationships among the message, model call, and tool call involved in the protected operation.
Guardrail checks events submitted through its SDK and requests handled by its Gateway. With the SDK, application code reads the returned decision before performing the operation; the Gateway enforces that ordering for model and MCP requests. Agent code that can run shell commands, arbitrary code, direct network calls, or host operations still requires a separate sandbox with default-deny egress, minimal temporary storage, and resource limits. Keep provider or tool credentials and audit storage outside that sandbox. The security model and operations guide define the responsibility split.
Deployment details and responsibility boundaries are described in the operations guide and security model. Future work is listed in the roadmap; the current architecture contract defines current behavior.
| Read | For |
|---|---|
| Documentation map | The shortest path for each task |
| Architecture overview | The end-to-end Event, Policy, Runtime, and Enforcement flow |
| Policy authoring | Writing version-3 YAML |
| Integration guide | Connecting application code, model clients, and MCP |
| Capability reference | Detector and Predicate contracts |
| Gateway protocol | HTTP, streaming, and MCP wire behavior |
| Responses state-layer design | previous_response_id state interface and external state-owner boundary |
| Operations guide | Profiles, environment variables, Docker, audit, and health |
| Security model | Assets, trust boundaries, and T01–T10 |
| Separate analysis service design | Deploying policy analysis separately |
| Long-session capacity evaluation | Regressing full, incremental shadow/active, and Remote Core v4 paths |
uv sync --frozen --extra gateway --dev
uv run pytest --cov=agent_guardrail --cov-report=term-missing
uv run ruff check .
uv run pyright
uv build
git diff --check
See CONTRIBUTING.md for the development workflow.
Agent Guardrail is available under the MIT License. Optional detector assets and dependencies retain their upstream licenses; consult the operations guide before deploying a model profile.
An explainable policy analyzer and enforcement gateway for AI agents.
Python
0
39 commits
updated Sep 15, 2026
A security control layer for AI agents.
English | 简体中文
Agent Guardrail checks model requests, model output, tool calls, and tool results before they proceed to the next step, then allows, records, or blocks them according to YAML rules.
It preserves relationships among messages, model calls, and tool calls, and produces masked findings, error messages, and audit records.
The current version is v0.1.0 alpha. The project provides in-process and HTTP Gateway integration, supports OpenAI, Anthropic, and MCP, and supports separate deployment of policy analysis.
Requirements: Python 3.12 or later and uv.
git clone https://github.com/cipeizheng/agent-guardrail.git
cd agent-guardrail
uv sync --frozen --extra gateway --dev
uv run python examples/secret_email_demo.py
The demo uses local model and tool implementations, so it needs no API key. The model call runs, while the email tool call is blocked before execution. The final lines are:
policy decision: block
model executions: 1
send_email executions: 0
Policies use the version-3 YAML format. This example checks a send_email call and blocks it before execution when its arguments contain a secret or other sensitive credential.
version: 3
scopes: [pending]
rules:
- id: prevent-secret-email
action: block
events:
call: {kind: tool_call_proposal, domain: pending}
where:
all:
- tool: {binding: call, name: send_email}
- detector:
id: secret_scan
capability: secrets
inputs:
- value: {field: [call, payload, arguments]}
encoding: canonical_json
finding:
code: secret_exfiltration
message: The proposed tool call contains secret material.
subjects: [call]
evidence: [{source: detector, id: secret_scan}]
The loader checks the format, references, resource limits, and available detection capabilities before activating a policy. See the Policy authoring guide for the complete syntax.
The default local profile provides the following local checks without model downloads or external services. The names in the table are used in policy files:
| What it checks | Purpose | Policy name |
|---|---|---|
| Secrets and credentials | Finds private keys, cloud credentials, and API tokens | secrets |
| Personal information | Finds fixed types such as email, phone, identity, and financial numbers | pii |
| Prompt injection signals | Finds high-signal instruction overrides, prompt disclosure, and role changes | prompt_injection |
| Invisible or confusing text | Finds Unicode controls, zero-width characters, and limited mixed-script tricks | unicode_security |
| Python code structure | Reports imports, risky calls, and syntax facts | python_ast_ipython |
| Hidden web content | Finds hidden HTML, comments, and bounded encoded content | hidden_content |
| Numeric or length ranges | Checks numbers, text, arrays, and objects against bounds | number_in_range, length_in_range |
| URL host allowlists | Checks whether an HTTP(S) URL uses an allowed host | url_host_allowed |
| Approximate text matching | Finds text within a bounded edit distance | fuzzy_contains |
Other detection capabilities, integration methods, and status are maintained in the capability matrix; detailed setup is in the capability reference and operations guide.
Detection results are signals. Rules should also use the data source, destination, authorization, and relationships among the message, model call, and tool call involved in the protected operation.
Guardrail checks events submitted through its SDK and requests handled by its Gateway. With the SDK, application code reads the returned decision before performing the operation; the Gateway enforces that ordering for model and MCP requests. Agent code that can run shell commands, arbitrary code, direct network calls, or host operations still requires a separate sandbox with default-deny egress, minimal temporary storage, and resource limits. Keep provider or tool credentials and audit storage outside that sandbox. The security model and operations guide define the responsibility split.
Deployment details and responsibility boundaries are described in the operations guide and security model. Future work is listed in the roadmap; the current architecture contract defines current behavior.
| Read | For |
|---|---|
| Documentation map | The shortest path for each task |
| Architecture overview | The end-to-end Event, Policy, Runtime, and Enforcement flow |
| Policy authoring | Writing version-3 YAML |
| Integration guide | Connecting application code, model clients, and MCP |
| Capability reference | Detector and Predicate contracts |
| Gateway protocol | HTTP, streaming, and MCP wire behavior |
| Responses state-layer design | previous_response_id state interface and external state-owner boundary |
| Operations guide | Profiles, environment variables, Docker, audit, and health |
| Security model | Assets, trust boundaries, and T01–T10 |
| Separate analysis service design | Deploying policy analysis separately |
| Long-session capacity evaluation | Regressing full, incremental shadow/active, and Remote Core v4 paths |
uv sync --frozen --extra gateway --dev
uv run pytest --cov=agent_guardrail --cov-report=term-missing
uv run ruff check .
uv run pyright
uv build
git diff --check
See CONTRIBUTING.md for the development workflow.
Agent Guardrail is available under the MIT License. Optional detector assets and dependencies retain their upstream licenses; consult the operations guide before deploying a model profile.