Claude Agent SDK

Warnings

• breaking The `claude-agent-sdk` requires Python 3.10 or newer. Installing or running with older Python versions (e.g., 3.9) will result in compatibility errors.
  Fix: Upgrade your Python environment to 3.10 or later.
• gotcha Large tool results (e.g., >50K characters) might be silently truncated in versions prior to 0.1.55 due to a bug in how `ToolAnnotations` were processed, potentially leading to incomplete data being processed by the agent.
  Fix: Upgrade to `claude-agent-sdk` version 0.1.55 or newer to ensure large tool results are handled correctly.
• gotcha When using `client.query()` with a string prompt and many tool calls (especially with hooks/MCP servers), versions prior to 0.1.53 could encounter a deadlock, causing the application to hang.
  Fix: Upgrade to `claude-agent-sdk` version 0.1.53 or newer to resolve the deadlock issue.
• gotcha Fine-grained tool streaming (`include_partial_messages=True`) was not reliably delivering `input_json_delta` events for versions 0.1.36 through 0.1.47 without a specific server-side feature flag being enabled, leading to a degraded streaming experience.
  Fix: Upgrade to `claude-agent-sdk` version 0.1.48 or newer to ensure correct fine-grained tool streaming behavior.
• gotcha Authentication requires either the `ANTHROPIC_API_KEY` or `CLAUDE_CODE_TOKEN` environment variable to be set, or passed explicitly as `api_key` to `ClaudeSDKClient`. Forgetting this will lead to authentication failures.
  Fix: Ensure `ANTHROPIC_API_KEY` or `CLAUDE_CODE_TOKEN` is set in your environment or passed as a parameter during client initialization.

Install

• pip install claude-agent-sdk Install latest version

Imports

• ClaudeSDKClient

  from claude_agent_sdk import ClaudeSDKClient

  Main client for interacting with Claude agents.
• tool

  from claude_agent_sdk import tool

  Decorator for defining callable tools that agents can use.
• create_sdk_mcp_server

  from claude_agent_sdk import create_sdk_mcp_server

  Function to create and run a Multi-Context Protocol (MCP) server for tools.

Quickstart

This quickstart demonstrates how to initialize the `ClaudeSDKClient`, define a simple tool using the `@tool` decorator, and send a query to Claude. It highlights the use of an API key for authentication and how to capture tool calls and agent responses.

import os
from claude_agent_sdk import ClaudeSDKClient, tool

# Set your API key as an environment variable or replace 'YOUR_ANTHROPIC_API_KEY'
# CLAUDE_CODE_TOKEN is also supported for authentication.
ANTHROPIC_API_KEY = os.environ.get('ANTHROPIC_API_KEY', 'YOUR_ANTHROPIC_API_KEY')

@tool
def get_current_weather(location: str) -> str:
    """Gets the current weather for a given location."""
    if location == "San Francisco":
        return "Sunny, 70F"
    return "Cloudy, 50F"

async def main():
    if ANTHROPIC_API_KEY == 'YOUR_ANTHROPIC_API_KEY':
        print("Please set the ANTHROPIC_API_KEY environment variable or replace the placeholder.")
        return

    client = ClaudeSDKClient(api_key=ANTHROPIC_API_KEY)
    try:
        response = await client.query(
            "What's the weather like in San Francisco?",
            tools=[get_current_weather]
        )
        print(f"Agent response: {response.response}")
        if response.tool_calls:
            for call in response.tool_calls:
                print(f"Tool call: {call.tool_name}({call.input_json})")
        if response.messages:
            for message in response.messages:
                if hasattr(message, 'text'):
                    print(f"Message: {message.text}")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    import asyncio
    asyncio.run(main())