GitHub - sshh12/modal-claude-agent-sdk-python: This package wraps the Claude Agent SDK to execute AI agents in secure, scalable Modal containers. It provides progressive complexity—simple usage mirrors the original Agent SDK, while advanced features expose Modal's full capabilities (GPU, volumes, image customization, etc.).

pip install modal-agents-sdk

import asyncio
from modal_agents_sdk import query

async def main():
    async for message in query("What is 2 + 2?"):
        print(message)

asyncio.run(main())

from modal_agents_sdk import query, ModalAgentOptions, AssistantMessage, TextBlock
import modal

# Simple query
async for message in query(prompt="Hello Claude"):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)

# With options
options = ModalAgentOptions(
    system_prompt="You are a helpful assistant",
    max_turns=3,
    secrets=[modal.Secret.from_name("anthropic-key")],
)

async for message in query(prompt="Tell me a joke", options=options):
    print(message)

options = ModalAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits",  # auto-accept file edits
    secrets=[modal.Secret.from_name("anthropic-key")],
)

async for message in query(prompt="Create a hello.py file", options=options):
    pass

from pathlib import Path

options = ModalAgentOptions(
    cwd="/workspace/myproject",  # or Path("/workspace/myproject")
    secrets=[modal.Secret.from_name("anthropic-key")],
)

options = ModalAgentOptions(
    gpu="A10G",  # or "H100", "A100-80GB:2", etc.
    memory=16384,  # 16 GB
    secrets=[modal.Secret.from_name("anthropic-key")],
)

import modal

data_volume = modal.Volume.from_name("my-data", create_if_missing=True)

options = ModalAgentOptions(
    volumes={"/data": data_volume},
    secrets=[modal.Secret.from_name("anthropic-key")],
)

# Files written to /data persist across sandbox executions

from modal_agents_sdk import ModalAgentImage

image = (
    ModalAgentImage.default()
    .pip_install("pandas", "numpy", "scikit-learn")
    .apt_install("ffmpeg")
    .run_commands("npm install -g typescript")
)

options = ModalAgentOptions(
    image=image,
    secrets=[modal.Secret.from_name("anthropic-key")],
)

# Anthropic API CIDR (required): 160.79.104.0/23
# Source: https://docs.anthropic.com/en/api/ip-addresses

options = ModalAgentOptions(
    cidr_allowlist=["160.79.104.0/23"],  # Anthropic API only
    secrets=[modal.Secret.from_name("anthropic-key")],
)

from modal_agents_sdk import ModalAgentClient, ModalAgentOptions
import modal

options = ModalAgentOptions(
    secrets=[modal.Secret.from_name("anthropic-key")],
)

async with ModalAgentClient(options=options) as client:
    await client.query("Create a Python project structure")
    async for msg in client.receive_response():
        print(msg)

    # Follow-up (maintains context)
    await client.query("Now add a requirements.txt")
    async for msg in client.receive_response():
        print(msg)

options = ModalAgentOptions(
    mcp_servers={
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
        },
    },
    secrets=[modal.Secret.from_name("anthropic-key")],
)

from modal_agents_sdk import (
    ModalAgentHooks,
    PreToolUseHookInput,
    PreToolUseHookResult,
    ModalAgentOptions,
)

async def block_dangerous_commands(input: PreToolUseHookInput) -> PreToolUseHookResult:
    """Block dangerous bash commands before execution."""
    if input.tool_name == "Bash" and "rm -rf" in input.tool_input.get("command", ""):
        return PreToolUseHookResult(
            decision="deny",
            reason="Blocked dangerous command",
        )
    return PreToolUseHookResult(decision="allow")

hooks = ModalAgentHooks(
    pre_tool_use=[block_dangerous_commands],
    tool_filter="Bash|Write|Edit",  # Only intercept these tools
)

options = ModalAgentOptions(
    host_hooks=hooks,
    secrets=[modal.Secret.from_name("anthropic-key")],
)

from modal_agents_sdk import host_tool, HostToolServer, ModalAgentOptions
import os

@host_tool(
    name="get_secret",
    description="Retrieve a secret from local environment",
    input_schema={"key": str},
)
async def get_secret(args):
    """Access local environment variables not available in sandbox."""
    value = os.environ.get(args["key"], "")
    return {"content": [{"type": "text", "text": f"Secret value: {value}"}]}

server = HostToolServer(name="local-tools", tools=[get_secret])

options = ModalAgentOptions(
    host_tools=[server],
    secrets=[modal.Secret.from_name("anthropic-key")],
)

# Agent can now call get_secret to access your local environment
async for message in query("Get the DATABASE_URL secret", options=options):
    print(message)

# modal_compute_functions.py - Deploy separately with: modal deploy modal_compute_functions.py
import modal

app = modal.App("agent-compute-tools")

@app.function()
def compute_fibonacci(n: int) -> dict:
    def fib(x): return x if x <= 1 else fib(x-1) + fib(x-2)
    return {"fibonacci": fib(n), "n": n}

# main.py - Run after deploying the Modal function
import modal
from modal_agents_sdk import HostTool, HostToolServer, ModalAgentOptions, query

async def fibonacci_handler(args: dict) -> dict:
    func = modal.Function.from_name("agent-compute-tools", "compute_fibonacci")
    result = await func.remote.aio(n=args["n"])
    import json
    return {"content": [{"type": "text", "text": json.dumps(result)}]}

tool = HostTool(
    name="compute_fibonacci",
    description="Compute the nth Fibonacci number",
    input_schema={"type": "object", "properties": {"n": {"type": "integer"}}, "required": ["n"]},
    handler=fibonacci_handler,
)

server = HostToolServer(name="compute-tools", tools=[tool])
options = ModalAgentOptions(host_tools=[server], secrets=[modal.Secret.from_name("anthropic-key")])

async for message in query("Calculate fibonacci(20)", options=options):
    print(message)

from modal_agents_sdk import (
    ModalAgentError,        # Base error
    SandboxCreationError,   # Failed to create sandbox
    SandboxTimeoutError,    # Execution timed out
    SandboxTerminatedError, # Sandbox terminated
    ImageBuildError,        # Image build failed
    CLINotInstalledError,   # claude-agent-sdk not in image
    AgentExecutionError,    # Agent execution failed
)

try:
    async for message in query(prompt="Hello", options=options):
        pass
except SandboxTimeoutError:
    print("Execution timed out")
except AgentExecutionError as e:
    print(f"Agent failed: exit code {e.exit_code}")

git clone https://github.com/sshh12/modal-claude-agent-sdk-python
cd modal-claude-agent-sdk-python
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run checks manually
pytest          # Run tests
mypy src/       # Type checking
ruff check src/ # Linting
ruff format src/ tests/  # Format code