Entry Points
| 入口 | 路由 | 说明 |
|---|---|---|
| Web 前端 | POST /api/agent/invoke | Next.js API Route，代理到 Python 后端 |
| Python API | POST /api/agent/invoke | FastAPI 路由，直接调用 AgentService |
| Resume (HITL) | POST /api/agent/resume | 用户审批后恢复执行 |
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() 复用。
Event Streaming
_astream_events() 监听 DeepAgents 框架的内部事件，转换为标准 SSE 消息发送到前端：
SSE 事件类型
| SSE 事件 | 触发时机 | 关键字段 |
|---|---|---|
text | LLM 每输出一个 token | content, role |
tool_call | LLM 决定调用工具 | tool_name, parameters, requires_approval |
tool_call_result | 工具执行完成 | tool_name, result, is_error |
complete | Agent 执行结束 | content, summary |
error | 发生异常 | error, error_code, details |
token_usage | LLM 调用结束后 | prompt_tokens, completion_tokens |
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 批量持久化实时事件：
| 配置 | 值 |
|---|---|
| 批量大小 | 3 个事件 |
| 批量间隔 | 100ms |
| 重试策略 | 指数退避，最多 3 次 |
| 降级方案 | LocalStorage 备份 |
Error Handling
后端错误
| 错误类型 | 检测条件 | 用户提示 |
|---|---|---|
| 输入长度超限 | Range of input length / InvalidParameter | 建议缩短输入 |
| 上下文窗口溢出 | context length / token limit | 建议开启新会话 |
| 通用异常 | 其他所有 Exception | 包含 traceback 详情 |
ErrorMessage SSE 事件发送，包含 error_code 和 details。
前端错误
| HTTP 状态码 | 含义 | 处理 |
|---|---|---|
| 401 | 未授权 | 重定向到登录 |
| 403 | 信用额度不足 | Toast 提示 |
| 503 | 后端未启动 | 连接错误提示 |
| 504 | 请求超时 | 超时提示 |
Timeouts
| 超时项 | 默认值 | 说明 |
|---|---|---|
| Agent 最大执行时长 | 7200s (2h) | FastAPI 单次调用上限 |
| MCP 服务器 | 1800s (30min) | 每个 MCP 服务器的连接超时 |
| HITL 工具审批 | 可配置 | 每个工具独立设置 |
| LangGraph 递归限制 | 999 | Agent 循环的最大迭代次数 |
Concurrency & Isolation
- 每个 Session 拥有独立的 Checkpointer 状态（
thread_id隔离） - Context Cache 按
session_id隔离，resume 只能恢复对应会话 - 工具执行是序列化的（LangGraph 保证同一 Session 内不会并发执行工具）
- 用户工作空间按
user_id完全隔离
Where Things Can End Early
- Agent 超时 — 超过 7200s 最大执行时长
- HITL 审批超时 — 用户未在规定时间内响应
- 前端断开 — 网络中断或用户关闭页面
- 信用额度耗尽 — 调用前检查失败
- 模型错误 — 上下文窗口溢出或 API 异常