这次我们聊的不是某个图形界面工具也不是某个模型权重而是 Linear 团队沉淀下来的一套 Agent 工程方法论构建生产级别 Agent 的 5 条规则。先直接说结论当前很多 Agent 项目能跑通 Demo但一旦进入生产环境就暴露问题——不可控、不可观测、不可回滚、不能评估。Linear 这套规则的价值在于它把 Agent 从“能聊天的玩具”拉回“有边界的工程系统”用显式建模、状态管理、可观测性、失败兜底和回归评估来约束 LLM 的不确定性。这篇文章会把这 5 条规则拆开讲清楚并给出每一条落地时需要的工程配置、代码模板、验证方式和排查思路。适合正在做 Agent 应用开发、想把智能体接到真实业务里、或者准备从单轮 Demo 走向多轮任务编排的读者。如果你只关心提示词怎么写这篇文章帮助有限如果你想的是“怎么让 Agent 稳定输出、出错了怎么定位、上线了怎么评估”可以直接收藏。1. 方法论核心速览能力项说明适用对象使用 LLM API 搭建任务型 Agent 的工程团队也适用于个人开发者落地小规模智能体服务核心目标让 Agent 在真实业务中可控、可观测、可评估、可回滚核心模块意图解析、状态机、工具调度、可观测日志、失败兜底、回归评估集工程要求需要状态存储、日志系统、任务队列、接口封装不依赖特定模型厂商支持平台只要能用 Python/Node 调 LLM API就能按这套规则落地是否开源方法论本身不依赖特定 GitHub 仓库具体实现需基于团队现有代码库集成批量任务规则四和规则九章节会给出任务队列与批量调度的设计思路接口能力通过显式 API 封装 Agent 动作便于第三方系统接入适合场景客服工单处理、数据分析助手、代码审查助手、自动化运维、内部知识库问答这张表没有列出“显存占用”和“GPU 依赖”因为这套方法论属于工程架构层而不是模型推理层。你在落地时仍然可以使用云端 LLM API也可以本地化部署模型两者并不冲突。2. 适用场景与使用边界先明确这套方法论适合什么场景。生产级 Agent 通常具备三个特征任务目标明确而不是开放式闲聊。需要调用外部工具或系统例如查数据库、发通知、改工单状态。输出会影响真实业务所以不允许“随便答”。典型场景包括客服自动应答Agent 读取用户工单调用知识库检索最后生成回复草稿。数据分析助手Agent 根据自然语言生成查询语句执行查询返回结构化结果。运维辅助Agent 解析日志识别异常调用脚本完成初步处置。内容生产辅助Agent 按流程完成多步骤文本处理并通过人工审核后发布。不适合什么场景第一种是开放式闲聊型产品这类产品追求发散性不需要强约束套这套规则反而限制体验。第二种是高风险决策场景例如医疗诊断、法律意见、金融自动交易在没有人工复核和完整合规评估之前任何规则都不能替代责任边界。合规边界要注意如果 Agent 会处理用户隐私数据必须在设计阶段就明确数据脱敏范围如果 Agent 会调用第三方系统写操作必须预留审批节点如果 Agent 会生成面向公众的内容必须有审核流程。不能因为“模型能输出”就觉得“可以自动发布”。3. 生产级 Agent 的工程化前置条件在讨论 5 条规则之前先确认工程前置条件。这不是代码层面的依赖而是架构层面的“地基”。3.1 显式状态存储生产级 Agent 不能把所有上下文都塞在 Prompt 里。多轮任务中每一步的输入、输出、中间结果都应该有明确的存储位置。推荐最小方案- task_id: 任务唯一 ID - status: pending / running / waiting_tool / success / failed / needs_review - input_payload: 用户输入 - step_history: 每个 Agent 动作的记录 - tool_results: 工具调用结果 - final_output: 最终输出不要用“全局变量 内存”的方式管理 Agent 状态。一旦服务重启、进程崩溃或并发请求增加状态丢失会造成任务不可恢复。3.2 结构化日志Debug 一个生产级 Agent最大的问题是“不知道它中间做了什么”。所以从第一版开始就要输出结构化日志。一个最小日志字段建议{ timestamp: 2026-01-01T10:00:00Z, task_id: task_001, step: intent_parsing, model: gpt-4o, prompt_version: v3, input_preview: 用户原始输入前200字, output_preview: 模型输出前200字, latency_ms: 830, token_usage: { prompt_tokens: 1200, completion_tokens: 300, total_tokens: 1500 } }这个日志文件会在规则三“可观测性”里发挥关键作用。3.3 任务队列如果 Agent 会被多个用户同时调用建议在 Agent 前面加一层任务队列而不是让每个 HTTP 请求直接创建一个 Agent 实例。任务队列的好处是控制并发、失败重试、限流、追踪。批量任务场景下队列几乎是必须的。3.4 工具接口封装Agent 要调用的外部工具不要直接给模型裸 SQL、裸 Shell、裸 API。先把工具封装成“有明确输入输出格式的 Function”模型只负责生成符合 JSON Schema 的参数真正的执行权留在受控的服务里。4. 规则一意图解析与任务边界的显式建模第一条规则是先定义 Agent 能做什么再让模型决定做什么。很多 Agent Demo 翻车不是因为模型能力不够而是因为“边界”没有定义。4.1 先枚举任务类型在生产环境里Agent 能处理的任务应该是有限集合。比如cancel_order取消订单modify_shipping修改收货地址query_order_status查询订单状态refund_apply申请退款escalate_to_human转人工把这些任务定义成枚举然后在 Prompt 或函数调用定义里约束模型只能从这里面选。不要开放“根据用户意思随便做”。4.2 用结构化字段承载用户意图不建议把“意图解析结果”直接用自然语言文本传给后续流程而是转成结构化数据。# 意图解析结果示例 { intent: cancel_order, confidence: 0.92, entities: { order_id: NO20260101123456, reason: 不想要了 }, raw_input: 我要取消订单 NO20260101123456东西不想要了 }后续步骤只需要读这个结构化对象不再重新解析用户原文。这样做的好处是流程可测试、可追溯、可 mock。4.3 显式编码任务状态机任务边界不只是一次“意图判断”而是整条链路的迁移规则。TASK_STATES [ pending, intent_parsing, collecting_params, confirming, calling_tool, generating_output, success, failed, needs_review ] ALLOWED_TRANSITIONS { pending: [intent_parsing], intent_parsing: [collecting_params, confirming, failed], collecting_params: [confirming, failed], confirming: [calling_tool, collecting_params, needs_review], calling_tool: [generating_output, needs_review, failed], generating_output: [success, needs_review], failed: [collecting_params, pending, needs_review], needs_review: [calling_tool, success, failed] }为什么状态机很重要因为生产级 Agent 不允许“模型想怎么走就怎么走”。状态机让任务在任意时刻都有确定的位置也方便失败恢复和人工介入。5. 规则二状态、记忆与上下文的显式管理第二条规则不要把所有信息都塞进上下文窗口。这是最容易犯的错误。很多 Agent 实现是“每轮把全部历史记录拼成一个大 Prompt 丢给模型”短期可行一旦上下文变长费用、延迟和准确率都会恶化。5.1 上下文分层建议把上下文分成三层系统级上下文角色定义、工具说明、输出格式、安全限制。任务级上下文当前任务的目标、已收集到的参数、工具调用返回结果。会话级上下文多轮对话中的精简摘要。系统级上下文保持稳定只在系统升级时变更。任务级上下文用结构化字段存储不依赖模型记忆。会话级上下文可以在每轮结束后生成摘要摘要长度固定避免无限膨胀。5.2 记忆不只靠 LLMAgent 的“记忆”应该落在数据库里。比如task_memory: - task_id - user_id - key - value - updated_at这个表可以存用户偏好、上次填写的参数、之前工具调用的结果。下次任务启动时按需加载而不是把整个历史都丢给模型。5.3 引入“重写摘要”而不是“拼接全文”当会话轮数超过阈值时用一次独立的 LLM 调用生成压缩摘要再用摘要替换历史记录原文。def summarize_history(history: list[dict]) - str: prompt f 请压缩以下对话记录为 200 字以内的摘要保留任务目标、已收集参数、待确认事项 {history} return llm_call(prompt)从材料看这样做的收益是延迟稳定。用户多轮交互时不会因为历史变长而越来越慢。6. 规则三工具调用的可观测性与审计第三条规则Agent 执行的每个动作都要能被追踪和审计。生产环境里“模型说了一句话”和“系统执行了一个动作”是两件完全不同的事。比如 Agent 说“我已经帮你取消了订单”但实际接口没有调用成功那这个回答就是严重事故。6.1 每次工具调用都要记录建议为 Agent 接入类似“动作审计日志”的机制{ event: tool_call, tool_name: order_service.cancel_order, arguments: { order_id: NO20260101123456 }, result_status: success, result_preview: order cancelled, executed_by: agent, approved_by: null, latency_ms: 320 }至少要记录调了哪个工具、参数是什么、成功失败、耗时多少。6.2 写操作必须经过确认如果 Agent 要执行写操作删除、修改、发送、下单建议分成两步Agent 生成“动作提案”proposed_action。系统根据规则自动确认或发送给用户/人工审批。确认后真正执行。实现上可以在工具封装层加一个requires_approval标志TOOL_APPROVAL_POLICY { order_service.cancel_order: user_confirm, order_service.query_status: none, notification.send_email: human_approval }这样做不一定是每次都要人工点按钮可以用规则自动批准低风险操作但高风险操作必须有审批节点。6.3 链路追踪生产级 Agent 会调用 LLM、数据库、外部 API、内部脚本任何一个环节出问题都需要快速定位。建议给每个任务分配trace_id所有日志、工具调用、模型请求都带上这个 ID。排障时只需要输入trace_id就能看到整个 Agent 任务从开始到结束的完整路径。7. 规则四失败处理、重试与人工介入第四条规则把失败当成正常流程来设计。模型必然会返回错误 JSON、工具调用必然会超时、外部接口必然会不稳定。这些都不是异常情况而是生产级系统必须处理的常态。7.1 工具调用的重试策略给外部工具调用设置明确的超时和重试上限。建议单次调用超时5 秒。重试次数2 次。重试退避线性退避或指数退避。超过重试上限任务标记为needs_review不再继续自动执行。import time def call_with_retry(func, max_retries2, timeout5): last_exception None for attempt in range(max_retries 1): try: return func(timeouttimeout) except TimeoutError as e: last_exception e time.sleep(attempt * 1) raise last_exception7.2 模型输出解析失败的处理模型返回非法 JSON 是最常见的失败场景。不要假设“换一个更强的模型就永远不会出错”而是要在解析层做好兜底。建议做法第一轮直接解析模型输出。失败后把错误信息回传给模型要求修正输出格式。第二次仍失败进入needs_review。def parse_model_json(raw_output: str): try: return json.loads(raw_output) except json.JSONDecodeError as e: # 提取代码块中的 JSON match re.search(rjson\s*(.*?)\s*, raw_output, re.DOTALL) if match: return json.loads(match.group(1)) # 交给模型自纠错 fix_prompt f你的输出不是合法 JSON请修正{raw_output} fixed_output llm_call(fix_prompt) return json.loads(fixed_output)7.3 人工介入通道生产级 Agent 必须保留人工介入通道。建议设置三种情况触发人工低置信度意图识别置信度低于阈值。高危操作删除、转账、封禁、发布。重复失败任务失败超过 N 次。人工介入不是“设计不够好”的表现而是对真实业务负责。8. 规则五评估集、回归测试与灰度发布第五条规则上线前必须有评估上线后必须有回归。Prompt 调整、模型切换、工具参数变化都可能让 Agent 从“表现不错”变成“全线崩坏”。没有评估集的 Agent 项目改动等于盲改。8.1 建立最小评估集建议准备三类测试用例正常场景用户输入清晰工具可用期望 Agent 完成任务。边界场景参数缺失、输入模糊、需要澄清。失败场景工具超时、模型输出非法 JSON、用户要求越权操作。一个评估用例的格式- id: case_001 category: normal input: 我要取消订单 NO20260101123456 expected: intent: cancel_order entity_extracted: order_id: NO20260101123456 tags: [core, order]8.2 用评估集做回归测试每次修改 Prompt 或工具定义后跑一遍评估集。建议关注四个指标意图准确率。参数抽取完整率。工具调用成功率。最终任务完成率。不是只看“模型回得对不对”而是看整条链路是否走通。8.3 灰度与小流量上线生产级 Agent 上线时建议先让 Agent 处理小流量真实请求但不直接执行写操作而是生成“建议动作”给人工确认。等观察日志确认不会翻车后再逐步放开自动执行权限。这套流程的实质是让模型在受限范围内试错而不是直接面对真实业务风险。9. 接口、批量任务与调用面设计从工程化角度Agent 不应该只是“一个聊天窗口”而应该对外提供稳定的调用面。9.1 Agent 服务 API 模板import requests url http://127.0.0.1:8000/agent/run payload { task_id: task_001, user_id: user_123, input: 我要取消订单 NO20260101123456 } response requests.post(url, jsonpayload, timeout30) print(response.json())返回结果建议包含任务 ID、当前状态、意图、需要确认的动作、最终输出。调用方不需要关心 Agent 内部做了几步只需要拿到任务状态和结果。9.2 批量任务调度当 Agent 需要处理大量输入时建议用任务队列。输入文件放在./inputs状态记录在数据库输出写到./outputs。{ input_dir: ./inputs, output_dir: ./outputs, max_concurrency: 4, retry_on_failure: true, max_retries: 2 }批量任务有几个坑要提前规避单条任务失败不能阻塞整个队列。每条任务要有独立日志方便定位。必须设置全局超时避免队列堆积。结果文件要按 task_id 命名不能覆盖。9.3 Webhook 回调批量任务耗时较长不建议用同步 HTTP 等待。可以设计回调机制任务完成后Agent 服务向预设的 Webhook 地址发送结果通知。{ task_id: task_001, status: success, output: 任务结果描述, callback_url: http://your-service.com/webhook/agent_done }这套模式适合把 Agent 集成到已有业务系统里前端提交任务后端异步处理完成后通知。10. 资源占用与性能观察这节单独说性能。虽然这套规则属于工程架构层但在实际部署时仍然会接触到资源占用和延迟问题。10.1 关注哪些指标在 Agent 服务运行过程中建议重点观察模型 API 延迟和 Token 消耗。状态存储数据库的读写延迟。工具调用外部接口的响应时间。任务队列堆积数。进程 CPU 和内存占用。10.2 延迟分析Agent 总耗时等于多个环节的累加总耗时 意图解析耗时 参数收集耗时 工具调用耗时 最终生成耗时如果用户反馈“Agent 响应很慢”优先看日志里哪一段耗时最长。常见问题上下文过长导致模型输入 Token 暴涨。工具调用没有设置超时一直等待外部接口返回。重试逻辑写成了死循环。每次请求都重新加载巨大配置文件。10.3 成本控制生产级 Agent 的成本大头几乎都在模型 API 上。建议为每类任务设置 Token 上限。控制历史记录长度用摘要代替全文。低风险任务使用小模型复杂任务才调用大模型。监控单任务平均成本异常波动说明 Prompt 或逻辑出了问题。11. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 回复“我已经取消了订单”但订单还在工具调用失败但模型没有感知查看工具调用的结构化日志工具失败时禁止生成成功回复改为报错提示上下文越长响应越慢历史全文一直拼接到 Prompt检查模型请求的 token 数量用摘要替换长历史或设置上下文长度上限模型频繁返回非法 JSON输出格式约束不足查看模型原始输出增加格式约束示例加入自纠错逻辑批量任务中途卡住单条任务无限重试检查任务状态是否停在 running设置全局超时和最大重试次数写操作被误执行动作确认策略没有设置查看审批日志为写操作工具配置 requires_approval同一输入每次结果不一样模型温度设置过高对比多次输出日志确定性任务降低 temperature或固定 seed日志分散在各文件排障困难没有链路追踪按 trace_id 搜索所有日志统一带上 trace_idAgent 越权处理了不擅长的问题意图边界没定义查看是否落入错误 intent在意图解析层增加“无法处理”类别这套排查表基本覆盖了从“能跑 Demo”到“上生产”之间最常见的翻车点。实际落地时如果发现新的问题建议直接补到自己的排障清单里。12. 最佳实践与下一步最后给一组可以直接抄走的工程建议。先按“最小闭环”跑通用状态机 结构化日志 一个工具调用把规则一和规则三先落地。不需要一开始就上复杂编排第一个版本只要做到“每条任务、每个动作都有日志失败能被发现”就已经比大多数 Demo 强了。再补评估准备 20 条正常场景用例、10 条边界场景用例、5 条失败场景用例。每次改 Prompt、换模型、加工具之前先跑一遍。通过率不达标就不允许上生产。然后加保护所有写操作默认需要审批所有外部工具默认设置超时。保护机制不是限制 Agent 能力而是让失控的成本可控。最后考虑扩展接人任务队列支持批量处理接 Webhook支持异步回调接可视化面板让非技术同事也能看到任务状态。Linear 这套“生产级别 Agent”规则本质上是在回答同一个问题当 LLM 的不确定性进入真实业务时用什么方式把它约束住。规则不是限制模型智能而是把不可控的模型输出装进一个可追踪、可验证、可回滚的框架里。先跑通一个受控任务再逐步扩大 Agent 的权限和任务范围这是最稳的路径。如果你正在规划 Agent 项目建议先把第三条规则“工具调用可观测性”和第五条规则“评估集回归测试”变成代码落地这两条收益最大也最容易在早期就埋下基础。剩下的规则可以在迭代过程中逐步补齐。
生产级Agent工程化：Linear的5条规则，让大模型应用可控可观测
这次我们聊的不是某个图形界面工具也不是某个模型权重而是 Linear 团队沉淀下来的一套 Agent 工程方法论构建生产级别 Agent 的 5 条规则。先直接说结论当前很多 Agent 项目能跑通 Demo但一旦进入生产环境就暴露问题——不可控、不可观测、不可回滚、不能评估。Linear 这套规则的价值在于它把 Agent 从“能聊天的玩具”拉回“有边界的工程系统”用显式建模、状态管理、可观测性、失败兜底和回归评估来约束 LLM 的不确定性。这篇文章会把这 5 条规则拆开讲清楚并给出每一条落地时需要的工程配置、代码模板、验证方式和排查思路。适合正在做 Agent 应用开发、想把智能体接到真实业务里、或者准备从单轮 Demo 走向多轮任务编排的读者。如果你只关心提示词怎么写这篇文章帮助有限如果你想的是“怎么让 Agent 稳定输出、出错了怎么定位、上线了怎么评估”可以直接收藏。1. 方法论核心速览能力项说明适用对象使用 LLM API 搭建任务型 Agent 的工程团队也适用于个人开发者落地小规模智能体服务核心目标让 Agent 在真实业务中可控、可观测、可评估、可回滚核心模块意图解析、状态机、工具调度、可观测日志、失败兜底、回归评估集工程要求需要状态存储、日志系统、任务队列、接口封装不依赖特定模型厂商支持平台只要能用 Python/Node 调 LLM API就能按这套规则落地是否开源方法论本身不依赖特定 GitHub 仓库具体实现需基于团队现有代码库集成批量任务规则四和规则九章节会给出任务队列与批量调度的设计思路接口能力通过显式 API 封装 Agent 动作便于第三方系统接入适合场景客服工单处理、数据分析助手、代码审查助手、自动化运维、内部知识库问答这张表没有列出“显存占用”和“GPU 依赖”因为这套方法论属于工程架构层而不是模型推理层。你在落地时仍然可以使用云端 LLM API也可以本地化部署模型两者并不冲突。2. 适用场景与使用边界先明确这套方法论适合什么场景。生产级 Agent 通常具备三个特征任务目标明确而不是开放式闲聊。需要调用外部工具或系统例如查数据库、发通知、改工单状态。输出会影响真实业务所以不允许“随便答”。典型场景包括客服自动应答Agent 读取用户工单调用知识库检索最后生成回复草稿。数据分析助手Agent 根据自然语言生成查询语句执行查询返回结构化结果。运维辅助Agent 解析日志识别异常调用脚本完成初步处置。内容生产辅助Agent 按流程完成多步骤文本处理并通过人工审核后发布。不适合什么场景第一种是开放式闲聊型产品这类产品追求发散性不需要强约束套这套规则反而限制体验。第二种是高风险决策场景例如医疗诊断、法律意见、金融自动交易在没有人工复核和完整合规评估之前任何规则都不能替代责任边界。合规边界要注意如果 Agent 会处理用户隐私数据必须在设计阶段就明确数据脱敏范围如果 Agent 会调用第三方系统写操作必须预留审批节点如果 Agent 会生成面向公众的内容必须有审核流程。不能因为“模型能输出”就觉得“可以自动发布”。3. 生产级 Agent 的工程化前置条件在讨论 5 条规则之前先确认工程前置条件。这不是代码层面的依赖而是架构层面的“地基”。3.1 显式状态存储生产级 Agent 不能把所有上下文都塞在 Prompt 里。多轮任务中每一步的输入、输出、中间结果都应该有明确的存储位置。推荐最小方案- task_id: 任务唯一 ID - status: pending / running / waiting_tool / success / failed / needs_review - input_payload: 用户输入 - step_history: 每个 Agent 动作的记录 - tool_results: 工具调用结果 - final_output: 最终输出不要用“全局变量 内存”的方式管理 Agent 状态。一旦服务重启、进程崩溃或并发请求增加状态丢失会造成任务不可恢复。3.2 结构化日志Debug 一个生产级 Agent最大的问题是“不知道它中间做了什么”。所以从第一版开始就要输出结构化日志。一个最小日志字段建议{ timestamp: 2026-01-01T10:00:00Z, task_id: task_001, step: intent_parsing, model: gpt-4o, prompt_version: v3, input_preview: 用户原始输入前200字, output_preview: 模型输出前200字, latency_ms: 830, token_usage: { prompt_tokens: 1200, completion_tokens: 300, total_tokens: 1500 } }这个日志文件会在规则三“可观测性”里发挥关键作用。3.3 任务队列如果 Agent 会被多个用户同时调用建议在 Agent 前面加一层任务队列而不是让每个 HTTP 请求直接创建一个 Agent 实例。任务队列的好处是控制并发、失败重试、限流、追踪。批量任务场景下队列几乎是必须的。3.4 工具接口封装Agent 要调用的外部工具不要直接给模型裸 SQL、裸 Shell、裸 API。先把工具封装成“有明确输入输出格式的 Function”模型只负责生成符合 JSON Schema 的参数真正的执行权留在受控的服务里。4. 规则一意图解析与任务边界的显式建模第一条规则是先定义 Agent 能做什么再让模型决定做什么。很多 Agent Demo 翻车不是因为模型能力不够而是因为“边界”没有定义。4.1 先枚举任务类型在生产环境里Agent 能处理的任务应该是有限集合。比如cancel_order取消订单modify_shipping修改收货地址query_order_status查询订单状态refund_apply申请退款escalate_to_human转人工把这些任务定义成枚举然后在 Prompt 或函数调用定义里约束模型只能从这里面选。不要开放“根据用户意思随便做”。4.2 用结构化字段承载用户意图不建议把“意图解析结果”直接用自然语言文本传给后续流程而是转成结构化数据。# 意图解析结果示例 { intent: cancel_order, confidence: 0.92, entities: { order_id: NO20260101123456, reason: 不想要了 }, raw_input: 我要取消订单 NO20260101123456东西不想要了 }后续步骤只需要读这个结构化对象不再重新解析用户原文。这样做的好处是流程可测试、可追溯、可 mock。4.3 显式编码任务状态机任务边界不只是一次“意图判断”而是整条链路的迁移规则。TASK_STATES [ pending, intent_parsing, collecting_params, confirming, calling_tool, generating_output, success, failed, needs_review ] ALLOWED_TRANSITIONS { pending: [intent_parsing], intent_parsing: [collecting_params, confirming, failed], collecting_params: [confirming, failed], confirming: [calling_tool, collecting_params, needs_review], calling_tool: [generating_output, needs_review, failed], generating_output: [success, needs_review], failed: [collecting_params, pending, needs_review], needs_review: [calling_tool, success, failed] }为什么状态机很重要因为生产级 Agent 不允许“模型想怎么走就怎么走”。状态机让任务在任意时刻都有确定的位置也方便失败恢复和人工介入。5. 规则二状态、记忆与上下文的显式管理第二条规则不要把所有信息都塞进上下文窗口。这是最容易犯的错误。很多 Agent 实现是“每轮把全部历史记录拼成一个大 Prompt 丢给模型”短期可行一旦上下文变长费用、延迟和准确率都会恶化。5.1 上下文分层建议把上下文分成三层系统级上下文角色定义、工具说明、输出格式、安全限制。任务级上下文当前任务的目标、已收集到的参数、工具调用返回结果。会话级上下文多轮对话中的精简摘要。系统级上下文保持稳定只在系统升级时变更。任务级上下文用结构化字段存储不依赖模型记忆。会话级上下文可以在每轮结束后生成摘要摘要长度固定避免无限膨胀。5.2 记忆不只靠 LLMAgent 的“记忆”应该落在数据库里。比如task_memory: - task_id - user_id - key - value - updated_at这个表可以存用户偏好、上次填写的参数、之前工具调用的结果。下次任务启动时按需加载而不是把整个历史都丢给模型。5.3 引入“重写摘要”而不是“拼接全文”当会话轮数超过阈值时用一次独立的 LLM 调用生成压缩摘要再用摘要替换历史记录原文。def summarize_history(history: list[dict]) - str: prompt f 请压缩以下对话记录为 200 字以内的摘要保留任务目标、已收集参数、待确认事项 {history} return llm_call(prompt)从材料看这样做的收益是延迟稳定。用户多轮交互时不会因为历史变长而越来越慢。6. 规则三工具调用的可观测性与审计第三条规则Agent 执行的每个动作都要能被追踪和审计。生产环境里“模型说了一句话”和“系统执行了一个动作”是两件完全不同的事。比如 Agent 说“我已经帮你取消了订单”但实际接口没有调用成功那这个回答就是严重事故。6.1 每次工具调用都要记录建议为 Agent 接入类似“动作审计日志”的机制{ event: tool_call, tool_name: order_service.cancel_order, arguments: { order_id: NO20260101123456 }, result_status: success, result_preview: order cancelled, executed_by: agent, approved_by: null, latency_ms: 320 }至少要记录调了哪个工具、参数是什么、成功失败、耗时多少。6.2 写操作必须经过确认如果 Agent 要执行写操作删除、修改、发送、下单建议分成两步Agent 生成“动作提案”proposed_action。系统根据规则自动确认或发送给用户/人工审批。确认后真正执行。实现上可以在工具封装层加一个requires_approval标志TOOL_APPROVAL_POLICY { order_service.cancel_order: user_confirm, order_service.query_status: none, notification.send_email: human_approval }这样做不一定是每次都要人工点按钮可以用规则自动批准低风险操作但高风险操作必须有审批节点。6.3 链路追踪生产级 Agent 会调用 LLM、数据库、外部 API、内部脚本任何一个环节出问题都需要快速定位。建议给每个任务分配trace_id所有日志、工具调用、模型请求都带上这个 ID。排障时只需要输入trace_id就能看到整个 Agent 任务从开始到结束的完整路径。7. 规则四失败处理、重试与人工介入第四条规则把失败当成正常流程来设计。模型必然会返回错误 JSON、工具调用必然会超时、外部接口必然会不稳定。这些都不是异常情况而是生产级系统必须处理的常态。7.1 工具调用的重试策略给外部工具调用设置明确的超时和重试上限。建议单次调用超时5 秒。重试次数2 次。重试退避线性退避或指数退避。超过重试上限任务标记为needs_review不再继续自动执行。import time def call_with_retry(func, max_retries2, timeout5): last_exception None for attempt in range(max_retries 1): try: return func(timeouttimeout) except TimeoutError as e: last_exception e time.sleep(attempt * 1) raise last_exception7.2 模型输出解析失败的处理模型返回非法 JSON 是最常见的失败场景。不要假设“换一个更强的模型就永远不会出错”而是要在解析层做好兜底。建议做法第一轮直接解析模型输出。失败后把错误信息回传给模型要求修正输出格式。第二次仍失败进入needs_review。def parse_model_json(raw_output: str): try: return json.loads(raw_output) except json.JSONDecodeError as e: # 提取代码块中的 JSON match re.search(rjson\s*(.*?)\s*, raw_output, re.DOTALL) if match: return json.loads(match.group(1)) # 交给模型自纠错 fix_prompt f你的输出不是合法 JSON请修正{raw_output} fixed_output llm_call(fix_prompt) return json.loads(fixed_output)7.3 人工介入通道生产级 Agent 必须保留人工介入通道。建议设置三种情况触发人工低置信度意图识别置信度低于阈值。高危操作删除、转账、封禁、发布。重复失败任务失败超过 N 次。人工介入不是“设计不够好”的表现而是对真实业务负责。8. 规则五评估集、回归测试与灰度发布第五条规则上线前必须有评估上线后必须有回归。Prompt 调整、模型切换、工具参数变化都可能让 Agent 从“表现不错”变成“全线崩坏”。没有评估集的 Agent 项目改动等于盲改。8.1 建立最小评估集建议准备三类测试用例正常场景用户输入清晰工具可用期望 Agent 完成任务。边界场景参数缺失、输入模糊、需要澄清。失败场景工具超时、模型输出非法 JSON、用户要求越权操作。一个评估用例的格式- id: case_001 category: normal input: 我要取消订单 NO20260101123456 expected: intent: cancel_order entity_extracted: order_id: NO20260101123456 tags: [core, order]8.2 用评估集做回归测试每次修改 Prompt 或工具定义后跑一遍评估集。建议关注四个指标意图准确率。参数抽取完整率。工具调用成功率。最终任务完成率。不是只看“模型回得对不对”而是看整条链路是否走通。8.3 灰度与小流量上线生产级 Agent 上线时建议先让 Agent 处理小流量真实请求但不直接执行写操作而是生成“建议动作”给人工确认。等观察日志确认不会翻车后再逐步放开自动执行权限。这套流程的实质是让模型在受限范围内试错而不是直接面对真实业务风险。9. 接口、批量任务与调用面设计从工程化角度Agent 不应该只是“一个聊天窗口”而应该对外提供稳定的调用面。9.1 Agent 服务 API 模板import requests url http://127.0.0.1:8000/agent/run payload { task_id: task_001, user_id: user_123, input: 我要取消订单 NO20260101123456 } response requests.post(url, jsonpayload, timeout30) print(response.json())返回结果建议包含任务 ID、当前状态、意图、需要确认的动作、最终输出。调用方不需要关心 Agent 内部做了几步只需要拿到任务状态和结果。9.2 批量任务调度当 Agent 需要处理大量输入时建议用任务队列。输入文件放在./inputs状态记录在数据库输出写到./outputs。{ input_dir: ./inputs, output_dir: ./outputs, max_concurrency: 4, retry_on_failure: true, max_retries: 2 }批量任务有几个坑要提前规避单条任务失败不能阻塞整个队列。每条任务要有独立日志方便定位。必须设置全局超时避免队列堆积。结果文件要按 task_id 命名不能覆盖。9.3 Webhook 回调批量任务耗时较长不建议用同步 HTTP 等待。可以设计回调机制任务完成后Agent 服务向预设的 Webhook 地址发送结果通知。{ task_id: task_001, status: success, output: 任务结果描述, callback_url: http://your-service.com/webhook/agent_done }这套模式适合把 Agent 集成到已有业务系统里前端提交任务后端异步处理完成后通知。10. 资源占用与性能观察这节单独说性能。虽然这套规则属于工程架构层但在实际部署时仍然会接触到资源占用和延迟问题。10.1 关注哪些指标在 Agent 服务运行过程中建议重点观察模型 API 延迟和 Token 消耗。状态存储数据库的读写延迟。工具调用外部接口的响应时间。任务队列堆积数。进程 CPU 和内存占用。10.2 延迟分析Agent 总耗时等于多个环节的累加总耗时 意图解析耗时 参数收集耗时 工具调用耗时 最终生成耗时如果用户反馈“Agent 响应很慢”优先看日志里哪一段耗时最长。常见问题上下文过长导致模型输入 Token 暴涨。工具调用没有设置超时一直等待外部接口返回。重试逻辑写成了死循环。每次请求都重新加载巨大配置文件。10.3 成本控制生产级 Agent 的成本大头几乎都在模型 API 上。建议为每类任务设置 Token 上限。控制历史记录长度用摘要代替全文。低风险任务使用小模型复杂任务才调用大模型。监控单任务平均成本异常波动说明 Prompt 或逻辑出了问题。11. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 回复“我已经取消了订单”但订单还在工具调用失败但模型没有感知查看工具调用的结构化日志工具失败时禁止生成成功回复改为报错提示上下文越长响应越慢历史全文一直拼接到 Prompt检查模型请求的 token 数量用摘要替换长历史或设置上下文长度上限模型频繁返回非法 JSON输出格式约束不足查看模型原始输出增加格式约束示例加入自纠错逻辑批量任务中途卡住单条任务无限重试检查任务状态是否停在 running设置全局超时和最大重试次数写操作被误执行动作确认策略没有设置查看审批日志为写操作工具配置 requires_approval同一输入每次结果不一样模型温度设置过高对比多次输出日志确定性任务降低 temperature或固定 seed日志分散在各文件排障困难没有链路追踪按 trace_id 搜索所有日志统一带上 trace_idAgent 越权处理了不擅长的问题意图边界没定义查看是否落入错误 intent在意图解析层增加“无法处理”类别这套排查表基本覆盖了从“能跑 Demo”到“上生产”之间最常见的翻车点。实际落地时如果发现新的问题建议直接补到自己的排障清单里。12. 最佳实践与下一步最后给一组可以直接抄走的工程建议。先按“最小闭环”跑通用状态机 结构化日志 一个工具调用把规则一和规则三先落地。不需要一开始就上复杂编排第一个版本只要做到“每条任务、每个动作都有日志失败能被发现”就已经比大多数 Demo 强了。再补评估准备 20 条正常场景用例、10 条边界场景用例、5 条失败场景用例。每次改 Prompt、换模型、加工具之前先跑一遍。通过率不达标就不允许上生产。然后加保护所有写操作默认需要审批所有外部工具默认设置超时。保护机制不是限制 Agent 能力而是让失控的成本可控。最后考虑扩展接人任务队列支持批量处理接 Webhook支持异步回调接可视化面板让非技术同事也能看到任务状态。Linear 这套“生产级别 Agent”规则本质上是在回答同一个问题当 LLM 的不确定性进入真实业务时用什么方式把它约束住。规则不是限制模型智能而是把不可控的模型输出装进一个可追踪、可验证、可回滚的框架里。先跑通一个受控任务再逐步扩大 Agent 的权限和任务范围这是最稳的路径。如果你正在规划 Agent 项目建议先把第三条规则“工具调用可观测性”和第五条规则“评估集回归测试”变成代码落地这两条收益最大也最容易在早期就埋下基础。剩下的规则可以在迭代过程中逐步补齐。