从 Demo 到生产：那些真正让 AI Agent 敢上线的护栏

开场钩子： 你在网上看到的多数「AI Agent」都是 demo。它们之所以上不了生产，原因往往 只有一个 —— 而下面这个开源的小脚手架，专门解决它。

我们已经过了「能调通大模型」就算赢的阶段。现在真正难的是那没人讲的 10%：是什么阻止 Agent 做出伤害性的事？ 我在微软跑过一套约 25 个 Agent 的生产平台，现在也帮团队把 Agent 从笔记本推进到真实用户面前。两边的体会是一致的。

一个不太舒服的真相：能调 5 个工具的聊天机器人，不是产品。周末项目和你敢放到客户面前的 系统之间，差的只有三件事 —— 而且全都是不酷、不性感的工程：

  1. 你怎么给输出质量打分（质量门）。
  2. 你怎么决定什么时候必须人签字（审批门）。
  3. 你如何让整套东西模型无关，不被某个厂商锁死。

所以我写了一个很小的 harness，把这三件事摆在最显眼的位置。它故意做得很小 —— 一小时能 读完 —— 因为价值不在「框架」，在模式本身。

仓库：github.com/zhasun0818/ai-agent-scaffold

1. 质量门：别发布你无法打分的东西

Agent 的输出是「预测」不是「承诺」。上线前它必须过一道检查：是否达到你的标准。脚手架里 这是一个可插拔的 QualityGate，你可以换成 LLM 裁判或测试套件：

# agent_harness/eval.py
@dataclass
class EvalReport:
    passed: bool
    score: float
    checks: List[str]

class QualityGate:
    def grade(self, proposal: str, context: str = "") -> EvalReport:
        return self.grader(proposal, context)

循环在门没过之前拒绝执行：

result.report = self.quality.grade(proposal, f"state={state}")
if not result.report.passed:
    self.approval.log("quality-gate", "blocked", result.report.__str__())
    return result

注意它把拦截记录下来了。生产里你会想把这些被拦的尝试都进可观测性系统。「这周我们拦下 了 12% 的 Agent 提议」是个真实 KPI —— 它说明门在工作。

2. 审批门：所有人都忘掉的那一步

这才是让企业真正点头说「可以」的东西。当 Agent 想加急订单、取消订阅、或动钱的时候，它应该 停下来问人。沉默不等于同意。

# agent_harness/approval.py
class ApprovalGate:
    def request(self, action: str, detail: str) -> bool:
        # 生产里：推一条通知到 Teams / Slack / 邮件，然后等待。
        decision = input(f"Approve {action}? [y/N] ").strip().lower()
        self.audit.append(AuditEntry(time.time(), action, "human-reviewer", decision, detail))
        return decision.startswith("y")

在脚手架里，标记 needs_approval=True 就够了：

@tool("expedite_order", "Mark an order as expedited.", needs_approval=True)
def expedite_order(order_id: str) -> str:
    return f"PO {order_id}: marked expedited"

而且因为有审计链，你永远能回答「谁改的、为什么」—— 这通常是合规团队问的第一个问题。

3. 模型无关的 provider：别跟一个厂商结婚

模型每几周就变，价格也是。你的 Agent 循环不该知道自己在对谁说话：

# agent_harness/providers.py
class ModelProvider(Protocol):
    def complete(self, messages: List[Message], tools: Dict[str, Any]) -> str: ...

agent = Agent(provider=default_provider("openai"))   # 或 "deepseek", "qwen", "mock"

几行抽象，你就能在 OpenAI、Azure OpenAI、DeepSeek、Qwen 之间切换，还能用一个不需要 key 的 MockProvider 离线跑整条链路。这不只是工程卫生，更是成本杠杆和避险。

4. 业务流程是状态机，不是聊天循环

另一个大模式：别让「Agent」在你的关键流程上自由发挥。把工作流显式建模。下面是一个采购订单 异常的状态机 —— 每个供应链 / ERP copilot 都会遇到的东西：

# agent_harness/state_machine.py
class State(str, Enum):
    OPEN = "open"; EXPEDITED = "expedited"; CANCELLED = "cancelled"
    EXECUTED = "executed"; CLOSED = "closed"

class POStateMachine:
    def transition(self, target: State, reason: str = "") -> State:
        if target not in TRANSITIONS[self.state]:
            raise InvalidTransition(f"{self.state} -> {target}")
        self.state = target
        return self.state

open ──► expedited ──► executed ──► closed
  │          ▲              ▲
  └──exception──┘  （中间是人工审批门）

Agent 提议一个迁移；状态机强制执行什么是合法的；任何有后果的动作都要人批准。这就是 「有控制的自主性」—— 企业最想听到的那个词。

串起来

agent = Agent(provider=provider, registry=registry,
              approval=ApprovalGate(), quality=QualityGate())
sm = POStateMachine(po_id="PO-1234")
result = agent.run("PO-1234 is stuck; expedite it.", state=sm)
print(result.audit)

拉下来，不需要任何 API key 就能跑：

python examples/po_workflow.py --yes

你会看到质量门通过 → 人批准 → 订单加急 → 状态迁到 expedited → 全程记进审计链。这就是约 300 行代码跑出来的、真正生产形态的流程。

结论

你要做 Agent，就先做护栏。它决定你拿到的是一张截图的 demo，还是一个企业真敢信任的系统。 如果你不想自己搭 —— 或者想找个在微软尺度上真跑过这玩意的人 —— 来找我。

MIT 开源。拿去 fork，拿去造，顺便打个招呼。

关于作者：我是孙兆伟，AI Agent / Copilot 工程师，在微软做过并跑过生产级 Agent 平台，在 Hulu 做过高并发系统。我做 Agent 架构咨询，并维护这个仓库 —— 它是我希望当初就有的脚手架。

标签： AI Agents, LLM, RAG, Microsoft Copilot, Software Architecture, System Design

建议发布平台： Dev.to | Medium | LinkedIn | 掘金（本版）| 开源中国