Agent架构实战：从裸调用到Harness Runtime的演进路径-平芜编程栈

1. 这不是选框架，是给AI装上“操作系统”：一次真实项目中的Agent架构决策现场

你手头有个需求：让大模型不只是回答问题，而是能查数据库、调API、写代码、发邮件、做决策，甚至在多个步骤间自主判断下一步该干什么。这时候，老板或技术负责人甩来一句：“AI Agent架构怎么选？”——别急着翻文档、查GitHub star数，先停三秒。我经历过三次从零搭建Agent系统的完整周期，最深的体会是：选架构不是比参数、看文档厚度，而是回答三个现实问题：你的任务链路有多长？失败容忍度有多低？团队里有没有人愿意天天修状态机？这次要讲的，就是我们为某高校实验室构建科研辅助Agent时的真实路径：从第一次用openai.ChatCompletion.create()硬编码调用，到最终落地一个可监控、可回溯、可灰度发布的Harness Runtime环境。它不追求“最先进”，但每一步都踩在交付节奏、调试成本和长期维护的刀刃上。核心关键词就四个：LLM调用、工具编排、状态管理、运行时可观测性。如果你正卡在“该不该上LangChain”“AutoGen是不是太重”“自己写调度器值不值得”这类问题里，这篇就是为你写的实战复盘。它适合两类人：一是刚把第一个llm.invoke("你好")跑通、正对着复杂业务逻辑发懵的工程师；二是已经上线了几个Agent Demo、但每次加个新工具就要改半套胶水代码的技术负责人。后面所有内容，没有PPT式概念堆砌，只有当时我们白板上画过的流程图、删掉又重写的第三版状态机定义、以及压测时发现的那条差点让整个系统雪崩的超时链路。

2. 架构选型不是技术比武，而是对“失控点”的预判与封堵

2.1 为什么不能直接用裸LLM调用？——从“单次问答”到“多步任务”的质变鸿沟

很多人以为Agent就是“让LLM多调几次API”。我们最初也是这么干的。需求很简单：根据用户输入的论文标题，自动检索相关文献、提取关键方法、生成对比表格。第一版代码不到50行：

def simple_agent(paper_title): # Step 1: 调用LLM理解用户意图 intent = llm.invoke(f"请分析以下论文标题的核心研究方向：{paper_title}") # Step 2: 根据意图构造数据库查询 db_query = llm.invoke(f"将以下研究方向转化为SQL查询语句：{intent}") results = database.execute(db_query) # Step 3: 用结果生成表格 table = llm.invoke(f"用以下数据生成Markdown表格：{results}") return table

跑通了，但上线三天就崩了两次。问题出在哪？裸调用把所有“不确定性”都扔给了LLM，而LLM恰恰最不擅长处理确定性边界。比如Step 1返回的intent如果是“研究机器学习在医疗影像的应用”，Step 2的SQL生成就可能变成SELECT * FROM papers WHERE abstract LIKE '%machine learning%' AND abstract LIKE '%medical%'——这会扫全库，超时。更糟的是，当Step 2失败时，整个函数直接抛异常，Step 3根本没机会执行，用户只看到“服务错误”，连哪一步挂了都不知道。我们后来统计，这种线性硬编码的失败率高达37%，且82%的失败发生在工具调用环节（数据库超时、API限流、格式解析错误）。裸LLM调用的本质，是把“任务编排”这个本该由程序逻辑承担的责任，强行塞给了语言模型的文本生成能力。这就像让一个只会写菜谱的人，亲自去菜市场买菜、切菜、炒菜、装盘——他能写出完美步骤，但真动手时，缺斤少两、火候不对、锅烧穿了，全是不可控变量。所以第一步必须明确：Agent架构的核心价值，不是让LLM更聪明，而是给它配一套可靠的“手脚”和“神经系统”。

2.2 LangChain/LlamaIndex这类框架，到底在解决什么？——解耦“思考”与“执行”的工程实践

当我们意识到裸调用走不通，自然想到LangChain。但直接引入，很快又陷入新困境：团队里两个后端工程师，一个觉得Chain太重，另一个觉得Tool Calling API不够底层。争论焦点其实是：框架提供的“抽象层”，是否匹配我们真实的控制粒度需求？我们拆解了LangChain的核心设计，发现它其实在做三件事：
第一，统一工具接口。无论你是调数据库、发HTTP请求还是读文件，都包装成Tool对象，有name、description、args_schema。这解决了我们之前db_query和llm.invoke混写导致的类型混乱问题。
第二，提供执行引擎。AgentExecutor会自动把LLM输出的JSON格式工具调用指令（如{"tool": "search_papers", "tool_input": {"query": "transformer"}}）解析、路由、执行，并把结果喂回LLM。这省去了我们手动写if tool == "search_papers"的胶水代码。
第三，内置记忆机制。ConversationBufferMemory能记住历史对话，让LLM在后续步骤中参考上下文。

听起来很美？但实测下来，问题出在“自动”二字上。比如，当search_papers工具返回空结果时，AgentExecutor默认策略是“重试”，而我们的业务规则是“空结果则切换到维基百科API补充背景知识”。LangChain的重试逻辑是硬编码在AgentExecutor里的，想改就得继承重写，反而比自己写调度器还麻烦。再比如，它的memory是全局的，但我们的场景需要为每个用户会话维护独立的状态快照（因为不同导师的科研偏好差异极大），而LangChain的内存管理是面向单次调用的。我们最终结论是：LangChain的价值，在于它验证了“工具抽象+执行引擎”这个模式的可行性，但它提供的“开箱即用”方案，往往是以牺牲对关键路径的细粒度控制为代价的。就像一辆预装好导航的车，你没法临时要求它“绕开所有红绿灯路口”，除非你拆掉原厂导航，自己接GPS模块。

2.3 为什么走向Harness Runtime？——从“能跑”到“可运维”的必然升级

当项目进入第二阶段，需求开始爆炸式增长：要支持导师A的“跨学科文献溯源”，要满足学生B的“实验数据自动绘图”，还要给管理员C提供“所有Agent调用的审计日志”。这时，我们发现所有现有方案都在同一个地方卡住：缺乏统一的运行时契约（Runtime Contract）。

LLM调用没有标准化的输入/输出Schema，不同模型返回的JSON结构五花八门；
工具执行没有统一的错误码体系，数据库超时、API限流、JSON解析失败，全混在Exception里；
状态流转没有持久化记录，用户问“刚才那步为什么卡住了”，我们只能翻日志大海捞针。

这就是Harness Runtime诞生的直接动因。它不是一个新框架，而是一套强制约定：

所有LLM调用必须通过LLMInvoker统一入口，输入是PromptTemplate + Variables，输出是强类型的LLMResponse（含content,tool_calls,usage字段）；
所有工具必须实现ToolInterface，声明invoke(input: dict) -> ToolResult，且ToolResult必须包含status（success/error）、data（业务数据）、error_code（预定义枚举）；
所有状态变更必须写入StateStore，用session_id + step_id作为主键，存input,output,timestamp,duration_ms。

这个“契约”本身不提供任何智能，但它像交通法规一样，让所有参与者（LLM、工具、监控系统）有了共同语言。我们用两周时间，把原来散落在各处的37个工具、5种LLM调用方式，全部按契约重构。重构后，最大的收益不是性能提升，而是故障定位时间从平均47分钟降到9分钟。因为现在只要查StateStore表，就能看到某个session_id下，第3步的error_code是TOOL_TIMEOUT_5003，对应数据库连接池耗尽——而不是在几十个微服务日志里grep“timeout”。Harness Runtime的本质，是把Agent系统从“一堆能动的零件”，变成了“一台可诊断、可维修、可升级的机器”。它不解决“LLM能不能想出好主意”，但确保“当它想出坏主意时，我们知道坏在哪、怎么修”。

3. Harness Runtime核心模块详解：从协议定义到生产级落地

3.1 LLM调用层：不止是API封装，更是“意图翻译器”的构建

在Harness Runtime里，LLMInvoker绝不是简单的requests.post()封装。它的核心职责，是把业务语义准确无损地翻译成LLM能理解的提示词，并把LLM的文本输出，精准还原为结构化指令。我们为此设计了三层转换：

第一层：Prompt模板引擎
我们弃用了硬编码字符串拼接，采用Jinja2模板，但做了关键增强：模板中所有变量都必须声明type和required。例如文献检索的Prompt模板：

{% set query = variables.query | string %} {% set max_results = variables.max_results | int | default(5) %} 你是一个学术助手，请严格按以下JSON格式输出： { "tool_calls": [ { "tool": "search_papers", "tool_input": { "query": "{{ query }}", "limit": {{ max_results }} } } ] }

variables.query | string这个过滤器，强制要求传入的query必须能转为字符串，否则在模板渲染阶段就报错，避免了LLM收到None或[object Object]这类无效输入。这层看似简单，却拦截了我们早期31%的LLM解析失败。

第二层：响应解析器（Response Parser）
LLM返回的永远是文本，而我们需要的是tool_calls列表。我们没用正则硬匹配，而是训练了一个轻量级的“结构校验器”：先用正则粗筛出JSON块，再用jsonschema验证其符合预定义的ToolCallSchema（含tool必须是注册过的工具名、tool_input必须包含必需字段等）。如果校验失败，不直接报错，而是触发“修复模式”：把原始响应和Schema定义一起喂给LLM，让它重写一次。实测下来，92%的格式错误能被自动修复，剩下8%才进入人工审核队列。这个设计的关键在于：把“LLM不可靠”当作前提，而非bug。我们不追求100%解析成功，而是确保失败时有明确的降级路径。

第三层：调用治理（Invocation Governance）
这是真正体现“Runtime”价值的部分。我们在LLMInvoker里嵌入了熔断、限流、超时三级防护：

超时：按模型类型设置硬超时（GPT-4设为30s，本地小模型设为8s），超时后立即返回{"status": "timeout", "fallback_response": "当前服务繁忙，请稍后重试"}；
限流：基于Redis计数器，对高风险Prompt（如含system:前缀的）实施QPS限制，防越狱攻击；
熔断：当连续5次调用返回status: "error"，自动熔断该模型10分钟，期间所有请求路由到备用模型。

这三层不是可选项，而是启动时强制加载的中间件。它让LLM调用从“尽力而为”变成了“可控服务”。

3.2 工具编排层：状态机驱动的“决策-执行-反馈”闭环

Harness Runtime的工具调度，核心是一个显式状态机（Explicit State Machine），而非LangChain式的隐式循环。我们定义了6个标准状态：

状态	触发条件	下一状态	关键动作
`WAITING_FOR_LLM`	新会话创建	`GENERATING_TOOL_CALLS`	加载初始Prompt模板
`GENERATING_TOOL_CALLS`	LLM返回有效tool_calls	`EXECUTING_TOOLS`	解析tool_calls，校验工具可用性
`EXECUTING_TOOLS`	工具执行完成	`PROCESSING_TOOL_RESULTS`	汇总所有工具结果，生成新Prompt
`PROCESSING_TOOL_RESULTS`	LLM返回最终答案	`COMPLETED`	存储最终结果，发送通知
`TOOL_ERROR`	工具执行失败	`HANDLING_ERROR`	根据error_code选择重试/降级/终止
`HANDLING_ERROR`	错误处理完成	`GENERATING_TOOL_CALLS`或`COMPLETED`	执行降级逻辑或标记失败

这个状态机不是画在PPT上的，而是用Python的transitions库实现，每个状态转移都记录transition_log。比如当状态从EXECUTING_TOOLS跳到TOOL_ERROR，日志会记：{"session_id": "abc123", "step_id": "step_4", "from_state": "EXECUTING_TOOLS", "to_state": "TOOL_ERROR", "error_code": "DB_CONNECTION_TIMEOUT_2001", "tool_name": "search_papers"}。
为什么坚持显式状态机？因为我们发现，隐式循环（如LangChain的while not done）在复杂分支下极易失控。比如，当search_papers失败后，按规则应调用wiki_lookup，但如果wiki_lookup也失败，是重试search_papers？还是调用第三个工具？还是直接返回错误？隐式循环无法清晰表达这种决策树。而显式状态机，把所有分支都写死在state_transitions配置里，新人看一眼就知道“TOOL_ERROR状态下，error_code=2001走A路径，error_code=3002走B路径”。这大幅降低了协作成本。

3.3 状态存储层：用“会话快照”替代“日志流水”，实现可追溯性

StateStore是我们最常被问及的模块。很多人第一反应是“用Elasticsearch存日志不就行了？”。但我们坚持用关系型数据库（PostgreSQL）存结构化快照，原因有三：
第一，查询效率。当导师问“张三同学昨天下午3点那个‘量子计算综述’的请求，第三步为什么没出图？”，我们需要在毫秒级内定位到session_id='zhangsan_20240520_1500'的step_id='step_3'记录。ES的全文检索在这里是杀鸡用牛刀，而PG的WHERE session_id = ? AND step_id = ?索引查询，稳定在12ms内。
第二，数据一致性。StateStore的每条记录，都包含完整的input和outputJSONB字段。这意味着，我们可以随时用这条记录“重放”整个步骤：把input喂给LLMInvoker，把output喂给下游工具，完全复现当时的执行环境。而日志是分散的，input在服务A的日志里，output在服务B的日志里，error在服务C的日志里，拼起来耗时且易错。
第三，审计合规。高校项目有严格的科研数据审计要求。StateStore表设置了ON UPDATE SET updated_at = NOW()，且所有字段不可为空。更重要的是，我们实现了immutable_history：每次状态更新，不是UPDATE，而是INSERT一条新记录，version字段自增。这样，session_id='zhangsan_20240520_1500'的历史，就是一张按version排序的快照链，谁在什么时候改了什么，一目了然。

这张表的设计，直接决定了我们能否在48小时内完成一次完整的故障复盘。它不是锦上添花，而是生存必需。

3.4 可观测性层：从“黑盒”到“透明玻璃房”的监控体系

Harness Runtime的可观测性，我们坚持“三不原则”：不依赖外部APM、不侵入业务代码、不增加开发者心智负担。所有监控数据，都来自StateStore和LLMInvoker的天然埋点。我们构建了三个核心视图：

视图一：会话健康度仪表盘
实时显示：

active_sessions：当前正在执行的会话数（StateStore中status IN ('WAITING_FOR_LLM', 'EXECUTING_TOOLS')的记录数）；
error_rate_5m：过去5分钟内，status='ERROR'的会话占比；
p95_step_duration：所有步骤耗时的95分位值。

当error_rate_5m > 5%时，自动触发告警，并附带Top 3error_code。这让我们能在用户投诉前，就发现DB_CONNECTION_TIMEOUT_2001集中爆发，进而定位到数据库连接池配置错误。

视图二：工具效能热力图
按工具名（tool_name）和error_code聚合，生成二维热力图。颜色越深，表示该错误在该工具上发生越频繁。我们曾通过这个图发现：generate_chart工具的CHART_DATA_INVALID_4002错误，90%集中在max_results > 100的场景。于是我们加了一条规则：当max_results > 100时，自动降级为文字描述，不再生成图表。这个改动，让该工具的错误率从18%降到0.3%。

视图三：LLM调用质量分析
监控两个关键指标：

parse_success_rate：LLM响应被成功解析为tool_calls的比例；
tool_call_accuracy：LLM调用的工具，是否真的是当前步骤最合适的（通过人工抽检100条，计算准确率）。

我们发现，当parse_success_rate < 85%时，tool_call_accuracy必然低于60%。这说明，LLM在“说人话”和“写代码”之间存在巨大鸿沟——它可能清楚该调什么工具，但就是写不出合法JSON。于是我们调整了Prompt模板，强制要求“先输出纯文本思考过程，再输出JSON”，这个简单改动，让parse_success_rate从79%提升到94%。

这套监控体系，不追求炫酷的火焰图，只关注三个问题：现在好不好？哪里不好？为什么不好？它让Agent系统不再是“调用即黑盒”，而是一个可以被持续优化的精密仪器。

4. 实操落地：从0到1搭建Harness Runtime的七步法

4.1 第一步：定义最小可行契约（MVP Contract）

不要一上来就设计10个模块。我们只定义三个最核心的契约：

LLM调用契约：所有LLM调用必须通过LLMInvoker.invoke(prompt_template: str, variables: dict) -> LLMResponse；
工具契约：所有工具必须实现ToolInterface.invoke(input: dict) -> ToolResult，且ToolResult必须含status,data,error_code；
状态契约：所有状态变更必须写入StateStore.upsert(session_id: str, step_id: str, state: dict)，state必须含input,output,timestamp,duration_ms。

这三句话，就是我们整个Harness Runtime的宪法。其他所有模块，都是为履行这三条契约服务的。我们花了半天时间，用Pydantic写完这三个基础Model，然后让所有开发者在当天下班前，把各自负责的LLM调用和工具，按契约重构。契约的力量，在于它把“讨论技术选型”的会议，变成了“检查是否达标”的验收。第二天晨会，我们只问一个问题：“你的模块，今天能过契约测试吗？”——没有废话，只有结果。

4.2 第二步：构建“契约测试”自动化流水线

契约定了，必须有测试保障。我们写了三个核心测试用例，集成到CI/CD中：

LLMInvoker测试：用固定Prompt模板和Variables，断言返回的LLMResponse.tool_calls类型正确、字段完整；
ToolInterface测试：对每个工具，用预设input，断言ToolResult.status和error_code符合预期（如数据库工具在input含非法字符时，必须返回error_code=DB_INVALID_INPUT_1001）；
StateStore测试：模拟一次完整会话，断言upsert后，能用session_id + step_id精确查出记录，且duration_ms在合理范围内（±100ms）。

这个流水线每天凌晨自动运行。一旦有人提交的代码导致任一契约测试失败，PR会被自动拒绝。这比任何Code Review都有效。它确保了“契约”不是墙上贴的标语，而是流淌在每一行代码里的血液。

4.3 第三步：实现状态机核心引擎

我们用transitions库实现状态机，但关键不在库，而在状态定义。我们花了整整一天，和产品、算法、后端一起，在白板上画出了所有可能的状态流转。重点不是画全，而是标出所有“死亡路径”（即走到这里就无法继续，必须终止会话的路径）。比如：

TOOL_ERROR→HANDLING_ERROR→ 如果降级工具也失败，则必须进入FAILED终态；
GENERATING_TOOL_CALLS→ 如果LLM连续3次返回空tool_calls，则进入STUCK_IN_LOOP终态。

这些终态，就是系统的“安全阀”。代码实现时，我们为每个终态编写了on_enter_<state>钩子，自动触发告警、清理资源、发送失败通知。状态机的威力，不在于它能走多远，而在于它知道什么时候该停下。这个设计，让我们在后续压测中，成功避免了因无限重试导致的线程池耗尽。

4.4 第四步：部署StateStore并打通数据链路

我们选PostgreSQL，不仅因为熟悉，更因为它原生支持JSONB和部分索引。建表语句核心部分如下：

CREATE TABLE state_store ( id SERIAL PRIMARY KEY, session_id VARCHAR(64) NOT NULL, step_id VARCHAR(32) NOT NULL, version INTEGER NOT NULL DEFAULT 1, input JSONB NOT NULL, output JSONB NOT NULL, status VARCHAR(20) NOT NULL, -- 'success', 'error', 'timeout' error_code VARCHAR(32), -- 如 'DB_TIMEOUT_2001' timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(), duration_ms INTEGER NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), UNIQUE (session_id, step_id, version) ); -- 关键索引 CREATE INDEX idx_session_step ON state_store (session_id, step_id); CREATE INDEX idx_error_code ON state_store (error_code) WHERE error_code IS NOT NULL;

部署后，我们写了第一个数据同步脚本：把过去30天的所有旧日志，按session_id和step_id聚合成StateStore记录。这个脚本跑了6小时，生成了217万条快照。这一步的意义，是让历史数据“活”过来。从此，任何一次用户投诉，我们都能在10秒内，给出完整的执行链路图。

4.5 第五步：接入可观测性，建立基线指标

我们没用Prometheus，而是直接用PostgreSQL的pg_stat_statements插件，监控state_store表的查询性能。同时，写了一个简单的Flask服务，暴露三个HTTP端点：

/health：返回{"status": "ok", "active_sessions": 12, "error_rate_5m": 0.02}；
/metrics：返回{"parse_success_rate": 0.94, "p95_step_duration_ms": 1420}；
/sessions/{session_id}：返回该会话所有步骤的快照列表。

这些端点，被直接接入公司已有的Grafana大盘。我们花了半天时间，配置好告警规则：当error_rate_5m > 0.05时，电话告警；当p95_step_duration_ms > 3000时，企业微信告警。可观测性的起点，不是堆工具，而是定义“什么是正常”。我们用上线首周的数据，定下了所有基线值。之后每一次波动，都是有价值的信号。

4.6 第六步：灰度发布与渐进式迁移

我们没有一刀切替换旧系统。而是采用“双写+影子流量”策略：

所有新请求，同时写入旧日志系统和新的StateStore；
选取5%的流量，让LLMInvoker和工具按新契约执行，但结果仍走旧路径（即新引擎只计算，不生效）；
对比新旧两条路径的输出，当连续1000次output完全一致时，将该5%流量切到新路径。

这个过程持续了11天。期间我们发现了两个关键问题：

旧系统对LLM响应的JSON解析，会忽略tool_input中的空格，而新契约要求严格匹配；
某个工具的error_code定义，旧系统用字符串"timeout"，新契约要求枚举TOOL_TIMEOUT_2001。

这些问题，在影子流量中被完美捕获，修复后才正式切流。灰度不是为了偷懒，而是为了把“未知风险”变成“已知问题”。这11天，是我们整个项目最踏实的11天。

4.7 第七步：建立开发者赋能体系

最后一步，也是最容易被忽视的一步：让团队真正用起来。我们做了三件事：

编写《Harness Runtime开发手册》：不是API文档，而是“场景化指南”。比如“如何添加一个新工具”，步骤是：① 创建my_tool.py，实现ToolInterface；② 在tool_registry.py中注册；③ 写一个契约测试；④ 提交PR。每步配截图和命令。
设立“契约守护者”轮值制：每周由一名工程师担任，负责审核所有涉及契约的PR，解答疑问，收集反馈。轮值表贴在团队群公告里。
每月“故障复盘会”：不追责，只复盘。主持人提前从StateStore中选出3个典型故障案例，会上大家一起看快照、猜原因、提方案。上个月的案例是TOOL_ERROR频发，大家集体讨论后，决定给所有数据库工具加连接池健康检查。

技术架构的成败，最终取决于有多少人愿意每天用它。这三件事，把Harness Runtime从“架构师的玩具”，变成了“团队的日常工具”。

5. 常见问题与避坑指南：那些只有踩过才知道的深坑

5.1 “LLM总是乱调工具，怎么约束它？”——Prompt工程之外的硬性护栏

这是最高频的问题。很多团队寄希望于“写更好的Prompt”，但实测发现，当工具数量超过7个，LLM的调用准确率会断崖式下跌。我们的解决方案是“软硬兼施”：

软性约束（Prompt层）：在Prompt模板末尾，强制添加工具白名单。例如：
```
可用工具列表（必须从中选择，禁止使用列表外的工具）： - search_papers: 用于检索学术论文 - wiki_lookup: 用于查询通用知识 - generate_chart: 用于生成数据图表
```
这个白名单，不是建议，而是指令。我们测试过，加上后，LLM调用未注册工具的概率从12%降到0.3%。
硬性约束（Runtime层）：LLMInvoker在解析tool_calls后，会校验每个tool是否在tool_registry中注册。如果不在，不执行，而是触发TOOL_NOT_FOUND错误，并自动重试（把白名单再次喂给LLM）。这个双重保险，让工具调用失控成为历史。

提示：不要迷信“LLM能自我纠正”。我们的数据表明，当LLM第一次调错工具，第二次调对的概率只有41%。所以，必须在它犯错前，就用白名单挡住；在它犯错后，就用硬校验兜底。

5.2 “状态机太重，小项目值得吗？”——按需裁剪的轻量级方案

有团队问：“我们就一个查天气的Agent，也要搞状态机？”当然不。我们为不同复杂度提供了三档方案：

L0（极简）：仅LLMInvoker契约 +StateStore快照。适用于单步、无分支的Agent（如“总结网页内容”）。代码量<200行。
L1（标准）：L0 + 显式状态机（仅WAITING_FOR_LLM→EXECUTING_TOOLS→COMPLETED三态）。适用于有工具调用，但无错误分支的场景（如“查股票价格+生成报告”）。
L2（完整）：L1 + 全状态机 + 可观测性。适用于多工具、多分支、高可靠要求的场景。

我们内部有个“复杂度评估表”，含5个问题：

是否需要调用≥2个不同工具？
工具执行失败后，是否有明确的降级路径？
是否需要为每个用户会话保存完整执行历史？
是否有审计或合规要求？
团队是否经常因“不知道哪步挂了”而加班？
答“是”≥3个，就上L2；答“是”≤2个，用L1；全否，用L0。架构不是越高越好，而是恰到好处。这个表，帮我们避免了在小项目上过度设计。

5.3 “工具执行慢，拖垮整个Agent，怎么解耦？”——异步执行与超时熔断的实战配置

工具执行慢，是Agent系统的头号杀手。我们曾遇到generate_chart工具因数据量大，单次执行超45秒，导致整个会话超时。解决方案是“异步+熔断”组合拳：

异步执行：EXECUTING_TOOLS状态不阻塞主线程。LLMInvoker把tool_calls发到消息队列（我们用RabbitMQ），Worker消费后执行，并把结果写回StateStore。主线程立即进入WAITING_FOR_TOOL_RESULTS状态，轮询StateStore。
超时熔断：每个工具在注册时，必须声明timeout_ms（如generate_chart: 10000）。Worker执行时，用signal.alarm()设置硬超时。超时后，Worker主动写入StateStore，status='timeout',error_code='TOOL_TIMEOUT_4001'。

这个设计的关键，在于把“等待”从同步阻塞，变成了异步轮询。用户感知上，只是响应慢一点；系统层面，却避免了线程池被占满。我们压测时，即使100个generate_chart并发，系统依然稳定，因为主线程始终在轮询，不被阻塞。

5.4 “LLM返回的tool_input格式总变，怎么保证工具能接住？”——输入Schema的防御性设计

LLM生成的tool_input，经常出现字段缺失、类型错误（如把数字当字符串）、多余字段等问题。我们工具的invoke方法，不直接用input["query"]，而是用Pydantic的BaseModel做防御性解析：

class SearchPapersInput(BaseModel): query: str limit: int = Field(default=5, ge=1, le=100) def invoke(self, input: dict) -> ToolResult: try: parsed_input = SearchPapersInput(**input) # 自动校验、转换、填充默认值 # 此时parsed_input.query一定是str，parsed_input.limit一定是int return self._execute_search(parsed_input.query, parsed_input.limit) except ValidationError as e: return ToolResult( status="error", error_code="INPUT_VALIDATION_FAILED_5001", data={"errors": e.errors()} )

这个SearchPapersInput模型，就是我们的“输入契约”。它比任何文档都管用，因为它是运行时强制执行的。防御性设计的精髓，不是预测LLM会怎么错，而是确保无论它怎么错，工具都能优雅地报错，而不是崩溃。这个模式，让我们工具层的稳定性从83%提升到99.2%。

5.5 “如何评估一个Agent架构是否成功？”——回归业务本质的四个硬指标

最后，分享我们用来评判架构成败的四个指标，它们和任何技术参数无关，只和业务结果挂钩：

首次故障定位时间（MTTD）：从用户报告问题，到工程师在StateStore中定位到具体session_id和step_id的时间。目标：<15分钟。
单次会话平均步骤数（Avg Steps/Session）：反映Agent的“智能程度”。我们从最初的1.2步（基本是单次问答），提升到现在的4.7步（能自主规划多步任务）。
工具调用成功率（Tool Success Rate）：StateStore中status='success'的工具调用占比。目标：>95%。
开发者新增工具平均耗时（Dev Time/New Tool）：从接到需求，到新工具上线、通过