用户发消息 → AI 调用工具 → 等待结果 → AI 回复

⏳ [任务名] 阶段 X/Y: 阶段描述
✅ [任务名] 完成: 结果摘要
⚠️ [任务名] 遇到问题: 具体描述

⚠️ [任务名] 遇到问题: 具体描述
   可能原因: XXX
   当前状态: 正在重试/等待用户决定
   预计恢复时间: XX 秒

🔄 继续等待（预计还需 XX 秒）
⏹️ 取消任务
💾 保存当前进度
📋 查看已完成部分

class ProgressReporter:
    def __init__(self, task_name: str, total_steps: int):
        self.task_name = task_name
        self.total_steps = total_steps
        self.current_step = 0
    
    def report(self, step_desc: str):
        self.current_step += 1
        msg = f"⏳ [{self.task_name}] 阶段 {self.current_step}/{self.total_steps}: {step_desc}"
        send_to_user(msg)  # 发送消息到用户界面
    
    def complete(self, summary: str):
        send_to_user(f"✅ [{self.task_name}] 完成: {summary}")
    
    def alert(self, problem: str, status: str = "正在处理"):
        send_to_user(f"⚠️ [{self.task_name}] 遇到问题: {problem}\n   状态: {status}")

# 使用示例
async def analyze_document(doc_path: str):
    reporter = ProgressReporter("文档分析", 4)
    
    reporter.report("读取文档")
    doc = await read_document(doc_path)
    
    reporter.report("提取关键信息")
    key_info = await extract_key_info(doc)
    
    reporter.report("生成摘要")
    summary = await generate_summary(key_info)
    
    reporter.report("格式化输出")
    result = await format_output(summary)
    
    reporter.complete(f"分析完成，共处理 {len(doc.pages)} 页")
    return result

from openai import OpenAI
from agents import Runner, Agent

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")

# 流式运行，实时输出
result = Runner.run_streamed(agent, input="分析这份 100 页的文档")

async for event in result.stream_events():
    if event.type == "tool_call_item":
        print(f"🔧 调用工具: {event.item.name}")
    elif event.type == "tool_call_output_item":
        print(f"📤 工具返回: {event.item.output[:100]}...")
    elif event.type == "message_output_item":
        print(f"💬 AI 回复: {event.item.content}")

// 1. 启动后台任务
{"tool": "exec", "command": "long-analysis.sh", "background": true}
// 返回: {"sessionId": "abc123"}

// 2. 轮询并发消息
{"tool": "process", "action": "poll", "sessionId": "abc123", "timeout": 5000}
{"tool": "message", "action": "send", "message": "⏳ 分析进行中，已完成 30%..."}

// 3. 循环直到完成
{"tool": "process", "action": "poll", "sessionId": "abc123"}
{"tool": "message", "action": "send", "message": "⏳ 分析进行中，已完成 60%..."}

// 4. 最终完成
{"tool": "message", "action": "send", "message": "✅ 分析完成: 共处理 10,000 条记录"}

// 启动子代理
{
  "tool": "sessions_spawn",
  "task": "分析 1000 篇文档并生成报告",
  "label": "文档分析任务",
  "mode": "run"
}

// 返回
{
  "status": "accepted",
  "runId": "run_abc123",
  "childSessionKey": "agent:main:subagent:uuid"
}

// 子代理完成后自动通知主会话
// 主会话收到通知后向用户报告

[AI 思考中...]
├── 事件: tool_call → [搜索中...]
├── 事件: tool_progress → [已找到 8 条结果]
├── 事件: tool_output → [搜索完成]
├── 事件: tool_call → [抓取中...]
├── 事件: tool_progress → [已抓取 3/8 页面]
└── 事件: final_response → [最终回复]