claude-code-sdk-python Python SDK 快速指南6 个场景搞定自定义 MCP 工具【免费下载链接】claude-agent-sdk-python项目地址: https://gitcode.com/GitHub_Trending/cl/claude-agent-sdk-pythonclaude-code-sdk-python 是构建 Claude Agent 应用的 Python SDKClaude Agent Python SDK让你用query()或ClaudeSDKClient驱动 Claude Code并挂载自定义 MCP 工具与钩子。适合会 Python 基础、想快速搭对话式 Agent 的工程师。一、能干什么能力速览能力解决的问题入口 API一次性问答无状态单问单答、批处理脚本、CI 流水线query()多轮对话带上下文追问、根据上轮回复决定下一步ClaudeSDKClient内置工具让 Claude 读写文件、跑命令allowed_toolspermission_mode自定义 MCP 工具把你写的 Python 函数变成 Claude 可调用的工具toolcreate_sdk_mcp_serverHook 护栏在工具执行前做确定性拦截或改写hooksHookMatcher流式输出边生成边消费消息实时渲染client.receive_response()运行原理一句话SDK 在你的 Python 进程里拉起 Claude Code CLI 子进程协作自定义工具则以进程内 MCP 服务器的形式直接跑在同一个 Python 进程里不需要额外起进程。二、3分钟跑起来环境与首次输出运行前确认三件事Python 3.10Node.jsCLI 的运行时依赖Claude Code CLI ≥ 2.0.0pip 包默认已内置通常无需单独装安装只保留两条命令装 SDK 本体内含捆绑版 Claude Codepip install claude-agent-sdk装你自己维护的 CLI 版本可选通过cli_path指定npm install -g anthropic-ai/claude-code最小可运行示例完整版见 examples/quick_start.pyimport anyio from claude_agent_sdk import query async def main(): # query 返回异步迭代器每产出一条消息就 yield 一次 async for message in query(promptWhat is 22?): print(message) anyio.run(main)三、场景实战6 个常用用法一次性问答与行为约束query() ClaudeAgentOptions适合所有输入一次性给全、不需要追问的场合。ClaudeAgentOptions的system_prompt设定角色基调max_turns限制 agent 循环轮数from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock options ClaudeAgentOptions( system_prompt用一句话中文回答。, max_turns1, # 只跑一轮防止多步发散 ) async for message in query(prompt什么是 Python, optionsoptions): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text)多轮会话客户端ClaudeSDKClient 有状态对话需要上一句答完再决定下一句时用ClaudeSDKClient用上下文管理器包住即可自动连接与断开from claude_agent_sdk import ClaudeSDKClient async with ClaudeSDKClient() as client: # 退出时自动断开 await client.query(法国的首都是哪里) async for message in client.receive_response(): print(message) await client.query(那座城市的常住人口是多少) # 带上下文的追问 async for message in client.receive_response(): print(message)更多会话模式参考 examples/streaming_mode.py。让 Claude 读写文件、执行命令allowed_tools permission_modeallowed_tools是权限白名单列进去的工具自动批准未列出的交给permission_mode决策。acceptEdits模式会自动接受文件编辑类操作省去逐次确认from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock options ClaudeAgentOptions( allowed_tools[Read, Write, Bash], # 白名单内的工具免提示 permission_modeacceptEdits, # 文件编辑自动接受 ) async for message in query(prompt创建 hello.txt 并写入一行文字, optionsoptions): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text)给 Claude 装配自制工具自定义 MCP 工具三步挂载想让 Claude 调用你自己的业务函数时按三步走tool定义 →create_sdk_mcp_server打包 →mcp_servers挂载from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient # 第一步tool 定义工具第三个参数是入参 schema tool(greet, Greet a user by name, {name: str}) async def greet_user(args): return {content: [{type: text, text: f你好{args[name]}}]} # 第二步打包成进程内 MCP 服务器第三步经 mcp_servers 挂载 server create_sdk_mcp_server(demo, tools[greet_user]) options ClaudeAgentOptions( mcp_servers{demo: server}, allowed_tools[mcp__demo__greet], # 命名规则mcp__服务器__工具 ) async with ClaudeSDKClient(optionsoptions) as client: await client.query(向小明打个招呼) async for message in client.receive_response(): print(message)完整多工具版本六个计算器工具见 examples/mcp_calculator.py。危险命令护栏PreToolUse 钩子拦截黑名单钩子由 Claude Code 在 agent 循环的特定点调用而不是模型调用适合确定性校验。返回permissionDecision: deny即可在命令执行前拦截from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher async def check_command(input_data, tool_use_id, context): if input_data[tool_name] ! Bash: return {} if foo.sh in input_data[tool_input].get(command, ): return {hookSpecificOutput: { hookEventName: PreToolUse, permissionDecision: deny, permissionDecisionReason: 命中黑名单}} return {} options ClaudeAgentOptions( hooks{PreToolUse: [HookMatcher(matcherBash, hooks[check_command])]} )其余事件类型SessionStart、Stop 等的写法见 examples/hooks.py。流式实时输出receive_response() 边收边处理长回复不想等完整结果时用async for消费receive_response()拿到AssistantMessage后逐块打印文本块from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock async with ClaudeSDKClient() as client: await client.query(讲一个短故事) async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text, end, flushTrue) # 增量打印四、出错时怎么办错误对照表异常类典型触发场景处理建议ClaudeSDKError所有 SDK 异常的基类作为兜底except捕获CLINotFoundError找不到 Claude Code CLICLIConnectionError子类安装 CLI 或用ClaudeAgentOptions(cli_path...)指路CLIConnectionError与 CLI 建连失败检查进程环境、端口与依赖ProcessErrorCLI 子进程异常退出带exit_code/stderr打印两者定位根因CLIJSONDecodeErrorCLI 输出了无法解析的 JSON 行升级 SDK核对捆绑 CLI 版本捕获示例导入from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeErrortry: async for message in query(promptHello): pass except CLINotFoundError: print(找不到 Claude Code先安装 CLI) except ProcessError as e: print(fCLI 进程异常退出exit_code{e.exit_code}) except CLIJSONDecodeError as e: print(fJSON 解析失败{e})全部异常定义在 src/claude_agent_sdk/_errors.py。五、进阶三步混合 MCP、类型速览与旧版迁移进程内与外部 stdio MCP 服务器共存mcp_servers字典的 value 允许两种形态混用create_sdk_mcp_server(...)返回的McpSdkServerConfig代表进程内服务器{type: stdio, command: ..., args: [...]}字典代表外部子进程服务器。键名互不冲突即可同时挂载工具仍按mcp__server__tool统一命名。常用类型一句话速览ClaudeAgentOptions所有运行时配置system_prompt、cwd、permission_mode、mcp_servers、hooks的容器。AssistantMessage/UserMessage/ResultMessage消息流中最常见的三类分别对应 Claude 回复、用户与工具结果、整轮汇总含total_cost_usd。TextBlock/ToolUseBlock/ToolResultBlock消息内的内容块靠isinstance区分处理。HookMatcher把钩子回调绑定到指定事件与工具名的匹配器。完整定义见 src/claude_agent_sdk/types.py。从 Claude Code SDK0.1.0升级要点ClaudeCodeOptions改名为ClaudeAgentOptions导入与引用都要更新。custom_system_prompt与append_system_prompt合并为单一system_prompt字段且不再默认注入 Claude Code 系统提示。settings.json、CLAUDE.md等文件设置默认不加载用setting_sources显式控制来源。新增编程式子代理agents选项与会话分支fork_session。细节以 CHANGELOG.md 的 0.1.0 条目为准。六、资料索引examples/quick_start.py覆盖裸查询、带ClaudeAgentOptions的查询、工具调用的最小完整示例。examples/mcp_calculator.py六个计算器工具的进程内 MCP 服务器展示自定义工具开发全链路。examples/hooks.pyPreToolUse、SessionStart 等多种钩子模式的可运行集合。examples/streaming_mode.py基础流式、多轮对话、边发边收等ClaudeSDKClient会话模式。src/claude_agent_sdk/_errors.py全部异常类的源码定义。CHANGELOG.md版本变更记录与迁移说明。至此覆盖了从环境安装、六个实战场景到自定义 MCP 工具挂载的完整路径。生产落地前建议先把 examples/ 下的样例各跑一遍确认各环节行为符合预期。【免费下载链接】claude-agent-sdk-python项目地址: https://gitcode.com/GitHub_Trending/cl/claude-agent-sdk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考