🚀 Claude Agent SDK 使用指南:流式输出 (Streaming Output)

在构建 AI Agent 应用时,用户体验至关重要。如果让用户盯着一个旋转的加载图标等待几秒甚至几十秒才能看到完整的回复,体验是非常糟糕的。

流式输出 (Streaming) 允许你的应用像打字机一样,实时展示 Agent 的思考和回复过程。本文将深入讲解如何在 Python 中使用 Claude Agent SDK 实现流式输出,涵盖文本生成和工具调用的实时反馈。

核心概念

默认情况下,Agent SDK 会在 Agent 完成整个回复后才返回完整的 AssistantMessage 对象。

要开启流式输出,我们需要关注两个关键点:

  1. 配置选项 :在 ClaudeAgentOptions 中设置 include_partial_messages=True。
  2. 事件处理 :处理 StreamEvent 类型的消息,从中提取 content_block_delta(内容增量)。

准备工作

确保你已经安装并配置好了 Claude Agent SDK 环境。

Python

javascript 复制代码
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent, ResultMessage
import asyncio
import sys

实战 1:基础文本流式输出

这是最基础的场景。我们需要过滤出 StreamEvent,找到文本类型的增量更新 (text_delta),并实时打印出来。

代码实现

Python

python 复制代码
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent

async def stream_text_response():
    # 1. 开启流式输出选项
    options = ClaudeAgentOptions(
        include_partial_messages=True, 
    )

    print("🤖 Agent 正在思考...\n")
    
    # 2. 发起查询并遍历返回的消息流
    async for message in query(prompt="请用三句话解释什么是量子纠缠", options=options):
        # 3. 检查消息是否为流式事件
        if isinstance(message, StreamEvent):
            event = message.event
            
            # 4. 寻找内容增量事件 (content_block_delta)
            if event.get("type") == "content_block_delta":
                delta = event.get("delta", {})
                
                # 5. 确认是文本增量 (text_delta)
                if delta.get("type") == "text_delta":
                    # 实时打印文本,使用 end="" 避免换行,flush=True 确保立即显示
                    print(delta.get("text", ""), end="", flush=True)
    
    print("\n\n✅ 回复完成")

if __name__ == "__main__":
    asyncio.run(stream_text_response())

代码解析

  • include_partial_messages=True:这是开关,必须开启。
  • message.event:包含了原始的 Claude API 事件数据。
  • flush=True:在 Python 中非常重要,确保字符被立即输出到控制台,而不是留在缓冲区。

实战 2:监控工具调用 (Tool Calls)

Agent 的强大之处在于使用工具。流式输出不仅能显示文本,还能让我们看到 Agent 正在输入什么参数 以及 何时开始/结束调用工具。

代码实现

Python

ini 复制代码
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent

async def stream_tool_usage():
    options = ClaudeAgentOptions(
        include_partial_messages=True,
        # 假设我们给 Agent 配置了一些工具
        allowed_tools=["Bash", "Read"], 
    )

    current_tool = None
    tool_input_accumulator = ""

    print("🔍 开始任务:读取项目中的 README 文件...\n")

    async for message in query(prompt="Read the README.md file", options=options):
        if isinstance(message, StreamEvent):
            event = message.event
            event_type = event.get("type")

            # --- 阶段 1: 工具调用开始 ---
            if event_type == "content_block_start":
                content_block = event.get("content_block", {})
                if content_block.get("type") == "tool_use":
                    current_tool = content_block.get("name")
                    tool_input_accumulator = "" # 重置累加器
                    print(f"\n🛠️  正在调用工具: {current_tool}")

            # --- 阶段 2: 参数流式输入 ---
            elif event_type == "content_block_delta":
                delta = event.get("delta", {})
                if delta.get("type") == "input_json_delta":
                    # 工具的参数是 JSON 格式,会分片到达,需要累加
                    chunk = delta.get("partial_json", "")
                    tool_input_accumulator += chunk
                    # 可以在这里打印 chunk 看到参数是逐字生成的
                    # print(chunk, end="", flush=True) 

            # --- 阶段 3: 工具调用结束 ---
            elif event_type == "content_block_stop":
                if current_tool:
                    print(f"📥 工具输入参数完整版: {tool_input_accumulator}")
                    print(f"✅ 工具 {current_tool} 调用请求已发送")
                    current_tool = None

if __name__ == "__main__":
    asyncio.run(stream_tool_usage())

关键点

  • content_block_start: 标志着一个新的块(文本或工具使用)开始。我们在这里捕获工具名称。
  • input_json_delta: 工具的参数不是一次性给出的,而是作为 JSON 字符串片段流式传输的。你需要将它们拼接起来才能得到完整的 JSON。

实战 3:打造完整交互 UI (文本+工具状态)

最后,我们将两者结合,模拟一个类似 ChatGPT 的控制台体验:Agent 说话时打字机输出,Agent 使用工具时显示状态指示器。

代码实现

Python

ini 复制代码
import asyncio
import sys
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
from claude_agent_sdk.types import StreamEvent

async def interactive_ui():
    options = ClaudeAgentOptions(
        include_partial_messages=True,
        allowed_tools=["Read", "Bash", "Grep"], # 示例工具
    )

    # 状态标记:当前是否在执行工具
    in_tool_mode = False

    print("💬 请输入指令 (示例: Find all TODO comments in the codebase)")
    user_prompt = "Find all TODO comments in the codebase" 
    
    async for message in query(prompt=user_prompt, options=options):
        
        # 处理流式事件
        if isinstance(message, StreamEvent):
            event = message.event
            event_type = event.get("type")

            # 1. 检测工具开始
            if event_type == "content_block_start":
                content_block = event.get("content_block", {})
                if content_block.get("type") == "tool_use":
                    tool_name = content_block.get("name")
                    # 显示工具状态,例如 [Using Bash...]
                    print(f"\n\n[⚙️ 正在使用 {tool_name}...]", end="", flush=True)
                    in_tool_mode = True

            # 2. 处理增量内容
            elif event_type == "content_block_delta":
                delta = event.get("delta", {})
                
                # 只有当 **不是** 在工具模式下,才打印文本
                # 这样可以避免把工具的 JSON 参数打印到屏幕上干扰用户
                if delta.get("type") == "text_delta" and not in_tool_mode:
                    sys.stdout.write(delta.get("text", ""))
                    sys.stdout.flush()

            # 3. 检测块结束
            elif event_type == "content_block_stop":
                if in_tool_mode:
                    print(" 完成", flush=True)
                    in_tool_mode = False
        
        # 处理最终结果消息 (任务结束)
        elif isinstance(message, ResultMessage):
            print(f"\n\n🎉 任务执行完毕")

if __name__ == "__main__":
    asyncio.run(interactive_ui())

⚠️ 注意事项与限制

在使用流式输出时,有几个已知限制需要注意:

  1. Extended Thinking (扩展思考) : 如果你设置了 max_thinking_tokens 启用了扩展思考模式,SDK 目前不会 发出 StreamEvent 消息。你只能在每轮对话结束后收到完整的消息。
  2. 结构化输出 (Structured Output) : 如果你强制 Agent 输出特定的 JSON 结构,解析后的 JSON 结果只会在最后的 ResultMessage.structured_output 中出现,而不会通过流式增量发送。

希望这篇指南能帮你打造出更丝滑的 Agent 交互体验!Happy Coding! 🚀

相关推荐
prince_zxill6 小时前
把 17 个散文件装进一个文件夹:拆解 claude-plugins-official 的插件打包术(47,413 Star 实测)
python·github·agent·mcp·claude code
程序员张富华6 小时前
一次发布拦住12个破坏性变更:我们给Agent工作流加了Schema门禁
人工智能·agent
ZhengEnCi9 小时前
Claude 的记忆是怎么设计的:四层记忆栈,和一场叫「做梦」的离线整理
aigc·agent·ai编程
一缕82年的清风12 小时前
百万 Token 砍到 0.5 美元!微软新模型半价、DeepSeek 连夜撤回搜索费,11 月底开发者怎么搭最省钱?
gpt·claude·deepseek
Csvn1 天前
换供应商要改一遍代码?把模型接入收进一层网关(C04)
人工智能·aigc·agent
Maynor9961 天前
Trymodel 使用介绍:一个平台同时用 Claude、GPT、Gemini 和 Grok
人工智能·gpt·ai·程序员·教程·claude·语音
七夜zippoe1 天前
多 Agent 通信灾难:状态不一致导致雪崩故障的排查与防护
ai·agent·通信灾难·雪崩故障·排查与防护
谙弆悕博士1 天前
多智能体架构详解:层级树状架构(分级主从型)
运维·架构·大模型·agent·多智能体·langgraph·层级树状
学无止境小袁同学1 天前
Google ADK 学习指南
python·llm·agent·多agent·google adk·llmagent·agent cli
塑料铲子1 天前
你的 Skill 越多越蠢?Token 上下文爆炸的求生指南
机器学习·agent