{"id":1417,"library":"claude-agent-sdk","title":"Claude Agent SDK","description":"The Claude Agent SDK provides a Python interface for interacting with Claude's agent capabilities, allowing developers to define tools, manage sessions, and build conversational agents. It bundles the Claude CLI and runs it as a subprocess. The current version is 0.1.56, and releases are frequent, often weekly, bundling updates to the underlying Claude CLI.","status":"active","version":"0.1.56","language":"en","source_language":"en","source_url":"https://github.com/anthropics/claude-agent-sdk-python","tags":["AI","LLM","agent","Anthropic","Claude","tool-use"],"install":[{"cmd":"pip install claude-agent-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Main client for interacting with Claude agents.","symbol":"ClaudeSDKClient","correct":"from claude_agent_sdk import ClaudeSDKClient"},{"note":"Decorator for defining callable tools that agents can use.","symbol":"tool","correct":"from claude_agent_sdk import tool"},{"note":"Function to create and run a Multi-Context Protocol (MCP) server for tools.","symbol":"create_sdk_mcp_server","correct":"from claude_agent_sdk import create_sdk_mcp_server"}],"quickstart":{"code":"import os\nfrom claude_agent_sdk import ClaudeSDKClient, tool\n\n# Set your API key as an environment variable or replace 'YOUR_ANTHROPIC_API_KEY'\n# CLAUDE_CODE_TOKEN is also supported for authentication.\nANTHROPIC_API_KEY = os.environ.get('ANTHROPIC_API_KEY', 'YOUR_ANTHROPIC_API_KEY')\n\n@tool\ndef get_current_weather(location: str) -> str:\n    \"\"\"Gets the current weather for a given location.\"\"\"\n    if location == \"San Francisco\":\n        return \"Sunny, 70F\"\n    return \"Cloudy, 50F\"\n\nasync def main():\n    if ANTHROPIC_API_KEY == 'YOUR_ANTHROPIC_API_KEY':\n        print(\"Please set the ANTHROPIC_API_KEY environment variable or replace the placeholder.\")\n        return\n\n    client = ClaudeSDKClient(api_key=ANTHROPIC_API_KEY)\n    try:\n        response = await client.query(\n            \"What's the weather like in San Francisco?\",\n            tools=[get_current_weather]\n        )\n        print(f\"Agent response: {response.response}\")\n        if response.tool_calls:\n            for call in response.tool_calls:\n                print(f\"Tool call: {call.tool_name}({call.input_json})\")\n        if response.messages:\n            for message in response.messages:\n                if hasattr(message, 'text'):\n                    print(f\"Message: {message.text}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == '__main__':\n    import asyncio\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later.","message":"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.","severity":"breaking","affected_versions":"<0.1.0"},{"fix":"Upgrade to `claude-agent-sdk` version 0.1.55 or newer to ensure large tool results are handled correctly.","message":"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.","severity":"gotcha","affected_versions":"<0.1.55"},{"fix":"Upgrade to `claude-agent-sdk` version 0.1.53 or newer to resolve the deadlock issue.","message":"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.","severity":"gotcha","affected_versions":"<0.1.53"},{"fix":"Upgrade to `claude-agent-sdk` version 0.1.48 or newer to ensure correct fine-grained tool streaming behavior.","message":"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.","severity":"gotcha","affected_versions":"0.1.36-0.1.47"},{"fix":"Ensure `ANTHROPIC_API_KEY` or `CLAUDE_CODE_TOKEN` is set in your environment or passed as a parameter during client initialization.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}