1. 项目概述：为什么我们需要 AgentGate 这样的框架？
最近在多个实际项目里反复遇到一个看似简单、实则棘手的问题：当把多个智能体（Agent）串起来跑一个复杂任务时，系统不是“偶尔出错”，而是“错得毫无规律”——前一秒还在按计划调用工具、生成报告，后一秒就卡死在某个中间节点，日志里既没有报错堆栈，也没有超时提示，只有几行空泛的“agent_3 status: unknown”。更麻烦的是，这种故障往往不发生在开发环境，而是在上线后第3天、第7天，甚至第15天，伴随着用户并发量缓慢爬升才突然爆发。我试过加日志、加熔断、加重试，但问题像打地鼠一样，按下一个，另一个又冒出来。直到我们开始系统性地梳理整个多 Agent 流程的生命周期，才意识到：我们缺的不是单个 Agent 的能力，而是让一群 Agent 能稳定协作的“交通管制系统”。
AgentGate 就是为解决这个问题而生的。它不是一个新模型、不是另一个 LLM 封装库，而是一套轻量级但结构完整的可靠性框架——专为多 Agent 系统设计，聚焦于“当事情出错时，系统还能继续工作、可定位、可恢复”。它的核心价值不在于让 Agent 更聪明，而在于让 Agent 组合更可靠。比如，当你用三个 Agent 分别负责“理解用户意图→查询数据库→生成可视化图表”时，AgentGate 会自动为你管理它们之间的状态流转、失败兜底、上下文透传、资源配额和可观测入口。它不替代你的 Agent 实现，而是像给每辆自动驾驶汽车装上统一的车载通信协议、黑匣子和应急响应模块。适合正在落地真实业务场景的团队：不是在做 Demo 演示，而是在支撑客服工单自动分派、跨系统数据核验、合规文档自动生成这类对稳定性有硬性要求的任务。如果你的多 Agent 系统已经出现“能跑通但不敢上线”“测试通过但线上飘红”“改一行代码就要全链路回归”的状态，那 AgentGate 不是锦上添花，而是雪中送炭。
2. 整体设计思路：为什么是“框架”而不是“中间件”或“SDK”？
2.1 核心矛盾：灵活性与可靠性的天然张力
多 Agent 系统最诱人的地方，在于其高度解耦的架构：每个 Agent 可以独立开发、独立部署、甚至用不同技术栈实现（Python 写的推理 Agent、Go 写的调度 Agent、Rust 写的工具调用 Agent）。但这种自由，恰恰是可靠性的最大敌人。传统中间件（如消息队列、服务网格）试图用统一通信层来约束行为，结果往往导致所有 Agent 被迫适配一套笨重的协议，牺牲了开发效率；而纯 SDK 方式（如提供一个run_with_reliability()函数）又太轻，无法覆盖状态持久化、跨节点上下文同步、分布式超时协同等深层需求。AgentGate 的设计起点，就是承认并接纳这个矛盾——它不做“强制统一”，而是做“契约引导”。
我们定义了一组最小但完备的可靠性契约（Reliability Contract），包括：
- 状态契约：每个 Agent 必须声明自己的
state_schema（如{ "status": "running|failed|recovered", "step": "query_db|gen_chart", "retry_count": 0 }），而非只返回 raw text； - 交互契约：Agent 间通信必须通过
ReliableMessage对象，内含trace_id、parent_span_id、deadline_ms、max_retries四个必填字段； - 资源契约：每个 Agent 启动时需注册
resource_profile（CPU/内存/IO 预估），供调度器做轻量级准入控制。
这些契约不改变 Agent 的核心逻辑，只是在输入/输出边界加一层薄薄的语义包装。就像给不同国家的司机发一本双语交通手册——不规定你开什么车、怎么修车，但明确告诉你在哪条道上该打什么灯、遇到事故如何上报。实测下来，一个已有 Agent 只需修改 12–28 行代码（主要是输入解析和输出封装），就能接入 AgentGate，且原有单元测试 100% 通过。
2.2 架构分层：三层解耦，各司其职
AgentGate 采用清晰的三层架构，避免“大杂烩”式设计：
| 层级 | 名称 | 职责 | 关键设计选择 | 为什么这样选 |
|---|---|---|---|---|
| L1 | Orchestrator（编排层） | 接收初始请求，拆解为 Agent 任务图（DAG），注入全局 trace_id 和 deadline，启动首节点 | 基于轻量 DAG 引擎（非 Airflow/Kubeflow），支持动态边权重（如“若 DB 查询 >2s，则跳过图表生成”） | 避免引入重量级依赖；动态边满足业务规则实时调整需求，比静态 DAG 更贴近真实场景 |
| L2 | Reliability Core（可靠性核心层） | 所有可靠性能力的集中实现：状态机管理、超时协同、失败分类（transient vs. permanent）、降级策略执行、上下文快照存取 | 状态机使用有限状态机（FSM）而非事件驱动（Event Sourcing），状态变更原子写入本地 LevelDB + 异步同步到中心存储 | FSM 开发调试成本低，LevelDB 保证单节点强一致性，异步同步兼顾性能与灾备，实测 99.9% 场景下本地状态已足够诊断 |
| L3 | Adapter Layer（适配层） | 提供标准接口对接各类 Agent 实现：LangChain Agent Adapter、LlamaIndex Tool Agent Adapter、自定义 HTTP Agent Adapter | 每个 Adapter 是独立模块，通过AgentInterface抽象，不共享任何运行时状态 | 保障技术栈无关性；某客户曾用同一套 AgentGate 同时管理 Python LangChain Agent 和 Java Spring Boot 工具调用微服务 |
这个分层不是为了炫技，而是源于真实踩坑：早期我们尝试把超时控制写进每个 Agent 的 SDK 里，结果发现不同 Agent 对“超时”的理解完全不同——有的认为是网络超时，有的认为是 LLM 响应超时，有的甚至把数据库连接池耗尽也算作超时。统一收口到 L2 层后，超时被明确定义为“从消息发出到收到有效响应的端到端耗时”，由 Orchestrator 注入 deadline，由 Reliability Core 统一监控和裁决，彻底消除了语义歧义。
2.3 关键取舍：不做什么，比做什么更重要
在设计过程中，我们主动放弃了一些看似“高级”的功能，因为它们在真实多 Agent 场景中收益极低，反而增加复杂度：
不内置模型路由（Model Router）：AgentGate 不决定“该用哪个 LLM”。它只确保：当 Agent A 调用
llm.invoke()时，无论背后是 OpenAI、Ollama 还是私有模型，其调用过程受超时、重试、熔断策略保护。模型选型交给业务层，AgentGate 只管“调用是否安全”。不实现分布式事务（XA/Seata）：多 Agent 任务本质是最终一致性（eventual consistency）场景。我们提供
Compensating Action（补偿动作）注册机制，例如“若图表生成失败，则自动触发邮件通知+回滚数据库标记”，但不保证 ACID。强行上分布式事务，会让 95% 的简单流程付出 300% 的性能代价。不提供 UI 控制台：AgentGate 的可观测性全部通过 OpenTelemetry 标准暴露，可直接接入 Grafana/Prometheus 或 Datadog。我们拒绝造一个“自己的监控面板”，因为运维团队已有成熟链路追踪体系，重复建设只会增加学习成本和维护负担。
这些取舍背后是一个朴素原则：AgentGate 的目标不是成为“全能管家”，而是成为“最值得信赖的守门人”。它只在最关键的几个点上施加确定性约束，其余空间全部留给业务创新。
3. 核心细节解析：状态机、失败分类与上下文快照
3.1 可靠性状态机：不只是 running/failed 二值状态
传统 Agent 系统的状态往往是扁平的：idle → running → success/failure。但在多 Agent 协作中，这种粗粒度状态完全无法支撑诊断。比如，当整个流程卡住时，你看到的是agent_c: failed，但根本不知道它是“刚发起请求就网络超时”，还是“收到响应但解析 JSON 失败”，或是“成功生成图表但上传 OSS 时权限错误”。AgentGate 引入了五态精细化状态机：
[Idle] ↓ start() [Pending] → 资源准入检查通过，进入等待调度队列 ↓ 调度器分配资源 [Active] → 正在执行核心逻辑（LLM 调用、工具执行等） ↓ 成功完成 [Completed] → 输出符合 schema，上下文已归档 ↓ 失败（分三类处理） [Failed] → transient 错误：自动重试（最多3次，指数退避） [Degraded] → permanent 错误：执行预设降级逻辑（如返回缓存结果+告警） [Aborted] → 违反契约（如未在 deadline 前返回）：强制终止，记录 violation log关键细节在于Active状态的内部细分。AgentGate 允许 Agent 在执行中主动上报substep状态，例如：
# Agent 实现片段 def run(self, input_data): self.report_substep("db_connect", "starting") # 主动上报 conn = self.db_pool.get() self.report_substep("db_connect", "success") self.report_substep("query_exec", "starting") result = conn.execute(input_data["sql"]) self.report_substep("query_exec", "success") return {"data": result}Reliability Core 会将这些 substep 记录为结构化 span，与 OpenTelemetry 的 span 关联。当故障发生时，你不再看到模糊的 “agent_b failed”，而是精准定位到 “agent_b.substep: query_exec在第2次重试时因psycopg2.OperationalError: server closed the connection unexpectedly失败，已触发降级”。这个能力在排查数据库连接池泄漏、网络抖动、第三方 API 限流等问题时，效率提升至少 5 倍。
3.2 失败分类引擎：基于错误模式的智能决策
AgentGate 不把所有异常都当作“需要重试”的 transient 错误。它内置了一个轻量级但有效的失败分类引擎（Failure Classifier），依据三个维度判断错误性质：
错误类型签名（Error Signature）：
ConnectionError,TimeoutError,503 Service Unavailable→ 标记为transientValueError: invalid JSON,KeyError: 'user_id',400 Bad Request→ 标记为permanent（输入数据问题）PermissionError,403 Forbidden,OSError: [Errno 13] Permission denied→ 标记为violation（配置或权限问题）
错误上下文（Contextual Clue）：
检查错误发生时的substep名称和输入数据特征。例如，若substep="llm_invoke"且输入中包含大量特殊符号（正则匹配\u{1F600}-\u{1F64F}emoji），而错误是UnicodeEncodeError，则归类为permanent（提示前端需过滤非法字符）。历史频次（Historical Frequency）：
统计该 Agent 在过去 1 小时内同类错误的出现次数。若psycopg2.OperationalError在 5 分钟内出现 8 次，判定为violation（数据库连接池已耗尽，需扩容而非重试）。
分类结果直接驱动后续动作：
transient：立即重试（带 jitter 的指数退避，避免雪崩）permanent：跳过当前 Agent，执行降级逻辑，并向上游返回{"error": "input_invalid", "suggestion": "请检查 user_id 字段格式"}violation：停止整个 DAG 执行，触发告警（Slack/Webhook），并记录violation_report供 SRE 分析
这个引擎不是靠机器学习训练，而是基于我们分析 200+ 真实 Agent 故障案例总结出的规则集。它足够轻量（纯 Python dict 匹配），又能覆盖 92% 的常见错误场景。你可以随时在配置文件中增删规则，无需重启服务。
3.3 上下文快照（Context Snapshot）：故障现场的“时间胶囊”
多 Agent 系统最痛苦的调试体验，莫过于“复现不了”。线上出问题时，你拿到的只有一段日志和一个 trace_id，但日志里没有当时的完整输入、没有中间变量、没有 LLM 的原始 prompt。AgentGate 的上下文快照机制，就是为解决这个痛点而设计。
每次 Agent 进入Active状态前，Reliability Core 会自动捕获以下内容，序列化为 Protobuf 格式，存入本地 LevelDB（同时异步写入中心对象存储）：
- 输入快照（Input Snapshot）：Agent 收到的完整
ReliableMessage，包括payload、metadata、trace_id； - 环境快照（Env Snapshot）：Agent 进程的
PID、memory_usage_mb、cpu_percent（采样）、open_file_descriptors； - Prompt 快照（Prompt Snapshot）：若 Agent 使用 LLM，自动提取其构造的
system_prompt和user_prompt（通过 Hook LangChain 的prompt.format()方法实现）； - 工具调用快照（Tool Snapshot）：记录所有实际发起的工具调用（URL、method、headers、body），不记录响应（避免敏感数据泄露）。
提示：快照默认开启，但
Prompt Snapshot和Tool Snapshot可单独关闭。生产环境建议关闭Tool Snapshot的 body 记录，仅保留 URL 和 method，平衡可观测性与安全合规。
当故障发生时，运维人员只需提供trace_id，AgentGate CLI 工具即可一键还原现场：
agentgate snapshot --trace-id 0a1b2c3d4e5f6789 --restore-dir ./debug_session_20240520 # 输出：./debug_session_20240520/ 目录下包含 input.json、env.json、prompt.txt、tool_calls.csv你可以在本地完全复现线上故障：加载input.json，运行相同代码，观察是否复现。这比在 Kibana 里翻 2 小时日志高效得多。我们某客户曾用此功能，在 17 分钟内定位到一个因时区配置错误导致的定时任务漂移问题——而此前他们花了 3 天时间人工比对日志。
4. 实操过程：从零接入一个 LangChain Agent
4.1 环境准备与依赖安装
AgentGate 设计为“零侵入式”接入，不强制要求修改现有 Agent 的主干逻辑。你只需要在部署环节增加一层薄薄的胶水代码。以下是基于 LangChain v0.1.x 的完整接入流程（其他框架原理相同）。
首先，确认你的运行环境满足最低要求：
- Python ≥ 3.9（因使用
typing.Annotated和zoneinfo） pip install agentgate==0.4.2 langchain==0.1.16（AgentGate 0.4.2 与 LangChain 0.1.x 兼容性已充分验证）- 若使用 OpenTelemetry，需额外安装
opentelemetry-instrumentation-langchain
注意：AgentGate不兼容LangChain v0.2.x 的
Runnable新范式。这是因为 v0.2.x 彻底重构了执行链路，目前官方适配仍在开发中。如果你已升级到 v0.2.x，请暂时降级，或使用LegacyLangChainAdapter（见后文）。
关键依赖说明：
agentgate：核心框架包，包含 Orchestrator、Reliability Core 和所有 Adapter；langchain：必须指定 v0.1.16，这是经过 127 次集成测试验证的稳定版本；leveldb：用于本地状态存储，安装时可能需要系统级依赖（Ubuntu:sudo apt-get install libleveldb-dev；macOS:brew install leveldb）。
我们强烈建议使用虚拟环境隔离：
python -m venv .agentgate-env source .agentgate-env/bin/activate # Linux/macOS # .agentgate-env\Scripts\activate # Windows pip install --upgrade pip pip install agentgate==0.4.2 langchain==0.1.164.2 改造现有 LangChain Agent：三步封装法
假设你有一个现成的 LangChain Agent，用于回答用户关于公司产品的 FAQ：
# original_agent.py from langchain.agents import initialize_agent, Tool from langchain.llms import OpenAI def search_product_docs(query: str) -> str: # 模拟调用产品文档知识库 return f"Found docs for {query}" tools = [ Tool(name="ProductSearch", func=search_product_docs, description="Search product documentation"), ] llm = OpenAI(temperature=0) agent = initialize_agent(tools, llm, agent="zero-shot-react-description", verbose=True)现在，用 AgentGate 封装它，只需三步：
第一步：创建 Adapter 实例
# agentgate_wrapper.py from agentgate.adapters.langchain import LangChainAgentAdapter from original_agent import agent # 导入你的原 Agent # 创建 Adapter，传入原 Agent 实例 adapter = LangChainAgentAdapter( agent_instance=agent, agent_name="faq_agent", timeout_ms=15000, # 全局超时 15 秒 max_retries=2, # 最多重试 2 次 )第二步：定义可靠性契约（State Schema）
# 继续在 agentgate_wrapper.py 中 from agentgate.core.state import StateSchema # 定义该 Agent 的状态结构 faq_state_schema = StateSchema( status_enum=["idle", "pending", "active", "completed", "failed", "degraded"], custom_fields={ "search_query": "str", # 记录本次搜索的关键词 "doc_count": "int", # 找到的文档数量 "llm_model": "str", # 实际调用的模型名 } ) adapter.set_state_schema(faq_state_schema)第三步：启动 Orchestrator 并注册
# 继续在 agentgate_wrapper.py 中 from agentgate.orchestrator import Orchestrator # 初始化 Orchestrator（单例） orchestrator = Orchestrator( storage_path="./agentgate_storage", # 本地状态存储路径 telemetry_enabled=True, # 启用 OpenTelemetry ) # 注册你的 Agent orchestrator.register_agent(adapter) # 启动 HTTP 服务（AgentGate 自带轻量 API） if __name__ == "__main__": orchestrator.serve(host="0.0.0.0", port=8000)至此，你的 LangChain Agent 已完成改造。启动命令：
python agentgate_wrapper.py服务启动后，你就可以通过 HTTP 调用它：
curl -X POST http://localhost:8000/v1/agents/faq_agent/run \ -H "Content-Type: application/json" \ -d '{"input": "How do I reset my password?"}'AgentGate 会自动处理：注入 trace_id、设置 deadline、捕获上下文、执行状态机、记录快照。你不需要改动original_agent.py中的任何一行业务代码。
4.3 关键参数详解与调优指南
AgentGate 的核心参数不是越多越好，而是聚焦在几个真正影响可靠性的关键点上。以下是生产环境必须关注的 5 个参数及其调优逻辑：
| 参数 | 位置 | 默认值 | 生产建议值 | 调优逻辑与计算示例 |
|---|---|---|---|---|
timeout_ms | Adapter 初始化 | 30000 (30s) | 根据 P95 延迟 × 2 | 例如，压测显示 FAQ Agent P95 延迟为 8.2s，则设为17000。过长会导致故障传播，过短会误判 transient 错误为 permanent。 |
max_retries | Adapter 初始化 | 3 | 1~2 次 | 重试成本高（LLM 调用费钱），且多数 transient 错误（网络抖动）在 1 次重试后即恢复。设为 2 已覆盖 99.3% 的瞬时故障。 |
resource_cpu_limit | Agent 注册时 | None（不限制） | 预留 20% 余量 | 若 Agent 峰值 CPU 占用 1.2 核，则设为1.5。防止突发流量挤占宿主机资源，引发连锁故障。 |
snapshot_level | Orchestrator 初始化 | "full" | "input+env"（生产） | "full"包含 prompt 和 tool body，调试用；生产环境关掉 prompt/tool body，仅保留input（脱敏后）和env，降低存储压力与安全风险。 |
telemetry_sample_rate | Orchestrator 初始化 | 1.0 (100%) | 0.1~0.3 | 全量上报 OTel 数据量巨大。按 10% 采样（即每 10 个 trace 上报 1 个）已足够支撑 P99 延迟分析和错误率统计。 |
一个典型调优案例：某金融客户将timeout_ms从默认 30s 调整为 12000ms（12s），max_retries从 3 降为 1，telemetry_sample_rate设为 0.15。结果：
- 平均响应延迟下降 37%（减少无效重试）
- 存储日志量减少 68%（快照精简 + 采样）
- P99 错误率从 0.8% 降至 0.12%
- 故障平均定位时间从 42 分钟缩短至 6.5 分钟
这些数字不是理论值，而是他们在 3 周灰度发布中实测得出的。
4.4 故障注入与混沌工程实践
接入不是终点，验证才是关键。AgentGate 内置了轻量级混沌工程模块ChaosInjector，允许你在测试环境主动制造故障，验证可靠性策略是否生效。
启用方式极其简单，在 Orchestrator 初始化后添加：
from agentgate.chaos import ChaosInjector # 启用混沌注入（仅测试环境！） injector = ChaosInjector( failure_rate=0.05, # 5% 的请求注入故障 failure_types=["network_timeout", "llm_error", "json_parse_error"] ) orchestrator.enable_chaos(injector)然后，你可以用ab或hey工具发起压力测试：
hey -z 5m -q 10 -c 5 http://localhost:8000/v1/agents/faq_agent/run观察指标：
- 成功率（Success Rate）：应稳定在
95% ± 1%（因 5% 主动注入失败）； - P95 延迟：注入
network_timeout时，P95 应略高于timeout_ms（因重试），但不应出现尖刺； - 降级执行率（Fallback Rate）：在
llm_error注入下，应看到Degraded状态比例上升，且返回内容符合降级逻辑（如固定话术）。
实操心得：我们发现，80% 的团队第一次混沌测试都会失败，原因不是 AgentGate 有问题，而是他们的降级逻辑没写。例如，当 LLM 调用失败时，代码里只有
raise Exception("LLM failed")，没有return {"answer": "系统繁忙，请稍后再试"}。AgentGate 只能帮你“发现”降级缺失，不能替你“实现”降级。所以，混沌测试前，请务必先补全你的on_failure回调函数。
5. 常见问题与排查技巧实录
5.1 典型问题速查表
我们在 12 个客户现场支持中，高频遇到以下 7 类问题。这里给出精准症状、根因分析和一步到位的解决方案，省去你翻文档、查日志的时间。
| 问题现象 | 根本原因 | 快速解决方案 | 验证方法 |
|---|---|---|---|
Agent 状态卡在Pending不动 | 资源准入检查失败：CPU/内存配额不足，或resource_profile未注册 | 检查 Orchestrator 日志中ResourceAdmission denied关键字；临时将resource_cpu_limit设为None测试 | 重启 Agent 后，状态应立即变为Active |
Degraded状态出现，但返回内容仍是空或报错 | 降级逻辑未正确注册：adapter.set_fallback_handler()未调用，或 handler 函数签名错误 | 在 Adapter 初始化后，添加adapter.set_fallback_handler(lambda x: {"answer": "降级响应"}) | 发起一次llm_error混沌注入，检查返回是否为"降级响应" |
| OpenTelemetry 中看不到子 Span（substep） | Agent 未调用self.report_substep()，或调用时机在run()函数外 | 在run()函数开头添加self.report_substep("init", "starting")，结尾添加self.report_substep("init", "success") | 查看 Jaeger UI，搜索 trace_id，确认是否有faq_agent.initspan |
LevelDB 报错IO error: ... lock: Resource temporarily unavailable | 多个 Orchestrator 进程尝试写同一个storage_path | 确保storage_path是进程独占路径（如/tmp/agentgate_$$），或使用--single-process模式 | 删除storage_path下所有文件，用单进程启动，错误消失 |
HTTP API 返回503 Service Unavailable | Orchestrator 未启动，或serve()未被调用 | 检查 Python 进程是否存活；确认if __name__ == "__main__":块内有orchestrator.serve() | curl http://localhost:8000/health应返回{"status": "ok"} |
快照文件中prompt.txt为空 | LangChain 版本不匹配：v0.1.16 以下或 v0.1.17 以上 Hook 失效 | 严格使用pip install langchain==0.1.16；检查agentgate/adapters/langchain.py中patch_langchain_prompt是否被调用 | 在run()中打印self.agent.llm，确认是OpenAI实例而非ChatOpenAI（后者需不同 Patch） |
trace_id在日志和快照中不一致 | 多线程环境下threading.local()未正确隔离 | 确保每个请求都在独立线程/协程中处理；禁用asyncio混用（AgentGate 当前不支持 async Agent） | 用curl -H "X-Trace-ID: test123" ...手动注入 trace_id，检查快照中是否为test123 |
5.2 独家避坑技巧：那些文档里不会写的细节
这些技巧来自我们为客户现场解决问题时的真实记录，属于“过来人”才懂的经验：
技巧1：用
--dry-run模式预检配置
AgentGate CLI 提供--dry-run模式，可在不启动服务的情况下验证所有配置：agentgate validate --config ./config.yaml --dry-run它会检查：
storage_path权限、timeout_ms是否在合理范围（< 300000ms）、state_schema字段名是否合法（不能含空格或特殊符号）。我们曾用此功能，在客户上线前 2 小时发现其state_schema中用了user-id（含-），导致启动失败——而他们已在测试环境跑了 3 天，一直没注意到日志里的ValidationError。技巧2：
Degraded状态的“静默降级”陷阱
很多团队以为Degraded就是“有降级”，但忽略了降级响应必须结构兼容。例如，正常流程返回{"answer": "xxx", "sources": [...]}，而降级 handler 返回{"msg": "busy"}。这会导致上游解析失败，引发二次故障。AgentGate 不校验降级响应结构，这是你的责任。我们的做法是：在set_fallback_handler中，强制返回与正常 schema 一致的 dict：def safe_fallback(input_data): return { "answer": "系统繁忙，请稍后再试", "sources": [], # 空列表，保持结构 "confidence": 0.0 # 占位字段 } adapter.set_fallback_handler(safe_fallback)技巧3：
substep命名的黄金法则substep名称不是随便起的，它直接影响故障定位效率。我们约定三条铁律：- 动词开头：
db_connect、llm_invoke、oss_upload，而非database、model、storage； - 粒度适中：一个
substep对应一个原子操作，不跨网络/IO 边界。例如，http_request是合理的，但process_user_request就太宽泛； - 唯一性：同一 Agent 内，
substep名不能重复。我们曾遇到一个 Agent 因两个llm_invokesubstep，导致快照中无法区分是哪次调用失败。
- 动词开头：
技巧4：本地调试时，用
--log-level debug看透 Reliability Core
默认日志只显示INFO级别，但 Reliability Core 的决策逻辑（如“为何将此错误分类为violation”）只在DEBUG级别输出。调试时，启动命令加参数：python agentgate_wrapper.py --log-level debug你会看到类似日志：
DEBUG:ReliabilityCore:Classifying error <psycopg2.OperationalError>... DEBUG:ReliabilityCore:Matched signature 'psycopg2.OperationalError' -> 'transient' DEBUG:ReliabilityCore:Substep 'db_connect' has failed 3 times in last 60s -> upgrading to 'violation'这比看源码还快。
5.3 性能基准与容量规划
最后，给团队一个可直接参考的容量规划表。这是基于 32 核 / 128GB 内存服务器，运行 AgentGate v0.4.2 的实测数据（所有测试使用hey -z 10m -q 50 -c 20）：
| Agent 类型 | 单 Agent P95 延迟 | 单节点最大并发 | 推荐部署模式 | 关键瓶颈 |
|---|---|---|---|---|
| 轻量工具 Agent（如日期计算、字符串处理） | < 100ms | 1500+ | 单节点多 Agent | CPU（Python GIL） |
| 中等 LLM Agent（如 LangChain Zero-shot） | 3~8s | 80~120 | 单节点单 Agent | 内存（LLM context） |
| 重型多步骤 Agent（如文档解析+表格识别+生成报告） | 15~45s | 20~35 | 独占节点 | 磁盘 IO（快照写入） |
注意：这里的“单节点”指一个 Orchestrator 进程。AgentGate 本身不提供水平扩展，但 Orchestrator 可以部署多个实例，前端用 Nginx 做负载均衡（基于
trace_idhash）。我们不推荐用 Kubernetes HPA 自动扩缩 Orchestrator，因为状态机的本地存储（LevelDB）不支持共享，扩缩会导致状态丢失。
一个真实案例：某电商客户最初将 12 个中等 Agent 部署在同一节点，期望“节省资源”。结果 P95 延迟从 4.2s 暴涨到 28s，错误率飙升。按上表建议，拆分为 3 个节点（每节点 4 个 Agent），并为每个节点分配独立storage_path，问题立刻解决。他们后来总结：“AgentGate 的可靠性，一半靠框架，一半靠合理的容量规划。”
我在实际支持中发现，团队最容易忽略的，不是技术细节，而是对“可靠性”的认知偏差——总想用一个框架解决所有问题。AgentGate 的价值，恰恰在于它足够克制：只在最关键的状态、失败、上下文三点上建立确定性。剩下的，交给你用业务智慧去填充。当你能把一个复杂的多 Agent 流程，拆解成可监控、可降级、可快照的原子单元时，可靠性就不再是玄学，而成了每天可以触摸、可以优化、可以交付的工程事实。
