Claude Agent SDK Integration

Integration with Claude Agent SDK for AI-powered background tasks.

Optional Dependency

Requires pip install fasthooks[claude]

ClaudeAgent

ClaudeAgent dataclass

Simplified wrapper for Claude Agent SDK.

Provides a simple interface for querying Claude in background tasks.

Usage

agent = ClaudeAgent(model="haiku", system_prompt="You are helpful.")

Simple query

response = await agent.query("What is 2+2?")

With tools

agent = ClaudeAgent(allowed_tools=["Read", "Grep"]) response = await agent.query("Find all TODO comments in src/")

Context manager usage

async with ClaudeAgent(model="sonnet") as agent: response = await agent.query("Explain this code")

model class-attribute instance-attribute

model: Model | str | None = None

system_prompt class-attribute instance-attribute

system_prompt: str | None = None

allowed_tools class-attribute instance-attribute

allowed_tools: list[str] = field(default_factory=list)

max_turns class-attribute instance-attribute

max_turns: int | None = None

max_budget_usd class-attribute instance-attribute

max_budget_usd: float | None = None

cwd class-attribute instance-attribute

cwd: str | None = None

query async

query(
    prompt: str,
    *,
    system_prompt: str | None = None,
    allowed_tools: list[str] | None = None,
    max_turns: int | None = None,
    max_budget_usd: float | None = None,
    cwd: str | None = None,
) -> str

Query Claude and return the text response.

Parameters:

Name	Type	Description	Default
prompt	str	The prompt to send to Claude	required
system_prompt	str | None	Override system prompt for this query	None
allowed_tools	list[str] | None	Override allowed tools for this query	None
max_turns	int | None	Override max turns for this query	None
max_budget_usd	float | None	Override budget limit for this query	None
cwd	str | None	Override working directory for this query	None

Returns:

Type	Description
str	The text response from Claude

Raises:

Type	Description
ImportError	If claude-agent-sdk is not installed
Exception	If the query fails

__aenter__ async

__aenter__() -> ClaudeAgent

Enter async context.

__aexit__ async

__aexit__(exc_type: Any, exc_val: Any, exc_tb: Any) -> None

Exit async context.

agent_task Decorator

agent_task

agent_task(
    model: Model | str = "haiku",
    system_prompt: str | None = None,
    allowed_tools: list[str] | None = None,
    max_turns: int | None = None,
    max_budget_usd: float | None = None,
    *,
    ttl: int = 300,
    priority: int = 0,
) -> Callable[[Callable[..., Any]], Task]

Decorator to create a background task that uses Claude Agent.

The decorated function receives a ClaudeAgent instance as its first argument, pre-configured with the specified options.

Usage

@agent_task(model="haiku", system_prompt="You are a code reviewer.") async def review_code(agent: ClaudeAgent, code: str) -> str: return await agent.query(f"Review this code:\n{code}")

Then use in a handler:

@app.pre_tool("Write") def on_write(event, tasks: BackgroundTasks): tasks.add(review_code, event.content, key="review")

Parameters:

Name	Type	Description	Default
model	Model | str	Claude model to use (haiku, sonnet, opus)	'haiku'
system_prompt	str | None	System prompt for the agent	None
allowed_tools	list[str] | None	Tools the agent can use	None
max_turns	int | None	Maximum conversation turns	None
max_budget_usd	float | None	Budget limit for the query	None
ttl	int	Time-to-live for task result (seconds)	300
priority	int	Task priority (higher = more important)	0

Returns:

Type	Description
Callable[[Callable[..., Any]], Task]	Task decorator

Type Aliases

# Model type hint
Model = Literal["sonnet", "opus", "haiku"]