Skip to main content
skill CX Codex

integrate-arcjet-guard-claude-agent-sdk-py — Claude Code skill

The integrate-arcjet-guard-claude-agent-sdk-py Claude Code skill connects Arcjet Guard to the Python Claude Agent SDK. It screens prompts and tool activity to rate-limit calls or block prompt injection and PII.

Apache-2.0 120 installs ★ 5 updated 2026-10-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add arcjet/skills --skill integrate-arcjet-guard-claude-agent-sdk-py -a claude-code
Open on GitHub

What integrate-arcjet-guard-claude-agent-sdk-py does

The skill guides integration of Arcjet Guard with a Python Claude Agent SDK project. It wraps authored @tool functions with guard_tool, then uses guard_hooks for inbound UserPromptSubmit checks and PreToolUse checks on built-ins or MCP tools that lack that wrapper.

Result screening uses result_rules or PostToolUse checks and requires PyPI arcjet 1.5.0. The integration requires Python >= 3.10, the official claude-agent-sdk>=0.2.127,<1, and PyPI arcjet 1.1.0 via arcjet[claude-agent-sdk]. It targets the Python SDK, not the JS adapter or hosted Claude Managed Agents sessions.

What it helps with

  • connect Arcjet Guard to a Python Claude Agent SDK project
  • rate-limit calls to authored tools
  • screen incoming prompts for prompt injection and PII
  • deny calls to built-in and MCP tools
  • screen tool results before they reach the model

Example prompts for the agent

  • Connect Arcjet Guard to my Python Claude Agent SDK project.
  • Add an Arcjet rate limit to this @tool function.
  • Set up prompt injection screening for incoming prompts and tool results.

How to install integrate-arcjet-guard-claude-agent-sdk-py

1Skills CLI (Vercel)

npx skills add arcjet/skills --skill integrate-arcjet-guard-claude-agent-sdk-py -a claude-code

2Manually: put the files in place

~/.claude/skills/integrate-arcjet-guard-claude-agent-sdk-py/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/integrate-arcjet-guard-claude-agent-sdk-py/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about integrate-arcjet-guard-claude-agent-sdk-py

How do I install integrate-arcjet-guard-claude-agent-sdk-py in Claude Code?

Run npx skills add arcjet/skills --skill integrate-arcjet-guard-claude-agent-sdk-py -a claude-code. The skill file is at ~/.claude/skills/integrate-arcjet-guard-claude-agent-sdk-py/SKILL.md.

What does integrate-arcjet-guard-claude-agent-sdk-py do?

It helps add Arcjet Guard checks to a Python Claude Agent SDK project, covering inbound prompts, tool calls, and, with the required version, tool results.

What does integrate-arcjet-guard-claude-agent-sdk-py require?

It requires Python >= 3.10, the official claude-agent-sdk>=0.2.127,<1, and PyPI arcjet 1.1.0 installed through arcjet[claude-agent-sdk]. Result screening requires PyPI arcjet 1.5.0.

Source text

SKILL.md · Apache-2.0
---
name: integrate-arcjet-guard-claude-agent-sdk-py
description: Integrate Arcjet Guard into the Python Claude Agent SDK — wrap authored @tool with guard_tool, and use guard_hooks for UserPromptSubmit inbound plus PreToolUse on unwrapped built-ins / MCP. Use when asked to add Arcjet to claude-agent-sdk, rate limit those tools, screen inbound prompts, or block prompt injection / PII. This is Python claude-agent-sdk, not the JS adapter and not Claude Managed Agents hosted sessions.
license: Apache-2.0
compatibility: Requires Python >= 3.10 and official claude-agent-sdk>=0.2.127,<1 via arcjet[claude-agent-sdk] (safe extra, no chromadb). Requires PyPI arcjet 1.1.0; result screening (result_rules / tool_results) needs 1.5.0.
metadata:
  author: arcjet
  type: core
  library: arcjet
---

# Integrate Arcjet Guard into the Python Claude Agent SDK

`arcjet.guard.claude_agent_sdk` wraps the agent's existing Arcjet client.
It never talks to the Arcjet API itself. Shared Guard fundamentals
(client, rules, labels, decisions, capture, registration) live in
[../arcjet/references/guards_python.md](../arcjet/references/guards_python.md).
Load that reference for anything that is not Claude Agent SDK-specific.

Official `claude-agent-sdk>=0.2.127,<1` only — not the JS
`@anthropic-ai/claude-agent-sdk` adapter
(`@arcjet/guard/claude-agent-sdk/v0`, docs
https://docs.arcjet.com/guards/claude-agent-sdk/), not Vercel AI, not
community forks, and not Claude Managed Agents hosted
`client.beta.sessions` (`arcjet.guard.claude_managed_agents`). Importing
`arcjet.guard.claude_agent_sdk` does not load LangChain, CrewAI, or the
JS adapter. The extra is safe (no chromadb).

Exports: `guard_tool`, `guard_hooks`, `claude_agent_context`,
`REPLACEABLE_BUILTIN_TOOLS`, `can_replace_result`. Authored
`@tool` + `create_sdk_mcp_server` for tools you own; `guard_hooks` for
inbound `UserPromptSubmit` and unwrapped built-ins / MCP `PreToolUse`.
There is no inbound helper and no `guard_can_use_tool`.

Three surfaces, one decision rule:

- **An authored `@tool`** → `guard_tool`. Denial is JSON-in-content +
  `is_error: True`. Python does **not** forward `structuredContent`
  (that is the JS adapter). Do **not** raise.
- **Inbound text** → `guard_hooks` `UserPromptSubmit` (`decision:
  "block"`). That is the only place a turn can be declined before the
  model reads the prompt.
- **Built-ins / unwrapped MCP** → `guard_hooks` `PreToolUse`
  (`permissionDecision: "deny"`).
- **What a tool returned** (1.5.0+) → `guard_tool(result_rules=...)` for
  an authored tool, `guard_hooks(tool_results={"rules": ...})` on
  `PostToolUse` for every tool. Without them `PostToolUse` only captures.
- **Correlation** → `claude_agent_context` reads a caller-owned UUID
  `session_id`. It never mints.

Docs: https://docs.arcjet.com/guards/claude-agent-sdk/.

## Unwrapped tools deny on `PreToolUse` via `guard_hooks`

Built-ins (Bash, Write, …) and MCP tools you did not pass through
`guard_tool` have no authored handler. `PreToolUse` is the only deny for
those. `PostToolUse` cannot undo a tool that already ran. List every
`guard_tool` wrapper in `exclude` or each authored tool is guarded twice
(two round trips, two quota units). Entries match the reported name:
pass `{"server": "support", "name": "lookup_order"}` for an authored MCP
tool (it resolves to `mcp__support__lookup_order`) and a bare string for
a built-in such as `"Bash"`. A bare authored name deliberately does not
match every server's tool of that name.

## Screen tool results before the model reads them (1.5.0+)

```python
guarded_fetch = guard_tool(guard=aj, tool=fetch_page, action="page.fetched",
                           session_id=session_id,
                           result_rules=lambda r: [DetectPromptInjection()(r["text"])])
hooks = guard_hooks(guard=aj, session_id=session_id,
                    tool_results={"rules": lambda r: [DetectPromptInjection()(r["text"])]})
```

- `result_rules` gets `{"arguments", "result", "text"}` and runs a second
  Guard call labelled `result_action` (default `"{action}.result"`) –
  publish remote policy under that label. A DENY returns the same
  `is_error` envelope in place of the result.
- `tool_results["rules"]` is required and must be a callable of
  `{"tool_name", "tool_input", "tool_response", "text"}`; default action
  `"{tool_name}.result"`. No policy inputs are sent.
- On a `tool_results` DENY: MCP tools (`mcp__…`) and `Bash` / `Read` get
  the result replaced; **any other tool stops the run** (`continue:
  false`). Don't resume a stopped session – it still holds the original
  result. Keep tools `can_replace_result()` rejects out of
  `allowed_tools` where stopping is unacceptable.
- `exclude` does not skip `tool_results`, so a tool with `result_rules`
  is screened twice. Subagent (`Agent`) output is not screened. Another
  `PostToolUse` hook that rewrites the result can overwrite the denial.
- `text` is never shortened: over 128 KiB to prompt injection is a deny,
  and a slow scan under the default `on_guard_error="deny"` also denies.
  Choose `on_guard_error` per tool deliberately.

## Authored `@tool` denial is JSON-in-content + `is_error: True`

`guard_tool` wraps the `@tool` definition so the handler never runs on
`DENY` (or unevaluated Guard under the default `on_guard_error="deny"`).
The model receives the `ArcjetDenialResult` as JSON text on `content`
with `is_error: True`. Do **not** set `structuredContent` (JS only). Do
**not** raise: a throw is a raw exception; omitting `is_error` looks
like success. Same fail-closed default as
[#196](https://github.com/arcjet/arcjet-py/pull/196): only `"allow"`
fails open; a `DENY` always blocks. Core `guard()` still fails open.

## `can_use_tool` is not a policy gate

`can_use_tool` is human-in-the-loop. `allowed_tools`, allow rules, and
`bypassPermissions` / `acceptEdits` skip it. Same trap as CrewAI
`human_input`, JS `canUseTool`, LangGraph `interrupt()`, and OpenAI
Agents `needs_approval`. There is no inbound helper — screen prompt
injection on `guard_hooks` `UserPromptSubmit`.

## Questions to ask the human first

Ask only what you cannot infer from the code; suggest defaults.

1. Which tools are **risky** (external side effects, irreversible, spends
   money, sends messages)? Those get `guard_tool`. Built-ins and
   unwrapped MCP get `guard_hooks` `PreToolUse`.
2. What **limits**? (e.g. "10 lookups/min per user" → `TokenBucket`.)
3. Who is the **user** for metadata — an opaque user/tenant ID (never PII)?
   Default: none. Session id is the correlation id, not the user. The
   Claude SDK requires `session_id` to be a UUID and allows a given id
   to be created only once — later turns use `resume`.
4. Is an Arcjet outage unacceptable? Every helper defaults to
   `on_guard_error="deny"`. Ask explicitly about inbound
   `UserPromptSubmit`: failing closed there means the agent stops
   answering, so `"allow"` is a routine and legitimate choice at that
   one call site.

## The things readers get wrong

1. **This is not the JS adapter and not Claude Managed Agents.** Do not
   import `@arcjet/guard/claude-agent-sdk/v0` or
   `arcjet.guard.claude_managed_agents`.
2. **There is no inbound helper.** Screen on `UserPromptSubmit` via
   `guard_hooks`.
3. **`can_use_tool` is HITL, not policy.**
4. **Python does not forward `structuredContent`.** Authored deny is
   JSON-in-content + `is_error: True`.
5. **`session_id` is a UUID, and only once.** Later turns: `resume`.
   `claude_agent_context` never mints.
6. **List every `guard_tool` wrapper in `exclude`.** Missing exclude
   double-calls Guard.
7. **Key rate limits on the authenticated caller**, not a model-supplied
   order id. Hand `query` / `create_sdk_mcp_server` the copy
   `guard_tool` returns.
8. **Do not hand-wrap every tool with raw `guard()`.**
9. **Isolation needs both `setting_sources=[]` and
   `strict_mcp_config=True`.** One without the other still exposes an
   unguarded path.
10. **Two distinct ids.** `ClaudeAgentOptions.session_id` is a unique
    UUID per run (`resume` later). The Guard `session_id` is a
    long-lived actor id. A missing decision is not a denial.

## Step 1: Install and find the guard client

Requires PyPI `arcjet` **1.1.0** (the `arcjet[claude-agent-sdk]` extra is not in 1.0.0):

```bash
pip install "arcjet[claude-agent-sdk]"
```

If the agent has no guard client yet, launch one **once at module scope**:

```python
import os
from arcjet.guard import launch_arcjet

aj = launch_arcjet(key=os.environ["ARCJET_KEY"])
```

## Step 2: Gate authored tools — `guard_tool`

```python
from claude_agent_sdk import ClaudeAgentOptions, create_sdk_mcp_server, query, tool
from arcjet.guard import DetectPromptInjection, TokenBucket, launch_arcjet
from arcjet.guard.claude_agent_sdk import guard_hooks, guard_tool

aj = launch_arcjet(key=os.environ["ARCJET_KEY"])
lookup_limit = TokenBucket(
    label="order.looked-up",
    bucket="lookups",
    refill_rate=10,
    interval_seconds=60,
    max_tokens=10,
)
mcp_limit = TokenBucket(
    label="mcp.invoked",
    bucket="mcp-access",
    refill_rate=20,
    interval_seconds=60,
    max_tokens=20,
)
inbound = DetectPromptInjection()
user_id = authenticated_user_id
# Caller-owned UUID for this conversation. Later turns: resume=session_id.
session_id = conversation_id

@tool("lookup_order", "Look up an order by number", {"order_id": str})
async def lookup_order(args: dict) -> dict:
    return {
        "content": [{"type": "text", "text": f"{args['order_id']}: shipped"}],
    }

lookup_order = guard_tool(
    guard=aj,
    tool=lookup_order,
    action="order.looked-up",
    rules=[lookup_limit(key=user_id, requested=1)],
    on_guard_error="deny",
)
# can_use_tool=... is HITL — not this policy gate
```

## Step 3: Screen inbound and gate unwrapped tools — `guard_hooks`

```python
async for message in query(
    prompt=user_text,
    options=ClaudeAgentOptions(
        session_id=session_id,  # later turns: resume=session_id instead
        mcp_servers={
            "support": create_sdk_mcp_server(name="support", tools=[lookup_order]),
        },
        hooks=guard_hooks(
            guard=aj,
            session_id=session_id,
            exclude=[{"server": "support", "name": "lookup_order"}],
            inbound={
                "action": "message.received",
                "rules": lambda ctx: [inbound(ctx["prompt"])],
            },
            action="mcp.invoked",
            rules=lambda ctx: [mcp_limit(key=user_id, requested=1)],
            on_guard_error="deny",
        ),
    ),
):
    pass
```

## Step 4: Correlation

`claude_agent_context(session_id=session_id)` reads that same
caller-owned UUID (hook `session_id` first, then `options.session_id`).
It never mints. Pass the id you already have into `guard_hooks` and
`ClaudeAgentOptions` — do not derive a new one per turn. The Claude SDK
also requires `session_id` to be a UUID and allows a given id to be
created only once — later turns use `resume`.

## Verify the integration

1. `python -m py_compile` (or the project's type-check) passes.
2. Exercise inbound PI (`UserPromptSubmit` block), an authored-tool deny
   (JSON-in-content + `is_error: True`, no `structuredContent`), a
   built-in / unwrapped MCP deny (`PreToolUse`), a rate limit, and
   fail-closed (an unreachable guard). Confirm a wrapped tool produces
   **one** guard decision per invocation — a second decision under the
   `PreToolUse` action means a missing `exclude` entry.
3. Confirm in the Arcjet Console / CLI that decisions share the
   caller-owned UUID `session_id`.
4. Manual E2E with a real `ARCJET_KEY` is still-to-verify until you run it.

The example `fastapi-claude-agent-sdk-guard` stays with Runtime — do not
invent a new example name. Do not add an example in this skills repo.

© arcjet · Apache-2.0 · arcjet/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set7

Project sponsors

Companies that keep this analytics open