Entry Points
How It Works (High-level)
- 请求接收 — Next.js API 验证身份、检查信用额度、加载 LLM 和工具配置，异步保存用户消息，转发到 Python 后端
- 上下文组装 —
_init_context()按序加载工具（MCP + OAuth + Built-in）、初始化 LLM、检索 Memory/Profile、激活 Skills、构建 System Prompt，缓存至context_cache - Agent 创建 — 通过 DeepAgents 创建 LangGraph 图，装配 LLM、工具、中间件管线、Checkpointer 和 HITL 中断配置
- 消息构建 — 前端 chat_history 转换为 LangChain 消息类型（最多 30 条），追加当前用户消息
- 流式执行 — 进入
_astream_events()核心循环，框架事件转换为 SSE 消息流式发送 - 完成 — 发送
CompleteMessage，Checkpointer 自动保存状态
Context Assembly
上下文组装完成后缓存至_context_cache[session_id]，供 HITL resume() 复用。
Context 详解
System Prompt 组装、Token 管理与优化策略
System Prompt
系统提示词 — CORE、SOUL、TOOLS、WORKFLOW、MEMORY、动态注入
Event Streaming
_astream_events() 监听 DeepAgents 框架的内部事件，转换为标准 SSE 消息发送到前端：
SSE 事件类型
Messages
了解完整的消息流程、状态管理和持久化
Tool Execution
执行决策
审批决策基于 Auto-Run 模式（Run Everything / Use Allowlist / Ask Everytime）。Tool Call ID 通过 FIFO 队列匹配，按工具名分组存储，on_chat_model_end 时入队，on_tool_end 时出队。
HITL 中断与恢复
当工具需要审批时，Agent Loop 被挂起，状态通过 Checkpointer 持久化。恢复流程： 被拒绝的工具会附加 SystemMessage，明确告知 Agent 不要重试。HITL 详解
Auto-Run 模式、审批 UI、中断恢复机制的完整说明
Frontend Processing
前端handleStreamMessage() 消费 SSE 流，将事件路由到对应的状态管理：
Event Persistence
RealtimeEventSaver 批量持久化实时事件：
Error Handling
后端错误
错误通过
ErrorMessage SSE 事件发送，包含 error_code 和 details。
前端错误
流错误（AbortError、网络断开、解析错误）均有对应的异常处理和用户提示。
Timeouts
Concurrency & Isolation
- 每个 Session 拥有独立的 Checkpointer 状态（
thread_id隔离） - Context Cache 按
session_id隔离，resume 只能恢复对应会话 - 工具执行是序列化的（LangGraph 保证同一 Session 内不会并发执行工具）
- 用户工作空间按
user_id完全隔离
Where Things Can End Early
- Agent 超时 — 超过 7200s 最大执行时长
- HITL 审批超时 — 用户未在规定时间内响应
- 前端断开 — 网络中断或用户关闭页面
- 信用额度耗尽 — 调用前检查失败
- 模型错误 — 上下文窗口溢出或 API 异常