claude-agent-sdk-python 自定义工具开发5分钟把 Claude 接进你的业务系统【免费下载链接】claude-agent-sdk-python项目地址: https://gitcode.com/GitHub_Trending/cl/claude-agent-sdk-python想让 Claude 自动改代码Bash 权限一放就翻车想接自己的数据库外部 MCP 又得另起进程。claude-agent-sdk-python 一次解决进程内 MCP 自定义工具、钩子拦截、细粒度权限回调。30秒安装启动要求只有 Python 3.10。装一条命令即可Claude Code CLI 已随 wheel 打包不用单独安装。pip install claude-agent-sdk想看源码和示例的话把仓库拉下来git clone https://gitcode.com/GitHub_Trending/cl/claude-agent-sdk-python就这些。Python 之外的依赖anyio、mcp、jsonschema随包自动装好。跑通第一个查询9行代码下面这段是query()的最小用法发一句话收回答import anyio from claude_agent_sdk import query, AssistantMessage, TextBlock async def main(): async for msg in query(promptWhat is 2 2?): if isinstance(msg, AssistantMessage): for b in msg.content: if isinstance(b, TextBlock): print(b.text) anyio.run(main)跑起来你会看到回答通常就是干净的 4。注意一个关键点迭代出来的不是 JSON 字符串而是带类型的对象可以按类型精确筛选和处理。从能力地图里选对你的入口SDK 的 API 面看着大其实按你要做什么可以压成四条路。多轮对话用 ClaudeSDKClient 接住上下文query()是一次性的上下文不留存要让 Claude 记住前一轮、继续追问用客户端。关键入口ClaudeSDKClient。async with ClaudeSDKClient() as client: await client.query(总结这个项目的报错日志) async for msg in client.receive_response(): print(msg)这意味着你可以做聊天界面receive_response()收到 ResultMessage 自动停止退出上下文时连接自动清理多轮追问时 Claude 一直记得前文。内置工具调用用白名单管住权限Claude 自带 Read、Write、Bash 等工具。allowed_tools是自动批准白名单——它不删除工具本身只决定哪些不用逐次确认。关键入口ClaudeAgentOptions。options ClaudeAgentOptions( allowed_tools[Read, Grep, Bash], permission_modeacceptEdits, )这意味着你可以放心让 Claude 在项目目录里读写文件、跑命令用permission_mode再细调授权档位acceptEdits、plan、dontAsk等。实时控制中途喊停和换模式长任务失控是生产场景最常见的事故。客户端支持运行中打断、切换权限模式。关键入口client.interrupt() / client.set_permission_mode()。async with ClaudeSDKClient() as client: await client.query(写一份一万字的分析) await client.interrupt() # 立即停 await client.set_permission_mode(plan) # 切到只规划不执行这意味着你的应用可以做紧急停止按钮也可以先规划、批准后再执行的两段式流程。自定义工具三步接进进程内 MCP自定义工具就是跑在你应用同进程里的 Python 函数没有子进程、没有 IPC还能直接碰你的业务对象。关键入口tool / create_sdk_mcp_server三步走tool定义函数 →create_sdk_mcp_server注册 → 塞进 options。options ClaudeAgentOptions( mcp_servers{db: server}, # create_sdk_mcp_server() 的返回值 allowed_tools[mcp__db__query_orders], # 命名格式mcp__服务名__工具名 )这意味着任何 Python 函数——查库、调内部 API、读配置——都能变成 Claude 会自己挑着用的工具。扩展实战把 Claude 接进 SQLite 数据库场景订单数据在一个 SQLite 文件里你想让 Claude 用自然语言回答订单总额多少而且只许读、不许写。第一步准备数据换成你自己的库文件即可import sqlite3 con sqlite3.connect(orders.db) con.execute(CREATE TABLE IF NOT EXISTS orders(id INTEGER, date TEXT, amount REAL)) con.executemany(INSERT INTO orders VALUES (?,?,?), [(1, 2026-09-10, 99.5), (2, 2026-09-12, 200.0)]) con.commit(); con.close()第二步定义工具函数。重点看两处SELECT 限制挡住一切写操作is_error标记把错误传回给 Claude让它自己换条路import json from claude_agent_sdk import tool tool(query_orders, 查询订单表仅允许 SELECT返回 JSON, {sql: str}) async def query_orders(args): sql args[sql].strip() if not sql.upper().startswith(SELECT): return {content: [{type: text, text: 只允许 SELECT}], is_error: True} con sqlite3.connect(orders.db) rows con.execute(sql).fetchall() con.close() return {content: [{type: text, text: json.dumps(rows, ensure_asciiFalse)}]}第三步注册工具并开聊import asyncio from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, create_sdk_mcp_server server create_sdk_mcp_server(namedb, tools[query_orders]) options ClaudeAgentOptions(mcp_servers{db: server}, allowed_tools[mcp__db__query_orders]) async def main(): async with ClaudeSDKClient(optionsoptions) as client: await client.query(订单总额是多少) async for msg in client.receive_response(): print(msg) asyncio.run(main())跑起来后Claude 会自己写出SELECT SUM(amount) FROM orders调用你定义的函数最终答出 299.5。因为工具函数和你的应用同进程它随时可以直接复用你的数据库连接和业务对象——这就是进程内 MCP 相比外部进程的价值。搭好防御层异常、拦截与安全线先认识异常。全部继承自ClaudeSDKError最外层兜底捕它即可。注意捕获顺序子类在前。异常触发场景应对动作CLINotFoundError找不到 Claude Code CLI检查安装或在 options 里指定cli_pathCLIConnectionError与 CLI 进程连不上/断了检查环境重试ProcessErrorCLI 进程非零退出读e.exit_code和e.stderrResultError运行以错误结果收尾max_turns、API 错误等按e.subtype/e.terminal_reason分支决定是否重试CLIJSONDecodeErrorCLI 输出无法解析为 JSON升级 SDK/CLI带着出错行报障完整定义在 src/claude_agent_sdk/_errors.py。权限线交给can_use_tool每次工具调用前你的回调先审一遍可以拒绝也可以改写输入。from claude_agent_sdk import ClaudeAgentOptions, PermissionResultAllow, PermissionResultDeny async def guard(tool_name, input_data, context): if tool_name Bash and rm -rf in input_data.get(command, ): return PermissionResultDeny(message危险命令已拒绝) return PermissionResultAllow() options ClaudeAgentOptions(can_use_toolguard, permission_modedefault)跑起来后Claude 一旦想执行rm -rf会被直接拦下并把理由回传给它其余工具放行。回调还能用updated_input改写参数比如把写入路径重定向到安全目录完整做法见 examples/tool_permission_callback.py。⚠️ 三条安全提醒permission_modebypassPermissions会跳过所有检查只在沙箱里用自定义工具和应用同进程工具函数里的输入校验如上例的 SELECT 限制是最后一道防线工具输出别不经过滤直接展示给用户防提示注入。进阶速览流式、混合部署与会话管理流式增量include_partial_messagesTrue让生成过程中持续吐出增量文本适合逐字上屏的界面。options ClaudeAgentOptions(include_partial_messagesTrue)混合 MCP 部署进程内服务器和外部 stdio 服务器可以挂在同一个mcp_servers里。mcp_servers{local: sdk_server, remote: {type: stdio, command: your-server}}会话持久化与分叉挂一个 SessionStore会话可跨重启恢复还能fork_session()拉出实验分支。options ClaudeAgentOptions(session_storeInMemorySessionStore())版本迁移0.1.0 把ClaudeCodeOptions改名为ClaudeAgentOptions并合并了系统提示配置对照见 CHANGELOG.md。按需查资源类型定义消息、内容块、选项全在这src/claude_agent_sdk/types.py示例合集查询、流式、钩子、权限回调都有examples/端到端测试场景看各特性怎么组合e2e-tests/版本变更记录CHANGELOG.md你现在能跑通一次性查询、做多轮对话还能把任意 Python 函数变成 Claude 的工具。下一步把实战里的 SQLite 表换成你自己的业务表再给 guard 回调加一条你们最怕的命令。【免费下载链接】claude-agent-sdk-python项目地址: https://gitcode.com/GitHub_Trending/cl/claude-agent-sdk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考