Claude Agent SDK

Integrate AgentGuard directly into the Claude Agent SDK at the tool-call layer — no Virtue Gateway required.

Before you start

Review the AgentGuard SDK reference for client setup, result fields, and error handling.

Installation

pip install agentsuite-sdk[claude]

Quickstart

1. Guard client

from agentsuite import AsyncActionGuardClient, GuardError

guard = AsyncActionGuardClient(api_key=..., policy_id=...)

2. PreToolUse hook

async def action_guard_hook(hook_input, tool_use_id, context):
    tool_name = hook_input.get("tool_name", "unknown")
    tool_args = hook_input.get("tool_input", {})
    try:
        result = await guard.actions.guard_query(
            query=f"Tool: {tool_name}, Args: {tool_args}",
        )
        decision = "allow" if result.allowed else "deny"
        response = {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": decision,
            }
        }
        if not result.allowed:
            response["hookSpecificOutput"]["reason"] = result.explanation
        return response
    except GuardError as e:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "reason": f"Action Guard unavailable: {e.message}",
            }
        }

3. Agent options

HookMatcher(matcher="^mcp__") scopes the hook to MCP tools only.

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

def build_options() -> ClaudeAgentOptions:
    mcp_headers = {"X-API-Key": MCP_API_KEY} if MCP_API_KEY else {}
    return ClaudeAgentOptions(
        model="...",
        mcp_servers={"action-guard-demo": {
            "type": "http",
            "url": MCP_SERVER_URL,
            "headers": mcp_headers,
        }},
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="^mcp__", hooks=[action_guard_hook])
            ]
        },
    )

4. Run

from claude_agent_sdk import ClaudeSDKClient

options = build_options()

async with ClaudeSDKClient(options=options) as sdk:
    ...

Full runnable example: demo_action_guard_claude.py

Demo Run

Start the local MCP server (python local_mcp_server.py from the repo root), set env vars, then run:

python examples/demo_action_guard_claude.py

Environment Variables

Variable	Description
VIRTUE_API_KEY	VirtueAI API key
ACTION_GUARD_POLICY_ID	Policy set ID (agp_...)
ANTHROPIC_API_KEY	Anthropic API key
MCP_SERVER_URL	MCP server URL (default in demos: http://localhost:3002/mcp)
MCP_API_KEY	Optional API key for the MCP server
CLAUDE_MODEL	Optional model name (default in demo: claude-sonnet-4-5)