LIBRARY

用Claude Agent SDK构建CLI工具

Claude Agent SDK为你的CLI提供了任何参数解析器都无法提供的东西。它可以对模糊输入进行推理，迭代调用工具，并根据在代码库或环境中的发现调整其方法。

admin

• 11 min read
用Claude Agent SDK构建CLI工具
微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI工具导航 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo
预览图片

我已经向我的团队说了几个月，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智能体有三个工作：

  1. 解析用户意图。 从命令行接受自然语言提示或结构化标志。
  2. 运行智能体循环。 将提示交给SDK，SDK管理对话、工具执行和多轮推理。
  3. 返回结果。 将输出流式传输到终端，或生成结构化产物。

这是最简单的版本：

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="读取配置文件并解释其作用",
        options=ClaudeAgentOptions(
            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(options=options) 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="", flush=True)
        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，在下次调用时传递resume=session_id以继续完整上下文。
  • 环境感知。 将cwd设置为项目目录，以便智能体自我定位。

这是大多数人错过的东西：Claude Code按成本顺序运行四种压缩策略。微压缩缓存未更改的工具结果（每轮运行）。剪切修剪旧消息同时保护最近上下文。自动压缩在剪切不够时对先前对话进行摘要。上下文折叠为最长会话进行分段压缩。最便宜的先运行。最贵的只在其他都不起作用时才触发。这是长会话感觉如此良好的重要部分。

如果你在这个SDK之上构建自己的编排层，将管理背景细节作为首要关注点，而不是事后考虑。这就像一般的软件开发：关注关键点，而不是试图一次监控所有事情。

7、真正有效的护栏

智能体可能会失控。我在生产中见过。SDK提供真正的护栏，你应该在其上叠加你自己的：

  • max_turns：限制工具调用轮次以防止无限循环。
  • max_budget_usd：限制每次调用的支出。对于面向客户的任何东西都是不可协商的。
  • permission_mode："default"在危险操作前提示；"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_mode="default",
        max_turns=20,
        system_prompt="你是部署助手。使用可用工具帮助用户管理他们的服务。",
    )
    async with ClaudeSDKClient(options=options) 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="", flush=True)
            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_KEY=your-key-here

从内置工具和query()开始。随着你发现领域需要什么，添加自定义MCP工具。随着智能体赢得信任，叠加钩子和权限控制。

SDK处理对话管理、工具调度和会话生命周期。你的工作是定义正确的工具和正确的护栏。这就是整个模型，老实说，公平地说，如果你一直在关注Anthropic如何构建Claude Code本身，你知道它是有效的。

原文链接: Building CLI Tools with the Claude Agent SDK

汇智网翻译整理，转载请标明出处