gov-agents · 业务方构建 Agent 完整教程
5 天 · 从选型到 Portal KPI。实操主文档：Day 02 独立仓逐步改文件 · Day 03 Monorepo 逐步改文件（含改前改后示例 + 验证命令）。
开篇 · 你要交付什么
这份教程和 框架源码 21 天 不同：不教你读 toolkit 源码，而是教业务团队怎么把自己的场景做成一个可上线、有 KPI 的 Agent。
🎯 你交付的 = LangGraph 业务图 + Prompt + 下游 client + 评测样本 + 效果指标。 Critic 防幻觉、成本熔断、invoke envelope、case 持久化——平台 ai-trust-toolkit 包好，你不重复造。
三种交付形态（可叠加）：CLI（本机跑 · 数据不出门）· MCP（Cursor/Claude Code 一键调）· Pod（HTTP 被系统/定时任务调用）。活范例：bmc-agent（独立仓 CLI+MCP）· biz-link-gov-agent（Monorepo Pod）。
文件地图 · 每步改哪个文件
builder.py 在 Python 包根（如 my_agent/builder.py），与 nodes/ 平级。nodes/ 目录下只有节点函数（如 run.py），没有 builder.py。详细逐步对照表：
- 独立仓 9 步 × 文件 → Day 02 对照表
- Monorepo 步骤 × 文件 → Day 03 对照表
- 业务文件逐一说明 → Day 04 文件详解
| 文件 | 独立仓路径示例 | 干什么 |
|---|---|---|
| builder.py | my-agent/my_agent/builder.py | 串 LangGraph（add_node/edge） |
| nodes/run.py | my-agent/my_agent/nodes/run.py | 单节点业务逻辑 |
| state.py | my-agent/my_agent/state.py | 图共享字段 |
| core.py | my-agent/my_agent/core.py | 跑图 + telemetry |
| server.py | my-agent/my_agent/server.py | Pod HTTP（独立仓）/ build_v1_router（Monorepo） |
三层架构 · 你写哪层
发光小球 = 一次请求从上往下穿过各层。业务方 90% 精力在 L3；L2 通过 BOM 一行依赖接入。
两条接入路径 · 先选对
路径 A · 独立仓（推荐大多数业务方）
- 不需要 gov-agents-platform 仓权限
- 模板直链 / Portal 下载 zip 起仓
- Nexus 拉
ai-trust-toolkit-bom[core] - 自己 git 仓迭代 · 发 Nexus · obelisk 部署
- 范例：
bmc-agent
路径 B · 平台 Monorepo
- 需要平台仓 MR 权限
agentctl new/ agent-creator / cp 老 agent- 全仓 3 处必改：workspace + AGENT_REGISTRY + AGENT_META
build_v1_router挂标准 API- 范例：
sre-rca-agent·biz-link-gov-agent
选型决策树 · 4 问定路线
Skill vs Agent？独立仓 vs Monorepo？跟现有 15+ agent 重复吗？手动 / 向导 / AI 生成哪种起手？
Skill 实战 · AI 资讯每日播报
按 standalone-repo-agent Skill 安装 → Cursor 触发 → 9 步引导 · Demo ai-daily-news · Marketplace CLI + 终端截图。
路径 A · 独立仓接入【实操主文档】
9 步逐步操作：每个文件改前/改后代码、builder 位置说明、每步验证命令。示例：回声 bot → 三步摘要 bot。
路径 B · Monorepo 接入【实操主文档】
脚手架 → 3 处注册怎么写 → server.py 三处映射 → evals + e2e。业务节点改法链到 Day 02。
业务图开发 · 核心代码
State / builder / specialists / tools / prompts · get_llm 铁律 · Critic L1 · 下游只读 client · 多 Agent 编排入门。
评测 · 安全 · 上线 · KPI
≥20 条样本 · FakeLLM 测试 · 安全自检 7 问 · canary 灰度 · record_effect 上报 Portal。
📎 独立仓想更细？番外 独立仓 9 步手把手 是 Day 02 的深化版（含时间线动画 + 三大坑）。框架原理？去 源码 21 天。