revsec-sdk
Check each tool call your Python agent makes against your organization's
RevSec policies before the tool runs, and record what happened. A blocked
call raises RevsecBlocked and the tool body never executes.
Works with any Python function: a tool in your own agent loop, a tool you register with an agent framework, or a handler in your own MCP server. It can also check every call your agent makes to an MCP server, and register the agent itself, so it is listed under Agents and its calls follow its approval (see Register your agent).
Quick start: a blocked tool call in 15 minutes
You need:
- Python 3.9 or newer.
- Your RevSec SDK key, from Settings → SDK in the RevSec console (see Which key).
- Access to the RevSec console for that organization, with a role that can create policies.
1. Install (1 minute)
pip install revsec-sdk
2. Point the SDK at RevSec (1 minute)
export REVSEC_API_KEY="<your SDK key>"
export REVSEC_BASE_URL="https://<your RevSec address>/fcc"
REVSEC_BASE_URL is your RevSec console's address followed by /fcc, with
nothing after it. Settings → SDK in the console shows both values. The SDK
has no built-in address: configure() uses base_url if you pass it, else
REVSEC_BASE_URL, and raises ValueError if neither is set.
3. Guard two tools (3 minutes)
Save this as quickstart.py:
import os
import uuid
from revsec import agent, mcp, tools
from revsec.mcp import RevsecBlocked
mcp.configure(
api_key=os.environ["REVSEC_API_KEY"],
base_url=os.environ["REVSEC_BASE_URL"],
)
mcp.set_session(str(uuid.uuid4())) # groups this run's calls in RevSec
me = agent.register(name="quickstart-agent", framework="custom",
tools=["lookup_order", "refund_order"])
@tools.guard(agent_id=me.agent_id)
def lookup_order(order_id: str) -> dict:
return {"order_id": order_id, "status": "delivered"}
@tools.guard(agent_id=me.agent_id)
def refund_order(order_id: str, amount: float) -> dict:
return {"order_id": order_id, "refunded": amount}
for name, call in [
("lookup_order", lambda: lookup_order("A-1001")),
("refund_order", lambda: refund_order("A-1001", 25.0)),
]:
try:
print(f"{name:13} allowed {call()}")
except RevsecBlocked as blocked:
print(f"{name:13} BLOCKED by '{blocked.decision.policy_name}'; the tool did not run")
agent.register lists the agent in RevSec. tools.guard checks each call as
one of the agent's own tools; the tool's name is the function's name, and it
is what policies match on.
4. Run it: both calls are allowed and recorded (1 minute)
python quickstart.py
lookup_order allowed {'order_id': 'A-1001', 'status': 'delivered'}
refund_order allowed {'order_id': 'A-1001', 'refunded': 25.0}
In the RevSec console, open Agents: quickstart-agent is listed as
Shadow (nobody has approved it yet). Activity Explorer shows both
calls under Agents.
5. Block the refund tool (5 minutes)
In the RevSec console:
- Approve the agent: open Approvals and approve
quickstart-agent. - Open Agents → Policies and click Create Policy.
- Name:
Block refunds (quick start). Enforcement: Block. - Under conditions, choose Tool the agent calls, equals, and type
refund_order. - Click Create Policy.
- At the top of the Agents page, set the posture to Enforce. Under Monitor, RevSec records what a policy would stop and lets the call run.
6. Run it again: the refund is blocked (1 minute)
python quickstart.py
lookup_order allowed {'order_id': 'A-1001', 'status': 'delivered'}
refund_order BLOCKED by 'Block refunds (quick start)'; the tool did not run
The blocked call is listed under Agents → Violations and in Activity Explorer. To undo, switch the policy off on Agents → Policies.
If refund_order is still allowed
- The SDK printed
RevSec refused the API key. The key is wrong for this address, so nothing is being checked and every call is allowed. See Which key. - The Agents posture is Monitor. Monitor records what the policy would stop but lets the call through. Set it to Enforce (step 5).
REVSEC_BASE_URLis wrong. It must end in/fcc, without/api/v1. When RevSec can't be reached, the SDK allows the call (see When RevSec can't be reached).
If both calls are blocked
- By
Agent posture · agent not approved. The Agents posture is Enforce and nobody has approvedquickstart-agentyet. Approve it in Approvals and run it again.
Register your agent
Register the agent once when it starts. RevSec lists it under Agents, in
the same registry as every agent it finds, with what you declare: the models
it uses, its tools and the data it can reach. Then pass its agent_id to
every check, so its tool calls are tied to it and follow its approval.
import os
from revsec import agent, mcp, tools
mcp.configure(api_key=os.environ["REVSEC_API_KEY"], base_url=os.environ["REVSEC_BASE_URL"])
me = agent.register(
name="orders-agent",
framework="langgraph",
agent_type="tool_using_agent",
autonomy="human_on_the_loop",
models=["claude-sonnet-5-5"],
tools=["lookup_order", "refund_order"],
data_access=["orders"],
owner_email="owner@yourcompany.com",
)
print(me.agent_id, me.status) # e.g. "6f1c1f9e-…", "shadow"
@tools.guard(agent_id=me.agent_id)
def lookup_order(order_id: str) -> dict:
...
- A new agent starts as Shadow, and an approval request is raised for it
on the Agents page. Until someone approves it, its tool calls and
content scans follow Agents → Enforcement posture: under Enforce
they are blocked (
Agent posture · agent not approved); under Monitor they run and are recorded. A quarantined or decommissioned agent is blocked under every posture. - Each call to the agent's own tools (
tools.guard) is checked against the agent's approval and its tool-call policies (Agents → Policies, "Tool the agent calls"). A call to an MCP server's tool (mcp_client) is checked against those and your MCP policies too. A stop from any of them blocks the call. A tool-call policy set to quarantine also quarantines the agent. - Registering again with the same
nameandframeworkupdates the same agent and returns its current status: its tools, models, data access and environment, and its type, autonomy and description when you pass them. The owner is set only if the agent has none (an owner set on the Agents page is kept). When what the agent policies look at changes, they are checked again. A differentframeworkmakes a second agent. agent_typeis one ofsingle_agent(a new agent's default),sub_agent,multi_agent_orchestrator,tool_using_agent,coding_assistant,productivity_assistant.autonomyis one ofhuman_in_the_loop(a new agent's default),human_on_the_loop,supervised,semi_autonomous,fully_autonomous,advisory_only. Agent policies match on these, so any other value is refused for a new agent, and kept as it was (with a warning) for a known one.- Its setup rating. What you declare (its tools,
data_access,autonomy,models, andcustomer_facing=Truefor an agent customers or the public use) feeds the agent's "Risk from setup" in RevSec, together with what RevSec sees it do. A declaration can raise that rating, never lower it:autonomy="human_in_the_loop"or a read-only tool doesn't make it look safer until RevSec sees it hold.customer_facing=Falseclears the flag. owner_emailmust be a person in your RevSec organization. Otherwise the agent is registered with no owner, andme.warningssays so (it is logged too).agent_idmust be the idregister()returned. Anything else (the agent's name, a typo) is treated as an agent RevSec has no record of: blocked under Enforce (Agent posture · agent not registered), and the SDK logs a warning.register()raisesRegistrationFailedwhen RevSec refuses the key or the values, or can't be reached, so a mistake shows up at start-up rather than as unchecked tool calls.await agent.aregister(...)is the async form.
Which key
Use an SDK key (it starts with rssdk_). An Org Admin or CISO issues it
in the RevSec console, under Settings → SDK; it is shown once. Give each agent
or environment its own, and revoke one there at any time.
The SDK sends the key in the X-API-Key header (and, to register an agent,
as Authorization: Bearer). An organization API key also works. A key made
for the RevSec browser extension, or a workspace key starting with rsk_, is
refused: every call is then allowed and the SDK logs
RevSec refused the API key.
If you build AI for your own customers, use the key of the customer account
the agent serves (it starts with rscus_; the Sandbox key you get when you
sign up is one). Checks, scans and agent registration then happen in that
customer account.
Keep the key in a secret store or an environment variable, never in code.
To check a different organization in the same process, pass api_key= to
guard(), aguard(), evaluate() or scan_content(). The key decides the
organization.
What the SDK calls
All calls go to REVSEC_BASE_URL with your key:
| Request | When |
|---|---|
POST /api/v1/agent-security/sdk/register |
agent.register(), once at start-up. The key is sent as Authorization: Bearer. Timeout 10 s. |
POST /api/v1/mcp-governance/evaluate |
Before each guarded call. Timeout 1.5 s. |
PATCH /api/v1/mcp-governance/events/{id}/outcome |
After the tool returns, fails or is blocked. Timeout 1 s. |
POST /api/v1/ai-data-flows/ingest |
Only when the content scan is on (dlp=True) or you call scan_content(). |
POST /api/v1/agent-security/sdk/check-content |
After each guarded own-tool or MCP call (its result), and when you call checks.check_prompt() or checks.check_tool_result(). Bearer key. Timeout 5 s. |
Async tools
Use @mcp.aguard for async def tools:
@mcp.aguard(server="internal-rag", tool="search_docs")
async def search_docs(query: str) -> dict:
return {"results": [...]}
Positional and keyword arguments both reach RevSec by parameter name, so policies on arguments work however the tool is called. The wrapper keeps the tool's name, signature and docstring, which agent frameworks read to describe the tool to the model.
Your agent's own tools
Your agent's own tools (functions in your code) are not MCP servers. Check
them with revsec.tools: each call is decided by the agent's status (a
quarantined agent is stopped; under Enforce, one nobody has approved yet is
held) and the agent's tool-call policies. It is recorded with the agent's tool
calls, and nothing is listed under MCP for it.
from revsec import agent, tools
me = agent.register(name="orders-agent", framework="custom", tools=["refund_order"])
@tools.guard(agent_id=me.agent_id)
def refund_order(order_id: str, amount: float) -> dict:
return {"order_id": order_id, "refunded": amount}
A blocked call raises RevsecBlocked before the function runs. With
mcp.configure(..., dlp=True), what the call sends out (its arguments) is also
scanned for secrets and personal data by your data protection policies, and a
call they block doesn't run. What the function hands back is checked before
your agent passes it to the model (see
Check prompts and tool results). Calls RevSec stops, holds or flags reach your SIEM
as agent_tool_call events. Use tools.aguard for an async function, or await tools.evaluate(tool=..., args=..., agent_id=...) to check without a decorator. The tool's name is the
function's name unless you pass one: @tools.guard("payments.refund").
MCP servers your agent connects to
Wrap the MCP client your agent already uses, and every tool call it makes to that server is checked first. The server is reported the way RevSec recognises it, read from the connection: its address, the package it runs, and the name it gives itself. So it joins the server already on record (from a laptop, the gateway or another agent) instead of being listed twice. Only the package name is read from a launch command, never its arguments.
pip install "revsec-sdk[mcp]"
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
from revsec import mcp_client
params = StdioServerParameters(command="npx", args=["-y", "@modelcontextprotocol/server-github"])
async with stdio_client(params) as (read, write):
async with mcp_client.guard(ClientSession(read, write), launch=params, agent_id=me.agent_id) as session:
await session.initialize()
await session.call_tool("create_issue", {"title": "Flaky test"}) # checked first
For a remote server pass url="https://…" instead of launch. agent_id is
the id agent.register() returned: it links the server to your agent. A
blocked call raises RevsecBlocked and never reaches the server; pass
on_block="result" to get an error result that tells the model why instead.
The server's reply is checked before your agent passes it to the model; a
reply RevSec stops raises RevsecBlocked, or with on_block="result" comes
back as an error result saying it was withheld.
Check prompts and tool results
RevSec checks what your agent sends its model, and what its tools hand back, with the same Model Security check the RevSec endpoint agent runs for coding tools on a laptop: your organization's prompt rules and the built-in checks (instructions aimed at the model, secrets, personal data). No AI gateway is needed.
from revsec import checks
verdict = checks.check_prompt_sync(prompt, agent_id=me.agent_id, model="gpt-4.1")
if not verdict.allowed:
raise mcp.RevsecBlocked(verdict.as_decision()) # don't send it
page = fetch_page(url)
verdict = checks.check_tool_result_sync(page, tool="fetch_page", agent_id=me.agent_id)
if not verdict.allowed:
page = verdict.withheld_text() # the model never reads it
tools.guard, tools.aguard and mcp_client.guard check each tool's result
for you, and langchain-revsec also checks the prompt before each model call.
verdict.decision is allow, alert (allowed, and a finding was kept) or
block. Each check is kept on the agent in RevSec: Model Security, Activity
(in the same session as its tool calls) and its risk. The model you name is
recorded as one of the agent's models. Use await checks.check_prompt(...)
and await checks.check_tool_result(...) from async code.
Both are on by default. If your model calls go through the RevSec AI gateway, which checks prompts there, turn the prompt check off; to stop checking tool results, turn that off:
mcp.configure(api_key=os.environ["REVSEC_API_KEY"], check_prompts=False)
mcp.configure(api_key=os.environ["REVSEC_API_KEY"], check_tool_results=False)
When RevSec can't be reached the check allows, unless
failure_mode="fail_closed".
When RevSec can't be reached
By default a call is allowed when RevSec can't be reached (fail open), so an outage never stops your agent. Change it for every call:
mcp.configure(api_key=os.environ["REVSEC_API_KEY"], failure_mode="fail_closed")
Without a setting, the SDK blocks only tools whose names start with a
destructive verb (delete_, drop_, truncate_, exec_, rm_, destroy_,
kill_) on servers outside a short list of well-known services, and allows
everything else.
Scan what a tool sends out
Policies decide whether a tool may run. Set dlp=True to also scan the
tool's input (the message, ticket or document it is about to send) for
secrets and personal data, with the same data policies as the rest of RevSec.
It is off by default: it adds one request per call and can newly block a
write.
mcp.configure(api_key=os.environ["REVSEC_API_KEY"], dlp=True)
@mcp.aguard(server="slack", tool="post_message")
async def post_message(*, channel_id: str, text: str) -> dict:
...
# If `text` carries a secret a policy blocks, RevsecBlocked is raised
# before post_message runs: the payload never leaves your process.
A redact verdict on a write is treated as a block: RevSec returns the redacted text as one string, which can't be put back into the tool's structured arguments, so the write is withheld rather than sent with the secret in it. If the scan can't reach RevSec, the call goes ahead.
Scan any text yourself, for example a tool's response:
verdict = await mcp.scan_content(
content=response_text, direction="inbound",
server="slack", tool="get_channel_history",
)
if verdict.blocked:
...
Group a run into turns
set_session() groups one run's calls. Inside a run, set_turn() opens a
turn: one thing the agent set out to do. Each guarded call is a step in
the current turn.
mcp.set_session(str(uuid.uuid4()))
mcp.set_turn("Reconcile the overnight claims batch")
await fetch_ledger(...) # step 1
await match_payments(...) # step 2
mcp.set_turn("Post the reconciliation summary to Slack")
await post_message(...) # step 1 of turn 2
The session id must be a UUID; another value is not kept. Write the turn as a
short goal, not the prompt: it is stored as written, so keep secrets, customer
data and prompt text out of it. It travels with the first call of the turn, so
it costs no extra request. clear_turn() stops tagging steps.
Check without a decorator
decision = await mcp.evaluate(
server="internal-rag",
tool="delete_doc",
args={"doc_id": "..."},
)
if not decision.allowed:
raise PermissionError(decision.reason)
# After running the tool:
await mcp.record_outcome(
event_id=decision.event_id,
outcome="success",
response_latency_ms=42,
)
What RevSec records
For every guarded call: the server and tool, the decision and the policy (and
its version) that made it, the tool's arguments with long values shortened and
secret-named fields (password, token, secret, api_key, key,
authorization, auth, credential) masked, the outcome (success, error,
timeout or blocked), how long the tool took and the size of its result.
Turn the SDK off
mcp.configure(api_key=..., enabled=False) allows every call without
contacting RevSec.
License
Proprietary. RevUp AI LLC.
Metadata
Release files for revsec-sdk 0.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| revsec_sdk-0.5.1.tar.gz | 59.4 kB | Without provenance | Details for revsec_sdk-0.5.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| revsec_sdk-0.5.1-py3-none-any.whl | Python 3 | none | any | Details for revsec_sdk-0.5.1-py3-none-any.whl |
Total release size: 95.4 kB
Release files / revsec_sdk-0.5.1.tar.gz
| Download URL | revsec_sdk-0.5.1.tar.gz |
|---|---|
| Size | 59.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c0383af24d75210b18dfaf7d1a50e6928e97e2dcdb8d1a18665a9cae3ab88ac0
|
|
BLAKE2b-256 checksum How to use checksums |
9298bfb7f9690caa608f20105ed2439867ded9a2a0fc8ce9caa1c3bc0dbceaaa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
Release files / revsec_sdk-0.5.1-py3-none-any.whl
| Download URL | revsec_sdk-0.5.1-py3-none-any.whl |
|---|---|
| Size | 35.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
020d8be2f80cdee6f46e24bf3809ddd52663917ce3a4edaa1006eff218e3a6a8
|
|
BLAKE2b-256 checksum How to use checksums |
46506c959039034847649610ba58632e47b5bb0a3238cb5853d48ae287d68e51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
Security for revsec-sdk 0.5.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.