К основному содержанию
скилл CX Codex

integrate-arcjet-guard-claude-agent-sdk-py — скилл для Claude Code

Скилл integrate-arcjet-guard-claude-agent-sdk-py для Claude Code подключает Arcjet Guard к Python Claude Agent SDK и проверяет запросы и вызовы инструментов, чтобы ограничивать их или блокировать prompt injection и PII.

Apache-2.0 120 установок ★ 5 обновлён 2026-10-07

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add arcjet/skills --skill integrate-arcjet-guard-claude-agent-sdk-py -a claude-code
Открыть на GitHub

Что делает integrate-arcjet-guard-claude-agent-sdk-py

Скилл помогает встроить Arcjet Guard в проект на Python с Claude Agent SDK. Для собственных инструментов @tool он использует guard_tool, а для входящего текста и не обёрнутых инструментов, включая встроенные и MCP, настраивает guard_hooks на события UserPromptSubmit и PreToolUse.

Для фильтрации результатов предусмотрены result_rules и проверки на PostToolUse; фильтрация результатов требует PyPI arcjet версии 1.5.0. Для основной интеграции нужны Python >= 3.10, официальный claude-agent-sdk>=0.2.127,<1 и PyPI arcjet 1.1.0 через arcjet[claude-agent-sdk]. Это интеграция с Python SDK, не с JS-адаптером и не с размещёнными сессиями Claude Managed Agents.

Какие задачи решает

  • подключить Arcjet Guard к Python Claude Agent SDK
  • ограничить частоту вызовов собственных инструментов
  • проверять входящие запросы на prompt injection и PII
  • блокировать вызовы встроенных и MCP-инструментов
  • проверять результаты инструментов до их передачи модели

Примеры запросов агенту

  • Подключи Arcjet Guard к моему проекту на Python с Claude Agent SDK.
  • Добавь ограничение частоты для инструмента @tool через Arcjet.
  • Настрой проверку входящих запросов и результатов инструментов на prompt injection.

Как установить integrate-arcjet-guard-claude-agent-sdk-py

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/integrate-arcjet-guard-claude-agent-sdk-py/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об integrate-arcjet-guard-claude-agent-sdk-py

Как установить integrate-arcjet-guard-claude-agent-sdk-py в Claude Code?

Выполни npx skills add arcjet/skills --skill integrate-arcjet-guard-claude-agent-sdk-py -a claude-code. Файл скилла находится по пути ~/.claude/skills/integrate-arcjet-guard-claude-agent-sdk-py/SKILL.md.

Что делает integrate-arcjet-guard-claude-agent-sdk-py?

Скилл настраивает Arcjet Guard для Python Claude Agent SDK: проверяет входящие запросы и вызовы инструментов, а также поддерживает проверку результатов.

Что нужно для работы integrate-arcjet-guard-claude-agent-sdk-py?

Нужны Python >= 3.10, официальный claude-agent-sdk>=0.2.127,<1 и PyPI arcjet 1.1.0, установленный через arcjet[claude-agent-sdk]. Для проверки результатов требуется PyPI arcjet 1.5.0.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
Arcjet arcjet MCP-сервер связывает ИИ-ассистент с Arcjet: он помогает разбирать запросы, анализировать трафик и настраивать удалённые правила безопасности. CX Codex +1 ★ 1звёзд репо agent-sdk-verifier-py официальный Anthropic Субагент agent-sdk-verifier-py для Claude Code, который проверяет Python-приложения на Agent SDK: правильность настройки, соответствие документации и готовность к запуску. Вызывается после создания или изменения приложения. CX Codex ★ 47 914звёзд репо migrating-claude-agent-sdk-to-pydantic-ai pydantic Скилл migrating-claude-agent-sdk-to-pydantic-ai для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI переводит Python-приложения с claude_agent_sdk на Pydantic AI. CX Codex +1 468установок claude-agent-sdk sammcj Помогает проектировать агентов на Anthropic Claude Agent SDK с хуками, субагентами и встроенными MCP-инструментами. CX Codex +1 ★ 173звёзд репо agent-sdk-dev официальный Anthropic Плагин agent-sdk-dev для Claude Code создаёт и проверяет приложения на Claude Agent SDK для Python и TypeScript. Проверяет проект перед деплоем. ★ 47 914звёзд репо prompt-guard UseAI-pro Скилл prompt-guard для Claude Code проверяет тексты скиллов, сообщения пользователя и внешние данные на попытки перехватить инструкции агента. Проверяет чужие скиллы и данные из веба. CX Codex +1 547установок

Из того же набора7

arcjet Подключает защиту Arcjet к HTTP-маршрутам и вызовам инструментов агента. Настраивает лимиты запросов и проверку на инъекции промпта. CX Codex +1 735установок integrate-arcjet-guard-openai-agents-py Скилл integrate-arcjet-guard-openai-agents-py для Claude Code помогает подключить Arcjet Guard к Python OpenAI Agents. Настраивает защиту авторских инструментов и проверку входящих сообщений. CX Codex +1 121установок integrate-arcjet-guard-crewai Скилл integrate-arcjet-guard-crewai для Claude Code добавляет Arcjet Guard в официальную CrewAI. Помогает ограничивать вызовы инструментов и проверять входящие сообщения перед запуском агента. CX Codex +1 120установок integrate-arcjet-guard-strands-agents-py Скилл integrate-arcjet-guard-strands-agents-py для Claude Code подключает Arcjet Guard к Python Strands Agents. Агент подбирает его для ограничения вызовов инструментов и проверки входящих сообщений. CX Codex +1 118установок integrate-arcjet-guard-claude-managed-agents-py Скилл integrate-arcjet-guard-claude-managed-agents-py для Claude Code подключает Arcjet Guard к размещённым Claude Managed Agents на Python. Он проверяет входные сообщения и ограничивает вызов пользовательских инструментов. CX Codex +1 118установок integrate-arcjet-guard-langchain-py Скилл integrate-arcjet-guard-langchain-py для Claude Code добавляет защиту Arcjet Guard в Python LangChain. Он подключает проверку инструментов и агента, а также запись событий цепочки. CX Codex +1 117установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой