企业官网建设流程全解析

前两天有人问我：“你那个 AI Agent 在 demo 里跑得飞起，一接真实业务就拉胯，到底是为什么？”我回了一句：“因为你只写了 Agent，没写 Harness。”对方当时就愣了：“Harness？那不是加载模型用的工具吗？”这就是我想写这篇东西的原因——很多人把 Harness 理解成某个具体插件，但它真正的意思是：让一个 AI Agent 能稳定地“下地干活”的那套工程框架和运行环境。换句话说，Agent 是脑子和手，Harness 是身体、筋络、保险绳，还有旁边盯着的安全员。

今天不扯虚的，直接把这套东西拆给你看。一个真正能扛业务的 AI Agent Harness，拆到底就是 7 个子系统：编排、工具注册、记忆、安全闸门、并发调度、观测、评估反馈。把这 7 块认识清楚，你就知道为什么光有 LangChain 或者某个大模型 API 远远不够，也明白为什么网上那些“Agent 项目”容易烂尾——因为多数人只做了其中的一两块，剩下的全靠运气。

1. 别把 Agent 当玩具：为什么非得有个 Harness

1.1 从“会聊天”到“能干活”差在哪

先想一个最日常的场景：你让 Agent 帮你“查一下这周线上订单里有哪些异常”。ChatGPT 这类对话框产品也能回答，但它只会给你一段泛泛的“建议你去看订单系统”。而当 Agent 要真正干活时，它需要做的是：连接数据库、写好查询 SQL、跑定时任务、把结果格式化，再根据异常类型调用不同的处理流程。这一整套动作里有大量外部依赖：数据库连不上怎么办、SQL 语法不兼容怎么办、查出来的数据太大怎么办、权限不够怎么办。

没有 Harness 的 Agent，遇到这些问题就是“死给你看”或者“瞎编一个答案”。有 Harness 的 Agent，至少会做三件事：先告诉你有异常，再按预设的补偿策略重试一次，最后把完整过程和结果送回日志系统供人复盘。这就是“能干活”和“demo 能跑”的分水岭。

1.2 Harness 不是框架，是工程纪律

很多人一听 Harness 就问：“是不是要学 LangGraph，还是用 Dify？”我通常这么解释：LangGraph 这类工具是“骨架”，Dify、Coze 这类平台是“样板间”，而 Harness 是“施工规范 + 水电管线 + 应急通道”的组合。它不一定要你从零写，但你必须理解它由哪些部分组成，否则平台给你的永远是阉割版——你能用里面的编排画布，但看不到工具的登录态管理、看不到队列的积压情况、更看不到 Agent 每一步的真实 token 消耗。

我见过不少团队，先是在低代码平台上拖出一个能跑通的机器人，上线之后发现三个问题：第一，用户量一上来，并发请求直接把上游接口打爆；第二，Agent 在某个业务分支的回复开始重复同样的话，没人发现有 bug；第三，出了重大事故后翻日志，发现根本没有像样的链路追踪。这三件事恰恰就是 Harness 的 7 个子系统要解决的。你绕不开它们。

2. 拆开看：7 个子系统到底管什么

2.1 编排引擎：决定 Agent 下一步干嘛

编排引擎是整个 Harness 的“大脑皮层”，负责维护 Agent 当前的目标、子任务列表、执行顺序和分支切换。它不负责具体干活，只负责“下一步做什么”这件事。

常见的编排方式有两种：一种是图编排，提前把“查订单 -> 分析异常 -> 发提醒”画成有向图，Agent 在节点之间移动；另一种是动态规划，让大模型自己根据目标拆解步骤，每走一步重新评估。前者稳定、可控、适合生产；后者灵活、智能、适合探索。一个成熟的 Harness 通常混合使用：把确定性的流程写死成图，把决策点开放给大模型。

这里有个很反直觉的点：编排引擎不要给 Agent 太多自由。我见过有人让 Agent 自己决定“调用什么工具、按什么顺序”，结果它在循环里绕了 20 轮，token 烧掉一大笔，任务还没完成。正确做法是：把可选项收敛到 3 到 5 个，每个选项都有明确边界和退出条件。这就像新员工入职，公司可以给他流程上的弹性，但不能让他自由到想干嘛就干嘛。

2.2 工具注册中心：给 Agent 一双能干活的手

没有工具的 Agent 只会输出文字，有了工具它才能查库、发邮件、调接口、改工单。工具注册中心就是管理这些外部能力的“插座面板”。

它至少要做三件事。第一，声明：给每个工具写清楚名字、描述、入参出参格式、超时时间、权限等级，这份声明会喂给大模型，让它在做函数调用时有谱。第二，鉴权：工具不是谁都能调的，注册中心要维护调用方的身份和凭证，比如内部 API 的 token、数据库的只读账号。第三，降级：工具挂了不能影响主流程，要有 mock、缓存或人工兜底的方案。

我强烈建议所有工具的描述都用“动词开头 + 限制条件结尾”的模板，比如“查询订单详情，仅支持最近 90 天订单，入参 orderId 是字符串”。别小看这句话，大模型能不能正确选工具，全靠它能不能读懂这段描述。描述写得太泛，Agent 就会在几个工具之间反复横跳；写得太生硬，它又会宁可用猜的也不用工具。

2.3 记忆与状态管理：别让 Agent 失忆

Agent 在干活过程中要记住很多东西：当前订单列表、已经处理到第几页、用户偏好、上一次报错原因。这些内容不能全塞进大模型上下文里，否则几轮下来上下文长度就爆了。Harness 里的记忆子系统要做的是分层管理。

我的实践经验是分三层。第一层叫短期工作记忆，存在 Redis 这类高速存储里，存放当前任务的临时中间结果，TTL 设个 30 到 60 分钟就够。第二层叫业务状态，存在数据库里，记录任务的持久化进度，比如“已发送 32 条通知，剩余 18 条”，这部分要支持崩溃恢复。第三层叫长期记忆，通常做向量化入库，存用户的偏好、历史决策要点、可复用的经验总结。

容易踩的坑是：把长期记忆做得太重，什么都往向量库里塞，结果检索回来的全是无关内容，反而污染了上下文。我一直信奉“少而精”的原则：能放在结构化字段里的，就别塞进自然语言里；能从现有系统查到的，就绝不重复记住。记忆的目的是减少重复劳动，不是替代业务数据库。

2.4 安全与合规闸门：守住底线

Agent 一旦能调工具，就有了实际的影响力，也就有了破坏力。安全闸门不是技术点缀，而是 Harness 里最重要的“刹车片”。

它通常拦在四个位置：工具调用前（检查权限、检查参数合法性）、工具调用后（检查返回内容是否包含敏感信息）、回复用户前（检查输出是否有幻觉、违规、品牌风险）、以及全流程旁路（监控 token 消耗、调用频率、异常模式）。这个子系统要敢拦、敢报错，有些 Agent 的“回答失败”并不是因为模型不行，而是闸门检测到工具调用试图读取不该读的数据，直接给拦下来了。

第二层是“最小权限”。我在公司内部做 Agent 时，任何工具默认只给只读权限，写操作必须走单独的审批流程。别看这一步烦琐，它能救你一命。曾经我们有个 Agent 因为工具描述错误，把测试环境的“删除全部”参数当成了“删除单条”，如果没有权限闸门，后果就是给全量用户发一波测试短信。事后我们立了一条规矩：所有高危操作必须二次确认，且确认操作不能由同一个 Agent 自己完成。

2.5 并发调度与队列：扛并发的核心

网上总有人问“AI Agent 怎么扛并发”，问得多了，你会发现他们其实不清楚问题出在哪。Agent 的并发和普通 Web 服务的并发完全不是一个维度。普通接口并发高，无非是加机器、加连接池；Agent 并发高，意味着大模型 API 限流、工具接口被反复打爆、上下文互相串扰、同一个任务被多个线程同时处理。

Harness 里的调度子系统通常做三件事：全局队列（把每个请求变成一个个可持久化的任务，排队执行，而不是直接开协程裸跑）、并发池（限制同时跑多少个任务，超出就排队，防止上游被压垮）、分批控制（对调用大模型 API 等高频操作做合并、加流控令牌桶）。我会给每个接入的 Agent 定一个最大并发度，比如 5 或 10，再配一个 SaaS API 的 token 消耗预算。

有人觉得排队会拖慢响应速度，其实恰恰相反。在真实业务里，并发一高，如果没有队列保护，你的上游接口会因为超时重试连环雪崩，最后所有请求全挂。有了队列，最坏情况只是等待时间长，但不会让系统崩溃。把任务状态持久化到数据库以后，连“进程重启丢任务”这种事都能避免。

2.6 观测与追踪：出了事能复盘

这可能是 7 个子系统里最不性感、但最不能省的一个。Agent 的执行链路比普通接口长得多：用户请求进来，可能有 20 次大模型调用，20 次工具调用，中间还穿插着记忆读写和分支跳转。一旦出 bug，没有观测系统你根本无从下手。

我做 Harness 时最在意的四类观测数据：第一步，完整 trace，记录“每一步发生了什么、模型返回了什么、工具返回了什么、耗时多少”；第二步，token 账单，每次调用的输入输出 token 数要单独记，月底核算成本就靠它；第三步，质量信号，包括任务是否完成、用户是否点击“不满意”、工具失败率、重试次数；第四步，环境指纹，记录每个请求所依赖的提示词版本、模型版本、知识库版本，不然模型一更新，行为突然变了，你都不知道是哪里变了。

我见过太多团队做 Agent 跟做黑箱一样，出问题就靠“重新跑一遍”。这不是不能解决问题，但效率极低。尤其是当一个任务在 40 多分钟内跨了 6 个服务、调了 9 个工具时，你难道要靠肉眼去看日志？观测系统的价值在事故复盘那一刻会完全体现出来：你能像放电影一样回放 Agent 的每一步决策，比什么都管用。

2.7 评估与反馈闭环：让 Agent 越用越准

Agent 的代码你没法像传统软件那样断言“if A then B”。同一个输入，模型今天可能给 A 回答，明天给你 B 回答。所以 Harness 必须有一个评估子系统，用来回答“这版 Agent 比上版是进步了还是退步了”。

基础做法是建一套评测集，至少放 50 到 100 条覆盖典型业务场景的问题，每条问题配好预期答案或判断标准。每次改动提示词、换模型、调工具描述，就跑一遍评测集，统计通过率、耗时长、调用次数变化。把这三项做成 CI 流程，改动合入前必须达标。

进阶做法是搭一个“反馈飞轮”：线上每个 Agent 执行完，收集用户是否采纳、是否修改结果、是否超时放弃等信息，回流到一个标注池。定期用这些真实负样本补进评测集，让系统持续学习。这一步做得好，Agent 会越来越扎实；不做，Agent 永远停留在“偶尔灵光、经常拉胯”的水平。

3. 实操：一个最小可用 Harness 怎么搭

3.1 先定边界：你的 Agent 到底要干哪几类活

很多人一上来就写代码，结果写完一堆没用。我建议先花一小时回答四个问题：

第一，Agent 的服务对象是谁？是内部运营人员，还是外部用户？这决定了鉴权和闸门的严格程度。第二，它能碰哪些系统？数据库、工单系统、邮件网关，还是只有内部知识库？这决定了工具注册中心里有哪些内容。第三，允许它自主到什么程度？只读建议，还是可以直接执行写操作？这决定了记忆和编排里要不要加“人工确认”步骤。第四，它的 KPI 是什么？是“回答满意度高”，还是“每单处理成本低”？这决定了评估子系统的主指标。

我这边的经验是，第一个落地场景不要贪大，优先选一个“流程重复、数据可查、出错可挽回”的活。比如“自动整理每日销售报表并推送群”就比“自动处理客户投诉”好落地得多。前者数据源单一、输出固定、错了可以人工改；后者要面对自由文本、多轮对话和复杂工单流转，第一版做成那样基本会翻车。

3.2 核心代码骨架：一条流水线跑起来

这里给一个最小示例，用 FastAPI 做 Web 层，用队列和编排模块模拟 Harness 的核心。只示意结构，不依赖具体平台。

# harness.py import asyncio from dataclasses import dataclass, field from enum import Enum from typing import Callable, Any class AgentState(Enum): IDLE = "idle" RUNNING = "running" WAITING_CONFIRM = "waiting_confirm" FAILED = "failed" DONE = "done" @dataclass class AgentTask: task_id: str goal: str state: AgentState = AgentState.IDLE steps: list = field(default_factory=list) context: dict = field(default_factory=dict) retry_count: int = 0 class ToolRegistry: """工具注册中心：每个工具都有声明、鉴权、超时控制。""" def __init__(self): self._tools = {} def register(self, name: str, description: str, handler: Callable, timeout: float = 10.0): self._tools[name] = { "description": description, "handler": handler, "timeout": timeout, } async def call(self, name: str, **kwargs): tool = self._tools.get(name) if not tool: raise ValueError(f"tool[{name}] not found") # 这里可以注入权限检查闸门 return await asyncio.wait_for(tool["handler"](**kwargs), timeout=tool["timeout"])

# main.py from fastapi import FastAPI from harness import ToolRegistry, AgentTask app = FastAPI() registry = ToolRegistry() def build_job_flow(task: AgentTask): # 这里就是编排引擎的核心：按图走流程 # 每个节点返回 (子任务名, 参数)，None 表示结束 yield ("call_tool", {"name": "query_db"}) yield ("llm_analyze", {"prompt": f"任务：{task.goal}"}) yield ("call_tool", {"name": "send_notice"}) yield (None, None) @app.post("/agent/run") async def run_agent(request: dict): task = AgentTask( task_id=request["task_id"], goal=request["goal"], ) for node, params in build_job_flow(task): if node is None: break if node == "call_tool": result = await registry.call(params["name"], **params.get("args", {})) task.context[params["name"]] = result elif node == "llm_analyze": # 调用大模型并记录 token 用量，交由观测系统埋点 task.context["analysis"] = "... model response ..." return {"task_id": task.task_id, "status": "done"}

这段代码不是让你直接抄着上线，而是让你看懂：工具调用收口在注册中心、流程跑在编排器里、任务上下文被显式保存。这三点做到位，后面加并发、加观测就顺理成章了。如果只是把调用大模型 API 写在业务代码里，那就谈不上 Harness，顶多算一个“带提示词的接口”。

3.3 工具接入的两种模式与参数取舍

工具接入千万别走极端。我见过两种典型反面教材：一是所有工具都走同一个内部统一网关，注册声明写得像 JSON Schema 一样晦涩，结果大模型经常选错；二是每个工具各写各的 SDK，日志格式、错误码、超时时间全都不一样，出问题后排查成本极高。

我的折中方案是：所有工具必须统一三个东西。第一，错误返回格式，一律返回{"code": 0, "data": ...}或{"code": 4001, "message": "..."}，Agent 会依据 code 判断是否重试。第二，超时时间，默认 5 秒，超过就认为是工具故障，不再重试，直接走降级分支。第三，鉴权方式，内部服务全走同一个 Service Token，外部 SaaS 接口单独在注册中心里配凭据。

还有个小技巧：工具入参一律用扁平结构，不要嵌套太深。比如查询订单，就传{"order_id": "xxx", "time_range": "7d"}，别传一个复杂的嵌套对象。大模型的函数调用对扁平参数的把握远比嵌套结构好，嵌套一深，它非常容易把字段位置搞错。

3.4 并发调度和限流怎么配

给你一个完全可以照搬的配置办法。第一步，给每个 Agent 任务类型建一张队列表，字段至少包括：task_id、status、priority、created_at、updated_at、payload。第二步，后台起一个 worker 池，每个 worker 从队列里拉取这个类型的任务，数量控制在 1 到 5 之间。第三步，在调外部工具和大模型 API 的地方加一个令牌桶，比如每分钟允许 100 次大模型调用，超出就等待。

# queue_worker.py import asyncio from collections import deque class TokenBucket: def __init__(self, rate: float, capacity: float): self.rate = rate self.capacity = capacity self.tokens = capacity self.updated_at = asyncio.get_event_loop().time() async def acquire(self): while True: now = asyncio.get_event_loop().time() self.tokens = min( self.capacity, self.tokens + (now - self.updated_at) * self.rate ) self.updated_at = now if self.tokens >= 1: self.tokens -= 1 return await asyncio.sleep(0.1) # 示例：限制大模型 API 调用频率 llm_limiter = TokenBucket(rate=50, capacity=20)

# worker.py async def worker_loop(queue: deque, registry: ToolRegistry): while True: if not queue: await asyncio.sleep(0.5) continue task = queue.popleft() try: # 执行编排 await execute_task(task, registry) except Exception as exc: # 记录到观测系统，触发重试或告警 log_error(task.task_id, exc)

把这个结构跑起来之后，你会发现并发从“玄学”变成了“排队学”。你不再害怕流量突增，因为队列本身就是母牛，上游扛不住时就地多排一会儿队。你也能放心重启服务，因为任务状态在数据库里，不会因为进程退出就丢。

4. 踩坑实录：Harness 真正难在哪儿

4.1 工具调用失败：别让 Agent 在同一个坑里摔三次

第一个坑就是工具报错后 Agent 直接“傻掉”。你让它查订单，订单表字段名配错了，数据库报“未知列 order_n”。普通代码会立刻抛异常并停止，Agent 大模型则会一本正经地告诉你“抱歉，订单系统异常”，既不告诉你异常原因，也不尝试修复。

Harness 的正确姿势是“有限重试 + 反馈修正”。第一步，工具返回错误后，把错误信息注入模型上下文：“你刚才调 get_order 失败，原因是参数 xxx 不存在，请修正后重试。”第二步，最多重试 2 次，超过就放弃，转人工。第三步，如果错误来自 Agent 自己乱传参，就把这次失败记录成样本，进评估集，下次调整工具描述。

这个方案看似简单，但很多团队做不到，因为他们压根没把“工具失败的返回”当成一种需要引导 Agent 的信号，直接就硬编码“调工具失败就报错”。结果 Agent 永远学不会自己修正，只能写得死板或者失控。

4.2 上下文爆炸：记忆到底该存什么

第二个高频坑是长期记忆系统“用了个寂寞”。最常见的情况是：项目方把用户每一轮对话都塞进向量库，表面上做了“持久记忆”，实际检索回来的片段全是相似废话，模型上下文被无关信息塞满，回答质量不升反降。

我的办法是把记忆按“结构化优先”来组织。如果用户说“帮我每周五早上 9 点发周报”，那就不要记那句自然语言，而是抽成结构化配置：{"schedule": "0 9 * * 5", "task_type": "weekly_report", "dest": "group@xx.com"}。只有当信息无法被结构化表达时，比如“用户偏好更简洁的文风”，才放进向量库。

还有一个被忽略的点：记忆要设“遗忘机制”。不是所有内容都值得长期保存，我一般给长期记忆加一个有效期，比如业务偏好 6 个月后过期，敏感信息只留三个月并脱敏。这里的核心思路是：记忆是资源不是资产，越少越精，效果反而越好。

4.3 并发场景状态错乱：共享变量是万恶之源

这年头你只要做几个高并发场景，大概率会遇到“用户 A 的查询结果跑到用户 B 的回复里”这种灵异事故。十有八九是代码里用了全局变量存上下文，或者 Python 协程间共享了同一个可变对象。

我之前带一个项目，Agent 任务进来先塞进全局task_context = {}，刚开始没问题，一旦并发上来，两个任务同时写同一个 key，后写覆盖先写，A 的订单状态就跑到 B 的上下文里去了。排查了半天才发现问题不在模型，而在这行看似人畜无害的字典。

正确做法很简单：任务上下文作为不可变快照传递，或者在任务实例内部持有，不要搞任何全局可变状态。每个任务上下文只允许在编排器里被主动更新，并且用 task_id 做隔离。你在代码里用AgentTask.context而不是global_context，就避开了这个坑。

4.4 观测缺失：Agent 出了错根本没法查

第三个坑，也是最现实的坑：很多 Agent 项目直到上线都没认真做 trace。在 demo 阶段无所谓，出了问题重新跑一遍就行。上线后就不行了，半夜两点用户反馈机器人发错了通知，你爬起来，发现日志里只有一行“error: internal error”，没有任务 id、没有输入输出、没有模型消耗记录。

我后来立了规矩，所有 Agent 执行必须留三类痕迹：开始痕迹（task_id、goal、初始参数）、过程痕迹（每一步的模型输入输出、工具调用入参出参、耗时）、结束痕迹（成功或失败、最终 token 数、人工干预标记）。不用搞得多花哨，存成 JSON 日志，落盘到日志服务里就行。没有这些，你后面连“Agent 变笨了”这类问题都没法定位，因为你连它之前是怎么回答的都不知道。

5. 什么项目才值得上 Harness

5.1 项目分级：不是所有 Agent 都要上全套

别看完 7 个子系统就被吓住了，不是每个场景都值得做成完整 Harness。我的分级是老办法：只有“要给外部用户用、要跑核心流程、出错成本高”的 Agent 才值得全套投入。做一个内部知识库问答机器人，把记忆、编排、安全闸门做扎实，并发调度都可以缓一缓；做一个自动发营销邮件的机器人，如果没有审批闸门和审计日志，分分钟出合规事故。

我把项目分为三级。第一级是“玩具级”，自己玩玩、单用户、失败无影响，只需要一个编排和基础记忆。第二级是“工具级”，给团队内部使用、允许少量人工干预，需要加上工具注册和安全闸门，再做一个简单观测。第三级是“生产级”，面向真实用户、对接多种外部系统、需要 7×24 小时稳定，这时候 7 个子系统一个都不能少，还要加监控告警和故障转移。搞清楚自己的项目在哪一级，再决定资源投入，比盲目抄别人架构重要得多。

5.2 个人和小团队怎么低成本起步

如果你是一个人或者小团队，刚开始没必要自研全套。我的路线是：先用低代码平台（比如 Coze 或者 Dify）把业务流跑通，确认“Agent 做事”这个方向有真实价值；然后对暴露出来的问题做砍需求式开发，把核心流程迁移到自己代码里；最后才按 7 个子系统补齐短板。别一上来就吭哧吭哧写框架，等写完了业务也凉了。

个人开发者最划算的做法是“模块替代”。并发调度直接用 Redis 队列；观测直接接一个现成的追踪服务；工具注册中心自己用几十行代码抽象就算完事。一个真正够用的最小 Harness 代码量其实不大，难的是你想清楚每个子系统的边界，以及出了问题往哪个模块去查。

5.3 再往前走：RPA、多 Agent 协作与泛化

Harness 的价值还有更大的想象空间。比如和 RPA 结合，让 Agent 负责判断和拆解，RPA 负责执行鼠标键盘级操作，Harness 则统一管理两者的状态流转和异常补偿。这种“Agent 做脑、RPA 做手”的组合，在批处理打印、跨系统数据搬运这类场景中特别实用。

多 Agent 协作时，Harness 更是刚需。两个 Agent 协作完成任务，本质是一个流程编排问题：谁先做、谁的后置依赖谁、结果怎么汇聚。没有 Harness，你搞多 Agent 协作会遇到“Agent A 等 B，B 也在等 A”的循环等待，或者两边各改各的上下文最终对不上账。有了外部调度和共享状态，多 Agent 协作从“聊天群”变成了“流水线”。最后我个人的体会：别沉迷于“让 Agent 更像人”，先把“让它像一台可靠机器”这件事做好，Agent 才有机会真正站在生产环境里。

如果真要我给一句总结性的经验，那就是：Harness 做的是减法，让 Agent 不犯错、不乱跑、有兜底、可追溯。这 7 个子系统看着多，实际上一环扣一环，从编排到评估，全都在为同一个目标服务——让 AI 从“会对话的模型”变成“能交付的劳动力”。你先记住这个目标，再回头看那些热词里飘着的一堆框架和名词，就不会再迷茫了。