用Claude Agent SDK构建CLI工具

我已经向我的团队说了几个月Claude Code包装器将成为2026年的Cursor。在花了大量时间深入研究Claude Agent SDK后是的在像其他人一样仔细研究了泄露的源代码之后我比以往任何时候都更加确信。转变是真实的不再是来回复制粘贴上下文而是让AI控制自己的环境。它在需要时读取文件在需要时写入运行命令检查是否有效。而将其变成可交付产品的最快方式CLI。以下是我会如何着手以及我认为你也应该如何着手。1、为什么终端是正确的前门如果你为开发者构建或为开发者越来越多地将其接入工作流的智能体构建CLI就是原生界面。它可以与管道组合。它在CI/CD中运行。它不需要与浏览器标签争夺注意力。但真正值得关注的事情Claude Agent SDK为你的CLI提供了任何参数解析器都无法提供的东西。它可以对模糊输入进行推理迭代调用工具并根据在代码库或环境中的发现调整其方法。这不是终端里的聊天机器人。这是一个带有命令行前门的自主智能体。我一直在企业项目中使用这个确切的过滤器如果Claude Code不能在一日内搭建解决方案那么问题要么是范围界定不清要么是真正新颖的。无论哪种情况你都能快速学到东西。A CLI agent built on this SDK gives you that same rapid feedback loop, but for your users.10年前你可以筹集100万美元从FAANG聘请一个精英团队花几个月时间构建产品最终仍然获得0个客户。现在你可以将反馈循环缩短到几小时仍然获得0个客户。CLI是你如何将同样的速度交给使用你工具的人。2、核心循环异步生成器到此为止如果你研究过Claude Code在底层实际如何工作你就知道整个智能体作为单个异步生成器运行。每个事件模型输出、工具调用、错误都会即时流式传输。query()函数是一个为一次性任务设计的异步生成器在消息到达时流式传输消息。UI逐字符渲染而不是在30秒的沉默后。你可以中止它、暂停它或将它嵌套在子智能体中。以同样的方式构建你的。在高层次上你的CLI智能体有三个工作解析用户意图。从命令行接受自然语言提示或结构化标志。运行智能体循环。将提示交给SDKSDK管理对话、工具执行和多轮推理。返回结果。将输出流式传输到终端或生成结构化产物。这是最简单的版本import anyio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def main(): async for message in query( prompt读取配置文件并解释其作用, optionsClaudeAgentOptions( cwd/path/to/project, allowed_tools[Read, Write, Edit, Bash, Glob, Grep], ) ): if isinstance(message, ResultMessage): print(message.result) anyio.run(main)SDK附带用于文件操作、shell命令和代码搜索的内置工具。你不需要自己实现这些。智能体决定何时以及如何使用它们。这就是重点你定义工具箱智能体处理编排。3、通过MCP自定义工具你的领域API层内置工具涵盖通用内容。但当你需要领域特定逻辑查询数据库、调用内部API、检查服务健康时你需要定义自定义MCP模型上下文协议工具。这就是让我觉得不同的地方。我最近写道SaaS的未来是一个后端两个前门一个给人类一个给他们的智能体。你的用户点击按钮。他们的智能体调用你的API。两者做同样的事情。当你的CLI智能体通过MCP暴露领域工具时你正是在构建这种架构。技能成为新的分销渠道。你的产品成为他们智能体的工具而不是他们必须访问的标签页。我在管理AI产品项目中艰难学到的一些设计原则一个工具一个任务。check_service_health和restart_service比service_operation(action, name)更好。模型用专注的工具推理得更好。将错误作为内容返回而不是异常。智能体可以对失败进行推理并重试。这反映了Claude Code内部如何处理错误错误恢复不是循环的包装器它就是循环本身。对危险操作设限。删除资源或推送到生产的工具需要确认逻辑或试运行模式。没有例外。开发者可以使用allowed_tools来控制智能体自主性自动批准特定操作或使用permission_mode对敏感操作如文件编辑要求用户确认。4、将其接入你的CLI使用你喜欢的任何CLI框架argparse、click、typer。真正的决定是你的界面模式自然语言模式自由形式提示$ mycli 将数据库模块重构为使用连接池混合模式常见任务的子命令自由形式回退$ mycli scaffold --template fastapi my-project $ mycli ask 为什么这个测试不稳定无论哪种方式提示都会流入SDK的query()函数或者为了更多控制流入ClaudeSDKClient后者维护多轮对话的会话历史和上下文。TypeScript SDK V2预览版通过send()和stream()方法使这一点更加清晰用于多轮对话。如果你在那个生态系统中构建值得关注。CLI位于针对API编写代码和使用GUI之间。它为你提供编程控制而无需编写完整集成。管道输出、链式命令、在CI/CD中运行、将复杂工作流别名为单行命令。REST API用于应用程序。MCP用于模型到工具通信。CLI用于在终端中思考的人类。不同的用户不同的界面相同的后端。5、流式输出因为冻结的终端会扼杀信任没有人喜欢盯着空白光标。让Claude Code感觉神奇的事情之一是UI逐字符渲染。Agent SDK为你提供同样的能力async with ClaudeSDKClient(optionsoptions) 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) elif isinstance(message, ResultMessage): print(f\n\n完成 (停止原因: {message.stop_reason}))ClaudeSDKClient为你提供对智能体生命周期的细粒度控制流式传输、中断、运行时MCP服务器管理。当你只需要最终结果时使用更简单的query()。Claude Code还会在用户输入时预计算响应这是响应时间感觉比应该更快的原因之一。对于像yes这样的简单输入系统在你按下回车之前就开始处理你的可能结果。在设计自己的UX时关于感知延迟这是值得记住的事情。6、上下文、状态和压缩秘密CLI调用通常是无状态的。但智能体从上下文中受益匪浅。SDK支持几种策略项目文件作为上下文。通过setting_sources[project]自动加载CLAUDE.md或传递自定义system_prompt。会话恢复。从init消息捕获session_id在下次调用时传递resumesession_id以继续完整上下文。环境感知。将cwd设置为项目目录以便智能体自我定位。这是大多数人错过的东西Claude Code按成本顺序运行四种压缩策略。微压缩缓存未更改的工具结果每轮运行。剪切修剪旧消息同时保护最近上下文。自动压缩在剪切不够时对先前对话进行摘要。上下文折叠为最长会话进行分段压缩。最便宜的先运行。最贵的只在其他都不起作用时才触发。这是长会话感觉如此良好的重要部分。如果你在这个SDK之上构建自己的编排层将管理背景细节作为首要关注点而不是事后考虑。这就像一般的软件开发关注关键点而不是试图一次监控所有事情。7、真正有效的护栏智能体可能会失控。我在生产中见过。SDK提供真正的护栏你应该在其上叠加你自己的max_turns限制工具调用轮次以防止无限循环。max_budget_usd限制每次调用的支出。对于面向客户的任何东西都是不可协商的。permission_modedefault在危险操作前提示acceptEdits自动接受文件更改同时对shell命令设限。PreToolUse钩子在执行前拦截和验证工具调用。记录它们、阻止模式、要求确认。错误处理捕获CLINotFoundError、CLIConnectionError和ProcessError以处理SDK级故障。这反映了Claude Code内部的7阶段批准链输入验证、拒绝规则、允许规则、工具特定检查、钩子、ML分类器、用户提示。不是一个开关。一个内置渐进信任的规则引擎。说真的用规则约束智能体的解决方案空间、边学边做的习惯、以及护栏 paradoxically increases productivity and reliability. 以同样的理念构建你的。8、完整图景这是一个最小但生产就绪的CLI智能体带有自定义工具import sys import anyio from claude_agent_sdk import ( tool, create_sdk_mcp_server, ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock, ResultMessage, ) tool(deploy_service, 将服务部署到预发或生产环境, { service: str, environment: str, }) async def deploy_service(args): service, env args[service], args[environment] return {content: [{type: text, text: f已将 {service} 部署到 {env}}]} server create_sdk_mcp_server(deploy-tools, tools[deploy_service]) async def main(): prompt .join(sys.argv[1:]) or 你能帮我什么 options ClaudeAgentOptions( cwd., allowed_tools[Read, Glob, Grep, Bash], mcp_servers{deploy: server}, permission_modedefault, max_turns20, system_prompt你是部署助手。使用可用工具帮助用户管理他们的服务。, ) async with ClaudeSDKClient(optionsoptions) as client: await client.query(prompt) 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) elif isinstance(message, ResultMessage): print() anyio.run(main)对于生产环境使用--bare模式跳过自动发现本地钩子和插件。这对确定性的CI/CD行为至关重要。9、这种模式何时有意义当任务涉及探索和判断、当用户输入模糊或多样、当工作流是多步骤时使用这种方法。对于简单的CRUD CLI或完全确定性的工具这是过度设计。但这是我的看法符合探索和判断的任务范围正在快速扩展。每周智能体在处理模糊性方面都变得更好。你今天在这个SDK上构建的工具不仅仅是解决当前问题。它们让你站在浪潮的正确一边。与Cursor首次推出时每个人仍在争论Copilot vs no Copilot时的能量相同。10、入门pip install claude-agent-sdk export ANTHROPIC_API_KEYyour-key-here从内置工具和query()开始。随着你发现领域需要什么添加自定义MCP工具。随着智能体赢得信任叠加钩子和权限控制。SDK处理对话管理、工具调度和会话生命周期。你的工作是定义正确的工具和正确的护栏。这就是整个模型老实说公平地说如果你一直在关注Anthropic如何构建Claude Code本身你知道它是有效的。原文链接用Claude Agent SDK构建CLI工具 - 汇智网