跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 12

12-02|企业 AI Agent 应该交付哪些东西

把代码、架构、测试、安全、部署、演示和交接材料组合成可运行、可验收、可维护的交付包。

Enterprise Delivery · Documentation · Portfolio

一个在线 Demo 不能代表完整交付

企业接手系统时会问:代码在哪里,怎样启动,使用什么数据,权限怎样控制,失败如何恢复,哪组测试证明它可用,谁维护知识库,哪些功能仍是 Mock。只有演示视频或聊天截图,无法回答这些问题。

最终交付包

可运行资产

Agent 项目 · 在线/本地 Demo · GitHub Repository · README

架构与数据

系统架构图 · Workflow · Tools · API/MCP · 数据与知识库设计

可信工程

权限与安全设计 · Eval/Reliability Report · Security Report

运行交接

部署说明 · Config/Secret 清单 · Monitoring · Rollback · Runbook

展示资产

Demo Script · 截图/视频 · Enterprise Case Study

图 1|交付包覆盖运行、设计、证据、维护和沟通,而不只是一份源代码。

README 是入口:解释业务问题、能力边界、架构、快速启动、测试命令、演示账号、已知限制和文档索引。详细设计可以拆分,但入口必须让新接手者知道从哪里开始,以及哪些前置资源需要另行申请。

证据如何串起来

Requirement ID
↓
Architecture Decision + Owner
↓
Implementation Version
↓
Test Case + Trace + Audit
↓
Report + Acceptance Sign-off
↓
Runbook + Change History

图 2|文档之间通过稳定 ID 和版本关联,客户才能验证结论并继续维护。

“系统支持安全退款”需要具体证据:需求编号、退款 State Machine、Approval Contract、对象级授权测试、重复执行测试、Security Report 和部署版本。截图可以帮助展示,但不能代替可重复测试和机器可读结果。

交接时明确四种状态

Implemented + Tested
已经实现,并通过列明环境和版本的测试
Demo / Mock
流程可演示,业务系统或数据为模拟
Designed
架构和接口已定义,尚未完成实现
Out of Scope
当前版本明确不承担,说明原因和后续条件
图 3|准确标注完成度能保护客户决策,也提升作品可信度。

作品集描述同样遵守事实边界。可以写“我设计了退款 Workflow、Tool Contract 与安全测试;使用 Codex 协助实现;在 Mock 数据集上通过 49 个用例”。如果没有连接真实 Shopify、没有生产流量和正式安全评审,就明确写出这些限制。

Failure Lab

交付一个能跑的仓库就结束

为什么诱人: 源代码是最具体的成果,开发者也最熟悉。

为什么失败: 客户无法判断配置、数据、风险、验收状态和故障处理责任。

更合理设计: 代码与架构、测试证据、部署、Runbook、限制和交接清单一起交付。

报告里只放成功截图

为什么诱人: 页面简洁,演示效果好。

为什么失败: 截图缺少输入、版本、断言和失败边界,无法重复验证。

更合理设计: 截图用于沟通;Case Result、Trace、Report 和版本记录用于验收。

隐藏 Mock 与未完成功能

为什么诱人: 项目看起来更接近商业成品。

为什么失败: 客户会基于错误前提评估风险,后续交接也会立即暴露差距。

更合理设计: 使用状态标签明确 Implemented、Mock、Designed 和 Out of Scope。

实践:执行 Delivery Package Audit

对照 10 项最终交付物,逐项记录路径、版本、Owner、完成状态、验证方法和已知限制。让一个不了解项目的人只看 README 与文档索引,尝试启动 Demo、运行测试、定位一次失败并找到回滚步骤。

Acceptance Criteria

  • ☐ Repository 与 README 能解释问题、边界、架构、启动、测试和文档入口。
  • ☐ 架构图覆盖 Workflow、Tools、API/MCP、数据、RAG、权限和部署。
  • ☐ Reliability 与 Security 报告可追溯到 Case、Trace 和版本。
  • ☐ 部署说明包含 Config、Secret、数据、Health、Monitor 和 Rollback。
  • ☐ Demo Script 同时展示成功、失败、审批和越权拒绝。
  • ☐ Enterprise Case Study 记录需求、判断、实现、证据、结果和限制。
  • ☐ 每项能力标明 Implemented、Mock、Designed 或 Out of Scope。
  • ☐ 文档说明个人设计、Codex 协助与实际测试范围。

主动回忆

  1. 为什么 README 应该成为交付入口?
  2. 截图和可重复测试分别承担什么作用?
  3. 一个功能要怎样从需求追溯到验收证据?
  4. 准确披露 Mock 和限制为什么会增强可信度?

下一课进行 Final Challenge:独立完成需求判断、架构、测试、部署与交付说明。

延伸阅读 / Sources

核查日期:2026-10-18。

长期有效的原理: 企业交付需要可运行资产、可追溯证据、运行责任和限制说明。当前实现方式: 文档工具与部署平台会变化,交付索引和状态声明应长期维护。