Metadata-Version: 2.4
Name: openai-agents-relayshield
Version: 0.1.0
Summary: OpenAI Agents SDK tools and a mandatory pre-execution gate for RelayShield's MCP registry risk and prompt-injection breach checks.
Project-URL: Homepage, https://relayshield.net
Project-URL: Documentation, https://api.relayshield.net/developers
Project-URL: Repository, https://github.com/nzdsf2-gif/openai-agents-relayshield
Author-email: RelayShield <relayshieldadmin@gmail.com>
License: MIT
Keywords: agents,agents-sdk,ai,breach,mcp,openai-agents,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: Topic :: Internet
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: openai-agents>=0.1.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# openai-agents-relayshield

OpenAI Agents SDK tools and a mandatory pre-execution gate for [RelayShield](https://relayshield.net)'s agentic-security endpoints — MCP server registry risk and AI-agent-sourced credential breach detection.

## Install

```bash
pip install openai-agents-relayshield
```

## Tools

```python
from agents import Agent, Runner
from openai_agents_relayshield import check_mcp_server_risk, check_prompt_injection_breach

agent = Agent(
    name="Assistant",
    tools=[check_mcp_server_risk, check_prompt_injection_breach],
)

result = await Runner.run(
    agent,
    "Is it safe to connect to the MCP server at https://mcp.example.com/sse? My RelayShield key is rs_live_...",
)
```

- **`check_mcp_server_risk`** — flags known-malicious IOC matches, typosquat domains, and newly-registered domains hosting an MCP server, before an agent connects to or installs it.
- **`check_prompt_injection_breach`** — checks whether an email appears in RelayShield's stolen-session corpus with a suspected-agentic-source marker (a session/token exposure that shows signs of having been captured via a compromised AI agent).

Both tools take `api_key` as a call argument rather than reading it from the environment implicitly — a shared agent process can act safely on behalf of multiple callers with different RelayShield keys.

Get a key at [api.relayshield.net/developers](https://api.relayshield.net/developers).

## Mandatory gate

Most "AI agent security" checks are optional — the agent *can* call them, but nothing stops it skipping the call and taking the risky action anyway. `relayshield_mcp_gate` is the other kind: a gate the framework enforces *before* a protected action (connecting to or installing an MCP server) can happen at all, built on the SDK's `@tool_input_guardrail` hook.

```python
from openai_agents_relayshield.guardrail import relayshield_mcp_gate

# Attach directly to your own connect/install tool(s) — the guardrail is
# scoped by which tools you assign it to, not by matching tool names inside it.
connect_mcp_server.tool_input_guardrails = [relayshield_mcp_gate]
```

Properties, all non-negotiable by design:

- A hook exception defaults to `defer` (blocked, with an explanatory message), never silently to `allow` — a gate failure must not become a pass.
- Bounded retry applies only to transient upstream failures (timeout/429/5xx) — auth failures, malformed responses, and payment-required states are terminal after one attempt.
- The gate logs the decision, reason codes, check version, target, and timestamp — never keys, payment proofs, or session material.
- The raw connect/install tool should never be bound to the model directly in a real deployment — only route access to it through the gate.

Same normalized policy as [langchain-relayshield](https://github.com/nzdsf2-gif/langchain-relayshield)'s `RelayShieldMCPGateMiddleware` and its original standalone reference implementation, [relayshield-langchain-gate](https://github.com/nzdsf2-gif/relayshield-langchain-gate) — ported rather than imported, so this package has no dependency on LangChain/LangGraph.

## License

MIT
