# Claude Agents SDK BEATS all Agent Framework! (Beginners Guide)

Source: https://www.youtube.com/watch?v=i6N8oQQ0tUE
Recap page: https://rapidrecap.app/video/i6N8oQQ0tUE
Generated: 2025-10-04T01:02:15.381+00:00

---
## Quick Overview

The video demonstrates how to use the Claude Agent SDK in Python to create and run AI agents capable of performing complex tasks, covering basic agent creation, utilizing internal tools like Bash, implementing custom tools such as a file writer, and configuring agent behavior using ClaudeAgentOptions.

**Key Points:**
- The Claude Agent SDK can be installed via pip using `pip install claude-agent-sdk` for Python or globally via npm for Claude Code (`npm install -g @anthropic-ai/claude-code`).
- A basic agent is created by importing `query` from `claude_agent_sdk`, defining an asynchronous `main` function, and calling `async for message in query(prompt="...")` to run the agent.
- Internal tools like 'Write' are accessible by default; this was demonstrated by prompting the agent to create a file named 'greeting.txt' with specific content, which resulted in a `ToolUseBlock` calling the 'Write' tool.
- Custom tools, like a 'greet' function, are integrated by decorating the function with `@tool("greet", "Greet a user", {"name": str})` and passing the tool definition via `create_sdk_mcp_server` and configuring `allowed_tools` in `ClaudeAgentOptions`.
- Agent behavior is configured using `ClaudeAgentOptions`, allowing specification of `system_prompt`, `permission_mode="acceptEdits"`, and mapping custom tools via `mcp_servers`.
- The demonstration of the custom tool execution shows the agent outputting an `AssistantMessage` containing a `ToolUseBlock` specifying the 'Write' tool with correct inputs, followed by a `ToolResultBlock` confirming success.

![Screenshot at 00:00: The initial diagram illustrates the Claude Agent SDK at the center, connecting to various specialized AI agents like the Code Security Agent, Contract Review Agent, and Financial Reporting Agent, highlighting the SDK's role as a hub for agent orchestration.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-00-00.png)

**Context:** This tutorial focuses on leveraging Anthropic's Claude Agent SDK, particularly for Python developers, showing how to move beyond simple prompts to build sophisticated AI agents that can interact with the environment using predefined or custom tools. The presenter walks through installation, basic agent execution using the streamable `query` function, and then advances to configuring agents with specific tool access and custom functionality via the Model Context Protocol (MCP).

## Detailed Analysis

The video provides a comprehensive guide on using the Claude Agent SDK, starting with installation methods for both Python (`pip install claude-agent-sdk`) and Node.js/Claude Code (`npm install -g @anthropic-ai/claude-code`). The presenter first builds a basic agent using the `query` function within an async loop to stream responses, demonstrating that internal tools like 'Write' are available by default, as seen when the agent successfully creates a file ('greeting.txt') based on a prompt (01:23-02:30). The session then progresses to custom tools (Step 3), showing how to define a custom Python function decorated with `@tool` (e.g., `greet`) (04:27). This custom tool is then registered by creating an MCP server using `create_sdk_mcp_server` (04:46) and referencing it in `ClaudeAgentOptions` via `mcp_servers` and `allowed_tools` (05:01). Finally, the agent is run with these custom options, and the output confirms the agent correctly invoked the custom 'greet' tool, demonstrating its ability to use user-defined capabilities (05:19-05:30). The video concludes by mentioning advanced options like system prompts and setting the working directory (`cwd`) within `ClaudeAgentOptions` (05:35).

### Agent SDK Setup

- Install Python SDK via 'pip install claude-agent-sdk'
- Install Claude Code via 'npm install -g @anthropic-ai/claude-code'
- Set ANTHROPIC_API_KEY environment variable

### Basic Agent Creation

- Use 'from claude_agent_sdk import query'
- Define async main function
- Execute agent using 'async for message in query(prompt="...")'

### Internal Tool Usage (Write)

- Prompt agent to create a file
- Agent returns ToolUseBlock for 'Write' tool
- ToolResultBlock confirms file creation ('greeting.txt')

### Custom Tool Implementation

- Define tool function decorated with '@tool("greet", ...)'
- Create MCP server using 'create_sdk_mcp_server'
- Pass server object to 'ClaudeAgentOptions' via 'mcp_servers'

### Agent Configuration (Claude Options)

- Configure agent behavior using 'ClaudeAgentOptions'
- Set 'system_prompt', 'permission_mode="acceptEdits"', and 'cwd'
- Explicitly list custom tools in 'allowed_tools'

![Screenshot at 00:00: Diagram showing the Claude Agent SDK architecture connecting to various specialized agents like Code Review and Invoice Processing.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-00-00.png)
![Screenshot at 00:06: Demonstration of installing the Python Agent SDK using pip in the terminal: pip install claude-agent-sdk.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-00-06.png)
![Screenshot at 00:10: A screenshot of the Claude Docs webpage detailing the capabilities of Claude Code, Anthropic's agentic coding tool.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-00-10.png)
![Screenshot at 00:30: The agenda slide outlining the four main topics for the tutorial: Basic, Internal Tools, Custom Tools, and Claude Options.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-00-30.png)
![Screenshot at 00:48: Terminal command demonstrating the installation of Claude Code globally using npm: npm i -g @anthropic-ai/claude-code.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-00-48.png)
![Screenshot at 01:27: The basic Python code structure for an agent, importing asyncio and query, defining an async main function, and running it with asyncio.run\(main\(\)\).](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-01-27.png)
![Screenshot at 02:13: Output from running the basic agent, showing the initial SystemMessage structure, including available tools like 'Task', 'Bash', and 'Read'.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-02-13.png)
![Screenshot at 04:06: Code snippet defining a custom tool named 'greet' using the @tool decorator, specifying its name, description, and required argument 'name' \(string type\).](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-04-06.png)
![Screenshot at 05:35: Code defining ClaudeAgentOptions to configure the agent's behavior, setting a system\_prompt to define its persona as an expert Python developer and enabling file editing with permission\_mode='acceptEdits'.](https://ss.rapidrecap.app/screens/i6N8oQQ0tUE/00-05-35.png)