DEV Community: sunny 1024k

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

sunny 1024k — Sun, 23 Aug 2026 15:41:42 +0000

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

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

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

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

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

所以我写了一个很小的 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 | 掘金（本版）| 开源中国

From Demo to Production: The Guardrails That Make an AI Agent Safe to Ship

sunny 1024k — Sun, 23 Aug 2026 15:41:29 +0000

From Demo to Production: The Guardrails That Make an AI Agent Safe to Ship

Hook: Most "AI agents" you see on the internet are demos. Here's the single most common
reason they never reach production — and a small, open-source harness that gets past it.

We are past the phase where the hard part of building an AI agent was calling the model.
The hard part now is the 10% nobody talks about: what stops the agent from doing something
harmful? I've seen this from both sides — I built and ran a ~25-agent platform in production
at Microsoft, and now I help teams take agent ideas from a notebook to real users.

The uncomfortable truth: a chatbox that can call 5 tools is not a product. The difference
between a weekend project and a system you can put in front of customers is three things —
and they're all boring, non-glamorous engineering:

How you grade output quality (the quality gate).
How you decide when a human must sign off (the approval gate).
How you make the whole thing model-agnostic so you're not locked into one vendor.

So I wrote a tiny harness that keeps these front and center. It's intentionally small — small
enough to read in an hour — because the value isn't in a framework, it's in the pattern.

Repo: github.com/zhasun0818/ai-agent-scaffold

1. The quality gate: don't ship what you can't grade

An agent's output is a prediction, not a promise. Before it ships, you need a check that
it passes your bar. In the harness this is a pluggable QualityGate — a rule of thumb you swap
with an LLM judge or a test suite:

# 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)

The loop refuses to execute if the gate fails:

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

Notice it logs the block. In production you'd want every blocked attempt in your
observability stack. "We rejected 12% of agent proposals this week" is a real KPI — it means
the gate is doing its job.

2. The approval gate: the step everyone forgets

This is the one that actually gets enterprises to say yes. When an agent wants to expedite
an order, cancel a subscription, or move money, it should stop and ask a human. Silence is
not consent.

# agent_harness/approval.py
class ApprovalGate:
    def request(self, action: str, detail: str) -> bool:
        # In production: push a notification to Teams / Slack / email and wait.
        decision = input(f"Approve {action}? [y/N] ").strip().lower()
        self.audit.append(AuditEntry(time.time(), action, "human-reviewer", decision, detail))
        return decision.startswith("y")

In the scaffold, marking a tool needs_approval=True is enough to route it through the gate:

@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"

And because there's an audit trail, you can always answer "who changed this and why?" —
which is usually the first question a compliance team asks.

3. Model-agnostic providers: don't marry one vendor

Models change every few weeks, and so do prices. Your agent loop should never know which
vendor it's talking to:

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

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

A few lines of abstraction mean you can run the same agent on OpenAI, Azure OpenAI, DeepSeek,
or Qwen with a config change — and test the whole thing offline with a MockProvider that
needs no API key. That's not just engineering hygiene, it's a cost lever and a hedge.

4. Business workflows are state machines, not a chat loop

The other huge pattern: don't let an "agent" freewheel over your critical process. Model the
workflow explicitly. Here's a purchase-order exception state machine — the kind of thing that
shows up in every supply chain / 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──┘  (human approval gate in between)

The agent proposes a transition; the state machine enforces what's legal; a human approves
anything consequential. That's how you get autonomy with control — the exact phrase
enterprises want to hear.

Put it together

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)

Pull the repo and run it with no API key:

python examples/po_workflow.py --yes

You'll see the quality gate pass, the human approve, the order get expedited, the state move to
expedited, and the whole thing recorded in the audit trail. That's a real production-shaped
flow in ~300 lines.

The takeaway

If you're building an agent, build the guardrails first. It's the difference between a
demo you screenshot and a system your business actually trusts. And if you don't want to build
it yourself — or want someone who's shipped this at Microsoft scale — get in touch.

Open-sourced under MIT. Fork it, build on it, and say hi.

About the author: I'm Zhaowei Sun, an AI agent / Copilot engineer who's built and run
production agent platforms at Microsoft and high-scale systems at Hulu. I consult on agent
architecture, and I keep this repo as the scaffolding I wish I'd had.

Tags: AI Agents, LLM, RAG, Microsoft Copilot, Software Architecture, System Design

Suggested platforms: Dev.to | Medium | LinkedIn | Hacker News (Show HN) | 掘金 (translated)