Crate claude_agents_sdk

Expand description

§Claude Agents SDK

A Rust SDK for building agents that interact with the Claude Code CLI.

This SDK provides two main entry points:

query: One-shot, unidirectional queries that return an async stream of messages
ClaudeClient: Full bidirectional client with control protocol support

§Quick Start

§Simple Query

use claude_agents_sdk::{query, ClaudeAgentOptions, Message};
use tokio_stream::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = ClaudeAgentOptions::new()
        .with_max_turns(3);

    let mut stream = query("What is 2 + 2?", Some(options)).await?;

    while let Some(message) = stream.next().await {
        match message? {
            Message::Assistant(msg) => print!("{}", msg.text()),
            Message::Result(result) => {
                println!("\nCost: ${:.4}", result.total_cost_usd.unwrap_or(0.0));
            }
            _ => {}
        }
    }

    Ok(())
}

§Bidirectional Client

use claude_agents_sdk::ClaudeClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = ClaudeClient::new(None);
    client.connect().await?;

    // First query
    client.query("What is the capital of France?").await?;
    let (response, _) = client.receive_response().await?;
    println!("Response: {}", response);

    // Follow-up query (maintains context)
    client.query("What's its population?").await?;
    let (response, _) = client.receive_response().await?;
    println!("Response: {}", response);

    client.disconnect().await?;
    Ok(())
}

§Tool Permission Callbacks

Control which tools Claude can use by providing a permission callback:

use claude_agents_sdk::{ClaudeClientBuilder, PermissionResult, PermissionMode};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = ClaudeClientBuilder::new()
        .permission_mode(PermissionMode::Default)
        .can_use_tool(|tool_name, input, _ctx| async move {
            println!("Tool requested: {} with {:?}", tool_name, input);

            // Allow Read, deny dangerous Bash commands
            if tool_name == "Bash" {
                if let Some(cmd) = input.get("command").and_then(|v| v.as_str()) {
                    if cmd.contains("rm -rf") {
                        return PermissionResult::deny_with_message("Dangerous command");
                    }
                }
            }

            PermissionResult::allow()
        })
        .build();

    client.connect().await?;
    // ... use client
    Ok(())
}

§Error Handling

The SDK provides ClaudeSDKError for comprehensive error handling:

use claude_agents_sdk::{query, ClaudeAgentOptions, ClaudeSDKError, PermissionMode};

#[tokio::main]
async fn main() {
    let options = ClaudeAgentOptions::new()
        .with_permission_mode(PermissionMode::Default)
        .with_timeout_secs(30);

    match query("Hello", Some(options)).await {
        Ok(stream) => {
            // Process stream...
        }
        Err(ClaudeSDKError::CLINotFound { message }) => {
            eprintln!("Claude CLI not installed: {}", message);
        }
        Err(ClaudeSDKError::Timeout { duration_ms }) => {
            eprintln!("Operation timed out after {}ms", duration_ms);
        }
        Err(e) => {
            eprintln!("Error: {}", e);
        }
    }
}

§Configuration Options

Configure queries with ClaudeAgentOptions:

use claude_agents_sdk::{ClaudeAgentOptions, PermissionMode};

let options = ClaudeAgentOptions::new()
    .with_model("claude-sonnet-4-20250514")
    .with_system_prompt("You are a helpful coding assistant.")
    .with_max_turns(10)
    .with_permission_mode(PermissionMode::AcceptEdits)
    .with_allowed_tools(vec!["Read".into(), "Write".into()])
    .with_timeout_secs(60);

§Feature Flags

default: Core SDK functionality
mcp: Enables MCP (Model Context Protocol) tool support for defining custom tools

Re-exports§

pub use mcp::create_sdk_mcp_server;mcp
pub use mcp::McpSdkServerConfig;mcp
pub use mcp::SdkMcpTool;mcp
pub use mcp::ToolAnnotations;mcp

Modules§

_internal: Internal implementation details for the Claude Agents SDK.
mcpmcp: MCP (Model Context Protocol) tool support.

Macros§

tool: Macro for defining tools with a simpler syntax.

Structs§

AgentDefinition: Agent definition.
AssistantMessage: Assistant message.
AsyncHookOutput: Async hook output that defers execution.
BaseHookInput: Base hook input fields.
ClaudeAgentOptions: Query options for Claude SDK.
ClaudeClient: Bidirectional client for streaming Claude interactions.
ClaudeClientBuilder: Builder for creating a ClaudeClient with configuration.
ClientGuard: A guard that automatically disconnects a ClaudeClient when dropped.
ControlErrorResponse: Error response.
ControlRequest: Control request.
ControlResponse: Control response.
ControlSuccessResponse: Success response.
HookContext: Context for hook callbacks.
HookMatcher: Hook matcher configuration.
McpHttpServerConfig: MCP HTTP server configuration.
McpSSEServerConfig: MCP SSE server configuration.
McpStdioServerConfig: MCP stdio server configuration.
NotificationHookInput: Input for Notification hook events.
NotificationHookSpecificOutput: Hook-specific output for Notification events.
PermissionRequestHookInput: Input for PermissionRequest hook events.
PermissionRequestHookSpecificOutput: Hook-specific output for PermissionRequest events.
PermissionResultAllow: Allow permission result.
PermissionResultDeny: Deny permission result.
PermissionRuleValue: Permission rule value.
PermissionUpdate: Permission update configuration.
PostToolUseFailureHookInput: Input for PostToolUseFailure hook events.
PostToolUseFailureHookSpecificOutput: Hook-specific output for PostToolUseFailure events.
PostToolUseHookInput: Input for PostToolUse hook events.
PostToolUseHookSpecificOutput: Hook-specific output for PostToolUse events.
PreCompactHookInput: Input for PreCompact hook events.
PreToolUseHookInput: Input for PreToolUse hook events.
PreToolUseHookSpecificOutput: Hook-specific output for PreToolUse events.
ResultMessage: Result message with cost and usage information.
SandboxIgnoreViolations: Violations to ignore in sandbox.
SandboxNetworkConfig: Network configuration for sandbox.
SandboxSettings: Sandbox settings configuration.
SdkPluginConfig: SDK plugin configuration.
StopHookInput: Input for Stop hook events.
StreamEvent: Stream event for partial message updates.
SubagentStartHookInput: Input for SubagentStart hook events.
SubagentStartHookSpecificOutput: Hook-specific output for SubagentStart events.
SubagentStopHookInput: Input for SubagentStop hook events.
SyncHookOutput: Synchronous hook output with control fields.
SystemMessage: System message.
SystemPromptPreset: System prompt preset.
TextBlock: Text content block.
ThinkingBlock: Thinking content block.
ToolPermissionContext: Context information for tool permission callbacks.
ToolResultBlock: Tool result content block.
ToolUseBlock: Tool use content block.
ToolsPreset: Tools preset.
UserMessage: User message.
UserPromptSubmitHookInput: Input for UserPromptSubmit hook events.
UserPromptSubmitHookSpecificOutput: Hook-specific output for UserPromptSubmit events.

Enums§

AgentModel: Agent model.
AssistantMessageError: Assistant message error types.
ClaudeSDKError: Main error type for the Claude Agents SDK.
CompactTrigger: Trigger for PreCompact hook.
ContentBlock: Content block union type.
ControlRequestPayload: Control request subtypes.
ControlResponsePayload: Control response payload.
Effort: Effort level for thinking depth.
HookEvent: Hook event types.
HookInput: Union of all hook input types.
HookOutput: Hook output type.
HookSpecificOutput: Union of hook-specific outputs.
McpServerConfig: MCP server configuration union.
McpServersConfig: MCP servers configuration.
Message: Message union type.
PermissionBehavior: Permission behavior for tool use.
PermissionMode: Permission modes controlling how the CLI handles tool permissions.
PermissionResult: Permission result from a tool permission callback.
PermissionUpdateDestination: Destination for permission updates.
PermissionUpdateType: Type of permission update.
SdkBeta: SDK Beta features.
SettingSource: Setting source.
SystemPromptConfig: System prompt configuration.
ThinkingConfig: Configuration for extended thinking behavior.
ToolsConfig: Tools configuration.
UserMessageContent: User message content can be a string or content blocks.

Constants§

MIN_CLI_VERSION: Minimum required Claude CLI version
VERSION: SDK version

Functions§

query: Execute a one-shot query to Claude.
query_all: Execute a query and collect all messages.
query_chunks: Execute a query with a prompt built from chunks.
query_result: Get the final result from a query.

Type Aliases§

CanUseTool: Type alias for the tool permission callback function.
CanUseToolFuture: The async future type returned by tool permission callbacks.
HookCallback: Type alias for hook callback functions.
HookCallbackFuture: The async future type returned by hook callbacks.
Result: Result type alias for SDK operations.

Crate claude_agents_sdk

Crate claude_agents_sdk Copy item path

§Claude Agents SDK

§Quick Start

§Simple Query

§Bidirectional Client

§Tool Permission Callbacks

§Error Handling

§Configuration Options

§Feature Flags

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate claude_agents_sdk