生产级AI Agent的5条工程实践：从边界定义到评估体系

在 AI Agent 从“实验室玩具”走向“业务生产力工具”的过程中团队面临的瓶颈往往不是模型能力而是工程化能力。模型可以快速跑通 Demo却很难在真实业务中稳定运行。Linear 团队公开分享过构建生产级别 Agent 的 5 条规则这背后是一套完整的工程方法论对任何准备把 Agent 落到业务中的团队都有参考价值。本文将围绕这 5 条规则展开先讲清楚每条规则要解决什么问题再给出具体的落地思路、代码示例和工程建议。无论你是在做 Agent 框架选型、流程编排还是已经进入 Agent 维护阶段都能从中找到可复用的实践经验。1. 背景为什么 AI Agent 从 Demo 到生产这么难1.1 Demo 与生产环境之间的鸿沟很多团队在体验 Agent 时都会有一个共同感受在本地跑通一个 Agent 很快但真正放进生产环境问题立刻变多。模型输出不稳定、工具调用结果不可控、上下文逐渐膨胀、错误恢复困难、安全问题频发这些都是在 Demo 时很难提前暴露的。Demo 阶段的 Agent 通常是单轮对话、输入明确、输出开放、执行路径短。而生产环境的 Agent 要面对的是多轮交互、输入模糊、输出约束严格、执行路径长、并发访问高。两者的复杂度完全不在一个量级。比如一个简单的“客服工单自动分类”AgentDemo 阶段只需要把用户问题传给大模型返回一个分类标签就可以。但生产环境要求 Agent 必须先做意图识别、再检查用户身份和权限、查询历史工单、参考知识库、生成结构化结果、写入业务系统、记录完整日志最后还要处理失败重试和人工兜底。每多一个环节潜在的失败点就多一层。1.2 Linear 团队为什么值得参考Linear 是一支以产品体验和工程效率著称的团队团队成员长期深度使用 AI 编程工具辅助开发。在构建 Agent 的过程中他们总结出了一套实践原则核心思想是Agent 不应该追求无限自主而是要在一个可控的边界内高效完成任务。这套思路与当前业内对 Agent 的主流认知高度一致Agent 的价值不在于“什么都能做”而在于“在该做的事上做得可靠、可预测、可维护”。1.3 什么是“生产级别 Agent”要理解“生产级别 Agent”可以先从它的对立面来看。一个 Demo 级 Agent 的特点是没有错误处理模型返回异常直接崩溃。没有审计日志出了问题无法定位。没有权限控制Agent 能访问所有资源和数据。没有评估机制只靠人来判断输出好坏。没有运维支撑无法监控和告警。而生产级别 Agent 至少要满足以下条件有明确的能力边界和权限范围。有完整的日志、追踪和监控机制。有可控的人机协同流程关键操作需要审批。有结构化和非结构化双层输出验证。有持续评估和回归测试机制。可以说生产级别 Agent 不是“更聪明的 Agent”而是“更稳、更安全、更可维护的 Agent”。2. 规则一定义边界让 Agent 知道自己“不该做什么”2.1 为什么要定义边界Agent 的能力来自大模型的推理能力但大模型的特点是有创造力、有联想能力这在对话场景是优势在业务场景却是风险。如果不定义边界Agent 可能会尝试调用不在白名单内的工具、访问没有权限的数据、甚至生成不符合业务规范的输出。定义边界的目的不是限制 Agent 的能力而是让 Agent 在可控范围内保持高可靠性。边界越清晰Agent 的失败模式就越可预测排错成本就越低。2.2 边界包括哪些维度边界至少包含四个维度工具边界Agent 可以调用哪些工具不可以调用哪些工具。数据边界Agent 可以读取哪些数据不可以读取哪些数据。权限边界Agent 的 API Key、服务账号具有什么级别的权限。操作边界哪些操作 Agent 可以自主完成哪些必须经过人工审批。以一个简单的文件处理 Agent 为例工具边界可以这样定义# 文件路径agent_tools.py from pydantic import BaseModel class ReadFileInput(BaseModel): path: str class WriteFileInput(BaseModel): path: str content: str class ListDirectoryInput(BaseModel): path: str # 只允许 Agent 访问 /data/sandbox 下的文件 ALLOWED_ROOT /data/sandbox def is_within_allowed_root(path: str) - bool: normalized str(path).replace(\\, /) return normalized.startswith(ALLOWED_ROOT) def safe_read_file(input_data: ReadFileInput) - str: if not is_within_allowed_root(input_data.path): raise PermissionError(fAccess denied: {input_data.path}) with open(input_data.path, r, encodingutf-8) as f: return f.read()在这个示例中safe_read_file做了路径校验只有位于白名单目录下的文件才允许读取。这个校验逻辑虽然简单但在生产环境中能拦截大量恶意路径注入和误操作。类似的边界校验应该覆盖所有工具函数。2.3 边界定义的最佳实践边界定义要遵循“最小权限”原则。默认拒绝一切调用只对明确需要的工具和资源开放访问。同时边界定义应该放在 Agent 启动时的配置中而不是散落在各个工具函数里。{ agent_id: file-agent, allowed_tools: [read_file, write_file, list_directory], allowed_data_sources: [s3://company-upload-bucket/agent-sandbox], max_token_limit: 8000, max_execution_steps: 10, requires_human_approval: [delete_file, send_email, create_issue] }这份配置里allowed_tools指定了可以调用的工具allowed_data_sources限定了数据源requires_human_approval则列出了需要人工审批的操作清单。配置和代码分离是生产级 Agent 的重要特征。3. 规则二把任务拆成可观测、可验证的步骤3.1 长链路任务的失控风险Agent 在执行复杂任务时往往需要多步推理和多次工具调用。如果整个任务是一个黑盒过程中任何一个环节出错都很难定位。更严重的是模型在多步推理中可能逐渐偏离原始目标产出完全不符合预期的结果。解决这个问题的核心方法是把大任务拆成小步骤每个步骤都有明确的输入、输出和验证标准。3.2 步骤拆解如何落地仍以工单分类 Agent 为例一个完整任务可以拆成四个子步骤意图识别判断用户诉求属于哪一类。信息抽取从工单中抽取关键实体。知识检索在知识库中检索相关文档。结果生成生成分类结果和处理建议。每一步的输出都可以用结构化数据来表达并进行自动校验# 文件路径agent_pipeline.py from pydantic import BaseModel class IntentResult(BaseModel): category: str confidence: float class ExtractionResult(BaseModel): customer_id: str order_id: str issue_type: str create_time: str class RetrievalResult(BaseModel): top_documents: list[str] relevance_score: float class FinalResult(BaseModel): classification: str priority: str suggested_action: str related_docs: list[str]每一步的返回都经过 Pydantic 的校验模型输出不符合字段类型或缺少必要字段时会立刻抛出校验异常而不是带着错误数据继续往下执行。3.3 步骤之间的数据传递步骤之间的数据传递也应该显式化避免隐式状态污染。比较好的方式是每个步骤只接收上一步的输出和必要的上下文不共享全局状态。# 文件路径agent_pipeline.py def run_agent(raw_input: dict): # 第一步意图识别 intent_result IntentResult.model_validate( call_llm_with_schema( system_prompt识别用户意图, user_contentraw_input[message], output_schemaIntentResult ) ) if intent_result.confidence 0.6: return {status: need_human, reason: 意图置信度不足} # 第二步信息抽取 extraction_result ExtractionResult.model_validate( call_llm_with_schema( system_prompt抽取工单关键信息, user_contentraw_input[message], output_schemaExtractionResult ) ) # 第三步知识检索此处省略检索代码 retrieval_result search_knowledge_base(extraction_result.issue_type) # 第四步结果生成 final_result FinalResult.model_validate( call_llm_with_schema( system_prompt生成工单分类结果, user_content{ intent: intent_result.model_dump(), extraction: extraction_result.model_dump(), retrieval: retrieval_result.model_dump() }, output_schemaFinalResult ) ) return {status: done, result: final_result.model_dump()}这种流水线式的实现方式虽然看起来不如“一个 Prompt 搞定”那么智能但在生产环境中的可维护性要高得多。因为每一个步骤都是独立的可以单独测试、单独评估、单独替换。4. 规则三人在环路不是可选项而是默认项4.1 为什么需要人在环路有些 Agent 团队追求“全自动”认为人的介入是效率损失。但从实践经验看Agent 在高风险操作上出现错误是必然的只是时间早晚的问题。完全去掉人工审批等于把错误恢复的成本从“事前拦截”变成了“事后补救”。人在环路Human-in-the-Loop的核心思想是Agent 负责完成重复性、低风险的劳动人在关键节点做决策和审批。这样既保留了自动化带来的效率又避免了失控带来的风险。4.2 在哪些环节加入人工审批生产级 Agent 至少应该在以下几类操作上加入人工审批对业务数据的修改、删除操作。对外发送消息、邮件。创建或关闭工单。涉及用户隐私信息的访问。跨系统写入操作。高额或敏感的业务操作。审批流程可以采用“预留暂停点”的方式Agent 执行到需要审批的步骤时暂停并生成审批请求等待人工确认后再继续执行。# 文件路径human_approval.py class ApprovalRequired(Exception): 自定义异常表示需要人工审批 def __init__(self, action: str, payload: dict): self.action action self.payload payload super().__init__(fApproval required for action: {action}) def execute_with_approval(action_name: str, payload: dict, approve_func): 执行需要审批的操作。 approve_func 是一个回调函数返回 True 表示通过False 表示拒绝。 approval approve_func(action_name, payload) if not approval: raise PermissionError(fApproval rejected: {action_name}) return {status: executed, action: action_name}在实际系统中审批不是简单地调用一个本地回调而是要把审批请求发送到企业微信、钉钉、Slack 等平台。这里给出的是核心逻辑示意接入具体 IM 平台时需要修改approve_func的实现。4.3 超时与降级策略人工审批不能无限等待。生产环境里要给审批设置超时时间超时后按预设策略处理通常有三种选择策略适用场景风险默认拒绝高安全敏感操作可能阻塞业务默认继续低风险操作可能产生误操作转交他人多人协作场景依赖审批人响应速度实际应用中建议默认拒绝同时提供自动升级和告警机制避免审批请求长时间无人处理。5. 规则四可观测性是生产环境的生命线5.1 可观测性解决的问题生产环境中的 Agent 一旦出错如果只有一句“模型返回异常”排错工程师是很难定位问题的。必须知道Agent 在什么时间收到什么输入做了哪些推理调用了哪些工具每个工具的响应是什么模型输出了什么最终结果是否通过了校验。可观测性三件套是Logging日志、Metrics指标、Tracing链路追踪。对 Agent 来说还要加上LLM Trace模型调用追踪把每次大模型调用的输入、输出、Token 消耗、延迟都记录下来。5.2 Agent 日志设计生产级 Agent 的日志应该按事件类型划分至少包括以下事件agent_startAgent 开始执行任务。agent_finishAgent 完成执行。step_start某个子步骤开始。step_finish某个子步骤完成。tool_call调用工具。tool_response工具返回结果。llm_call调用大模型。llm_response大模型返回结果。approval_request发起审批。approval_result审批结果。error异常信息。human_escalation人工介入。一个标准的日志片段{ timestamp: 2024-11-20T10:15:30.123Z, event: tool_call, agent_id: file-agent, session_id: 7c9d8a5e-9f94-4d2c-b6a1-3b1c2e8f0a6d, step_id: step_3, tool_name: read_file, input: {path: /data/sandbox/report.txt}, trace_id: ab12cd34ef567890 }在 Python 中可以用structlog输出结构化日志# 文件路径logger.py import structlog logger structlog.get_logger() def log_tool_call(agent_id, session_id, step_id, tool_name, tool_input, trace_id): logger.info( tool_call, agent_idagent_id, session_idsession_id, step_idstep_id, tool_nametool_name, tool_inputtool_input, trace_idtrace_id )5.3 模型调用追踪模型调用是 Agent 中最容易出现性能瓶颈和成本压力的环节必须单独追踪。每次模型调用至少记录以下字段模型名称和版本。Prompt 的 Token 数。Completions 的 Token 数。响应延迟。返回内容截断标识。消耗的费用估算如果计费。用一个简化的追踪数据结构{ event: llm_call, model: gpt-4o-mini, prompt_tokens: 1250, completion_tokens: 320, total_tokens: 1570, latency_ms: 2340, finish_reason: stop }这些数据不仅可以用来排错还可以作为成本优化和模型选型的依据。如果长期监控发现某个环节经常超出 Token 上限就需要对 Prompt 做压缩或拆分。5.4 监控和告警日志和追踪是“事后定位”还需要监控和告警做“事前发现”。建议监控以下核心指标Agent 调用成功率。Agent 平均响应时间。工具调用失败率。人工审批平均等待时间。模型调用 Token 消耗趋势。上下文超限频率。结构化输出校验失败率。告警规则可以设置为成功率低于 90% 告警、平均响应时间超过 10 秒告警、审批超时率超过 30% 告警。具体阈值需要根据业务调整但建议在项目上线初期就接入不要等到出事故再补。6. 规则五用评估体系驱动迭代6.1 没有评估就没有迭代方向很多团队对 Agent 的优化停留在“改 Prompt 试试”的阶段改了之后凭感觉判断好不好。这种方式偶尔能奏效但无法持续迭代因为不知道改动的真正影响。生产级 Agent 必须建立评估体系用数据量化每个改动带来的效果变化。6.2 评估集的建设评估集是评估体系的核心资产。建设评估集不是一次性工作而是一个持续积累的过程。评估集的来源可以包括线上真实用户的历史输入。已有知识库中的典型问题。已知错误场景和边界场景。人工构造的对抗性测试。每条评估样本至少应包含四个字段输入、期望输出、评估维度、备注。{ test_id: case_0001, input: 我的订单 20241118001 已付款但一直显示待发货请帮我查一下, expected: { classification: order_delivery, priority: high, suggested_action: check_order_status_and_contact_warehouse }, dimensions: [classification, priority, action], remark: 用户已付款但未发货属于高优先级问题 }6.3 自动化回归测试评估集建好之后要把它接入自动化回归测试。每次修改 Prompt、调整工具逻辑、更换模型版本时都运行一次全量评估对比通过率和关键指标的变化。# 文件路径evaluate.py import json def run_evaluation(agent_fn, testset_path: str): with open(testset_path, r, encodingutf-8) as f: testset json.load(f) pass_count 0 total_count len(testset) detail [] for case in testset: result agent_fn(case[input]) expected case[expected] passed check_match(result, expected) if passed: pass_count 1 detail.append({ test_id: case[test_id], passed: passed, actual: result, expected: expected }) accuracy pass_count / total_count if total_count 0 else 0 return { total: total_count, passed: pass_count, accuracy: round(accuracy, 4), detail: detail } def check_match(actual: dict, expected: dict) - bool: for key in expected: if actual.get(key) ! expected[key]: return False return True这份评估代码返回的是整体通过率和逐条测试详情可以直接接入 CI/CD 流程。当回归测试失败时CI 可以阻止发布。6.4 线上效果监控除了离线评估还要做线上效果的持续监控。可以采用“抽样人工评估”机制每天抽取一定比例的线上 Agent 执行记录由人工对执行结果打分记录质量问题和改进建议。这些人工评估结果又会沉淀为新的评估集样本形成闭环。7. 实战用 5 条规则搭建一个生产级工单 Agent7.1 需求与架构我们以“自动处理客户工单”为场景串起前面 5 条规则。这个 Agent 的职责是读取用户提交的工单。识别问题类型和紧急程度。查询知识库寻找解决方案。对可以自动解决的问题直接回复用户。对无法自动解决的问题生成处理建议并提交人工审核。整体流程可以描述为用户提交工单 → 边界检查 → 意图分类 → 信息抽取 → 知识检索 → 方案生成 → 风险判断 → 自动回复或人工审批 → 记录日志。7.2 项目结构agent_project/ ├── config/ │ └── agent_config.json # Agent 边界和参数配置 ├── src/ │ ├── tools/ │ │ ├── __init__.py │ │ ├── safe_tools.py # 带边界检查的工具 │ │ ├── search_kb.py # 知识库检索工具 │ │ └── ticket_api.py # 工单系统 API │ ├── pipeline/ │ │ ├── __init__.py │ │ ├── steps.py # 子步骤定义 │ │ └── runner.py # 流程编排 │ ├── approval/ │ │ ├── __init__.py │ │ └── approver.py # 人工审批逻辑 │ ├── observability/ │ │ ├── __init__.py │ │ ├── logger.py # 结构化日志 │ │ └── tracer.py # 链路追踪 │ └── main.py # 入口 ├── tests/ │ ├── testset.json # 评估集 │ └── run_eval.py # 回归测试脚本 └── requirements.txt7.3 入口代码示例# 文件路径src/main.py import json from src.pipeline.runner import run_agent_pipeline from src.observability.logger import logger def load_config(): with open(config/agent_config.json, r, encodingutf-8) as f: return json.load(f) def handler(raw_event: dict): config load_config() logger.info( agent_start, agent_idconfig[agent_id], session_idraw_event.get(session_id) ) try: result run_agent_pipeline(raw_event, config) logger.info(agent_finish, session_idraw_event.get(session_id), resultresult) return result except Exception as e: logger.error(agent_error, messagestr(e), session_idraw_event.get(session_id)) return {status: error, message: str(e)}7.4 核心流程编排代码示例# 文件路径src/pipeline/runner.py from src.pipeline.steps import classify_intent, extract_info, search_knowledge, generate_solution from src.approval.approver import need_human_approval, request_approval def run_agent_pipeline(raw_event: dict, config: dict): # 边界检查确认 session 是否在白名单内 session_id raw_event.get(session_id, ) if session_id not in config.get(allowed_sessions, []): raise PermissionError(fSession {session_id} not allowed) # 步骤 1意图分类 intent classify_intent(raw_event[message], config) if intent[confidence] config.get(intent_threshold, 0.6): return {status: need_human, reason: intent_confidence_low} # 步骤 2信息抽取 extracted extract_info(raw_event[message], config) # 步骤 3知识库检索 docs search_knowledge(extracted, config) # 步骤 4生成解决方案 solution generate_solution(intent, extracted, docs, config) # 步骤 5判断是否需要人工审批 risk_level solution.get(risk_level, low) if risk_level in config.get(requires_human_approval_risks, []): approval_result request_approval(solution, config) if not approval_result[approved]: return {status: rejected, reason: human_rejected} # 步骤 6输出最终结果 return {status: done, solution: solution}7.5 实际效果与经验按照上述结构落地之后这个工单 Agent 的可维护性明显优于单一 Prompt 的实现方式。最直观的收益是当某个环节出错时可以从日志中直接定位到具体是模型分类不准、知识检索不到、还是审批超时而不需要再通过反复测试去猜测。在此基础上评估集推动了持续优化。刚开始时意图分类准确率只有 80% 左右通过不断补充对抗样本逐步把准确率提升到了 92%。如果没有评估集很难说清楚哪次 Prompt 改动带来了真正的提升。8. 常见问题与排查思路构建生产级 Agent 的过程中以下问题是团队最容易遇到的问题现象常见原因解决思路Agent 执行到一半停止响应模型上下文超限或工具调用超时增加 Token 上限监控拆分长任务设置工具调用超时结构化输出频繁校验失败Prompt 中输出格式描述不清晰使用 JSON Schema 约束增加 Few-shot 示例加入自动重试机制Agent 调用了不该调用的工具工具白名单配置不完整检查边界配置默认拒绝策略审批请求无人处理任务一直卡住审批超时策略不完善设置审批超时配置升级和转交机制线上效果和评估集结果差距大评估集数据分布与线上不一致增加线上数据采样动态补充评估集模型输出“幻觉”严重知识检索不到相关内容增加 RAG 检索质量评估结果带引用来源成本逐步上升上下文膨胀导致每次请求 Token 增加引入上下文压缩控制历史消息条数日志太多难以阅读所有事件打在同一日志流按事件类型分 Topic增加 session_id 过滤针对结构化输出崩溃的问题一个实用的方案是在校验失败时自动重试一次并告诉模型上一次的错误信息# 文件路径src/pipeline/steps.py def call_llm_with_schema(system_prompt, user_content, output_schema, retry_count1): from pydantic import ValidationError for attempt in range(retry_count 1): try: raw_response llm_call(system_prompt, user_content) parsed output_schema.model_validate_json(raw_response) return parsed except ValidationError as e: if attempt retry_count: raise user_content f\n\n上次输出格式不符合要求错误信息{e}\n请重新生成。 raise RuntimeError(unreachable)9. 最佳实践与工程建议9.1 将 Agent 当作“有状态服务”来对待Agent 不是简单的一次性函数调用它有自己的上下文、会话状态和外部依赖。在生产环境中要把 Agent 当作有状态服务来治理包括状态持久化、超时管理、并发控制、优雅停机。建议为每个会话分配独立的 session_id并把这个 ID 贯穿到所有日志和追踪数据中。9.2 配置与代码分离工具白名单、审批规则、阈值参数、Prompt 模板都不应该硬编码在代码里。把它们放到配置中心或专门的配置文件中配合 CI/CD 进行版本管理。这样可以在不重新发布服务的情况下动态调整 Agent 行为。9.3 安全设计前置Agent 的安全问题必须在设计阶段考虑而不是上线后补救。至少要做到所有外部输入都经过校验和清洗。所有工具调用都有权限校验。所有访问外部系统的凭证使用独立的最小权限凭据。所有敏感数据脱敏后才进入模型上下文。所有关键操作都有审计记录。9.4 引入“护栏”机制除了规则一里说的边界控制还可以增加两层护栏输出护栏对模型生成内容进行敏感词过滤、合规校验。行为护栏监控 Agent 的执行步数、Token 消耗、工具调用频率超过上限自动终止。9.5 先做窄再做强很多团队一开始就想构建“全知全能”的 Agent结果项目很快失控。更务实的路径是先选择一个边界清晰、频次高、重复性强的业务场景把这一条链路做到稳定再横向扩展。比如先做工单自动分类再逐步扩展到工单自动回复、自动操作。9.6 数据积累是长期资产Agent 在生产环境中产生的每一次成功和失败都是宝贵的资产。建议从第一天就记录完整的执行轨迹定期做失败分析和样本入库。这些数据不仅可以优化 Prompt还能用来做模型的 Fine-tuning或者训练专门的评估模型。10. 总结与下一步Linear 团队分享的 5 条规则本质上是一套“可信 Agent”的构建框架定义边界让 Agent 在可控范围内运行。拆解步骤把黑盒变白盒。人在环路用审批沉淀风险和信任。可观测性让问题可以被发现和定位。评估体系让优化有据可依。这套规则的通用性很强不依赖特定的大模型厂商也不绑定特定的 Agent 框架。当你开始规划自己的生产级 Agent 时可以按这 5 条规则逐条对照先补足工程短板再追求更高级的智能能力。下一步建议重点学习 Agent 框架与编排、Harness 工程实践、Agent 记忆机制、以及 Agent 与 MCP 工具的协作方式。这些方向都是在 5 条规则之上构建更强 Agent 能力的关键技术路径。