| name | agent-dev-workshop |
| description | 交互式 AI Agent 开发工作坊：通过 6 阶段深度协作对话，引导用户完成 Agent 需求分析、架构设计、 工具定义、Prompt 与编排设计、代码生成、验证迭代，产出可直接运行的 Agent 项目。 框架无关设计优先，支持 LangChain / EINO / AutoGen / AgentScope / CrewAI 等 ADK 框架。
|
| origin | ECC |
Agent Dev Workshop
交互式 AI Agent 开发工作坊。用户通过深度协作式对话，逐阶段完成 Agent 设计并生成可直接运行的项目代码。
何时激活
- 用户说"开发 agent"、"创建 agent"、"构建 agent"、"agent 开发"
- 用户要基于 EINO / LangChain / AutoGen / AgentScope / CrewAI 创建 Agent 应用
- 用户要将已有 Agent 迁移到另一个框架
- 用户说"agent dev"、"build agent"、"create agent"、"develop agent"
/agent-dev 命令入口
三种运行模式
默认模式（深度协作）
完整 6 阶段交互流程。每个阶段结束必须用户确认后才推进到下一阶段，每个工具/组件逐一交互确认。
快速模式（--quick）
用户给一句话需求 → 自动执行 Phase 1-4（推断 Agent 类型、匹配架构模式、生成默认工具和 Prompt）→ 仅在 Phase 5 代码生成后做一次整体确认 → Phase 6 验证。适合有经验用户或原型快速验证。
快速模式约束：
- 自动推断时，选择最常见的默认值（如：单 Agent 默认 ReAct，多角色默认 Multi-Agent Conversation）
- 框架选择依据用户指定语言自动匹配（Python → LangChain，Go → EINO，未指定 → LangChain）
- 生成后必须完整展示项目结构和核心文件内容，等待用户确认
导入模式（--import）
用户指定已有 Agent 代码路径：
- 分析现有代码：识别框架、Agent 类型、工具列表、Prompt、编排逻辑
- 生成
agent-spec.md（逆向提取）— 展示给用户确认
- 用户确认：确认提取结果 + 选择目标框架
- 跳转 Phase 5：用目标框架重新生成代码
- Phase 6：对比验证原 Agent 行为是否保留
导入模式约束：
- 必须列出代码分析中的不确定项，让用户确认
- 原 Agent 的所有工具必须在新框架中保留等效实现
- 生成 diff 摘要：原框架 vs 目标框架的关键差异
严格约束
- 每个阶段必须用户确认后才能进入下一阶段。严禁静默推进。
- 每个阶段开始前，先读取
references/phase{N}-*.md 获取该阶段详细指引。
- 遇到需求冲突或不明确的约束，立即暂停并提问，不自行推测。
- 每个阶段的核心产出必须立即写入磁盘，不允许仅停留在对话上下文中。
- 代码生成阶段（Phase 5），必须读取
adk-framework-adapters 对应框架的 reference 文件后再生成代码。
- 框架适配 reference 文件标注了
verified_date，若距今超过 90 天，应提醒用户 API 可能已变化。
工作方式
- 阶段驱动：按 Phase 1 → 6 顺序推进，每阶段有明确的输入、活动、产出和确认点。
- 追踪表：在 Phase 1 结束后创建
{output_dir}/tracking.md，每个阶段完成后更新状态。
- 引用 reference：每个阶段开始前，读取对应
references/phase{N}-*.md 获取详细引导。
- 立即落盘：每个阶段的产出文件在完成后立即写入
{output_dir}/，并展示给用户确认。
- 跨 skill 调用：Phase 2 调用
agent-patterns-catalog 匹配架构模式；Phase 5 调用 adk-framework-adapters 加载框架模板。
阶段概览
| Phase | 名称 | 核心活动 | 产出文件 | Reference |
|---|
| 1 | 需求发现 | 业务场景、Agent 类型、框架、约束 | agent-spec.md | references/phase1-discovery.md |
| 2 | 架构设计 | 架构模式匹配、组件拓扑、数据流 | agent-architecture.md | references/phase2-architecture.md |
| 3 | 工具与能力 | 工具定义、Memory 策略、RAG pipeline | agent-tools.md | references/phase3-tools.md |
| 4 | Prompt 与编排 | System Prompt、编排逻辑、路由策略 | agent-prompts.md + agent-orchestration.md | references/phase4-prompts.md |
| 5 | 代码生成 | 框架代码、项目结构、配置、脚本 | 完整项目目录 | references/phase5-codegen.md |
| 6 | 验证迭代 | 依赖安装、测试、Smoke Test、迭代 | 验证报告 | references/phase6-verification.md |
输出目录规范
{agent-name}/ # 项目根目录（Phase 5 生成）
├── README.md
├── pyproject.toml / go.mod / package.json
├── .env.example
├── src/
│ ├── agent.py / agent.go / agent.ts
│ ├── tools/
│ ├── prompts/
│ ├── memory/
│ └── orchestrator/ # multi-agent 时
├── tests/
├── configs/
└── scripts/
└── run.sh
docs/agent-dev/ # 设计文档目录（Phase 1-4 生成）
├── tracking.md # 进度追踪表
├── agent-spec.md # Phase 1
├── agent-architecture.md # Phase 2
├── agent-tools.md # Phase 3
├── agent-prompts.md # Phase 4
└── agent-orchestration.md # Phase 4
Phase 1: 需求发现（Discovery）
交互方式: 深度对话 + 结构化提问
活动:
- 用户描述 Agent 要解决的业务场景
- 引导确认：目标用户、核心能力、输入/输出、成功标准
- 确定 Agent 类型（提供选项）：
- ReAct Agent（推理+行动循环）
- Multi-Agent 协作（多角色对话/编排）
- RAG Agent（检索增强生成）
- Tool-Use Agent（工具调用链）
- Workflow Agent（固定流程编排）
- Autonomous Agent（自主规划+执行）
- 确定目标框架偏好（或根据场景推荐）
- 确认约束：部署环境、编程语言、LLM provider、外部依赖
- 导入模式入口：如果用户有已有 Agent 代码，先分析代码再提取 spec
产出: agent-spec.md
- Agent 名称、描述、类型
- 核心能力列表
- 输入/输出契约
- 目标框架 + 编程语言
- LLM provider + 模型
- 约束与外部依赖
- 成功标准
确认点: 用户审批 agent-spec.md 后进入 Phase 2
Phase 2: 架构设计（Architecture）
交互方式: 展示架构方案 + Mermaid 图 + 用户确认/调整
活动:
- 读取
agent-patterns-catalog 中对应 Agent 类型的参考架构
- 设计组件拓扑：Agent Core → Memory → Tools → LLM → Orchestrator
- Multi-Agent 场景：角色拆分、通信拓扑（星型 / 链式 / 网状 / 层级）
- RAG 场景：检索策略、向量存储选型、chunk 策略
- 生成 Mermaid 架构图
- 列出关键设计决策及其理由
产出: agent-architecture.md
- 架构模式名称与简述
- 组件拓扑图（Mermaid）
- 组件职责表
- 数据流描述
- 关键设计决策
- Multi-Agent 场景的角色定义（如适用）
确认点: 架构确认后进入 Phase 3
Phase 3: 工具与能力定义（Tools & Capabilities）
交互方式: 逐个工具交互确认
活动:
- 根据 agent-spec 和 architecture 列出所有需要的工具（Tool）
- 每个工具逐一确认：
- 名称（name）
- 描述（description）
- 输入参数 schema（JSON Schema 格式）
- 输出 schema
- 实现策略（API 调用 / 数据库查询 / 文件操作 / 自定义逻辑）
- 定义 Memory 策略：
- 类型（conversation_buffer / entity / summary / vector）
- 存储后端（in-memory / Redis / SQLite / 向量数据库）
- 窗口大小或 token 限制
- RAG pipeline 定义（如适用）：
- 数据源（文件 / API / 数据库）
- Embedding 模型
- 向量存储（FAISS / Chroma / Milvus / Weaviate）
- 检索策略（similarity / MMR / hybrid）
- Chunk 策略（大小 / 重叠 / 分隔符）
产出: agent-tools.md
- 工具清单表（name / description / input / output / strategy）
- Memory 配置
- RAG pipeline 定义（如适用）
- 外部依赖清单
确认点: 全部工具定义确认后进入 Phase 4
Phase 4: Prompt 与编排设计（Prompt & Orchestration）
交互方式: 展示 prompt 草稿 + 用户迭代修改
活动:
- 设计 System Prompt：
- 角色定义
- 行为约束与规则
- 输出格式要求
- 可用工具说明
- 设计编排逻辑：
- 单 Agent：执行循环（max_iterations / 终止条件）
- Multi-Agent：状态机 / DAG / 对话轮次 / 投票机制
- Workflow：阶段定义 / 条件分支 / 并行节点
- Multi-Agent 特有：
- 每个角色的 prompt
- 路由策略（round-robin / LLM-based / rule-based）
- 终止条件
- 错误处理与兜底策略
- Few-shot examples（如需要）
产出:
agent-prompts.md：所有 prompt 全文agent-orchestration.md：编排逻辑 + Mermaid 流程图 + 路由规则 + 错误处理
确认点: Prompt 和编排逻辑确认后进入 Phase 5
Phase 5: 代码生成（Code Generation）
交互方式: 生成代码 + 逐文件审查确认
活动:
- 读取
adk-framework-adapters 中目标框架的 reference 文件
- 检查 reference 文件的
verified_date，若超 90 天则提醒用户
- 根据 Phase 1-4 的全部设计文档 + 框架模板生成完整项目：
- 项目结构（目录、依赖文件）
- Agent 核心代码
- 所有工具实现
- Prompt 模板文件
- Memory 配置
- 编排逻辑代码
- 配置文件（
.env.example / config.yaml）
- 启动脚本（
scripts/run.sh）
- README.md（含安装运行说明）
- 基础测试文件
- 每个核心代码文件生成后展示给用户确认
- 需要用户提供的敏感配置（API Key 等）统一放在
.env.example 中标注
产出: 完整可运行项目目录
确认点: 项目结构和核心文件确认后进入 Phase 6
Phase 6: 验证与迭代（Verification & Iteration）
交互方式: 自动验证 + 反馈循环
活动:
- 依赖安装验证（
pip install / go mod tidy / npm install）
- 语法检查 / 类型检查
- 单元测试执行
- Agent 行为 Smoke Test：模拟一轮对话，验证 Agent 能正确调用工具并返回结果
- 如有问题：定位 → 修复 → 重跑
- 展示验证结果给用户
- 用户手动测试后的反馈 → 迭代调整 prompt / 工具 / 编排逻辑
产出: 验证通过的可运行项目 + 验证报告
确认点: 用户确认项目可用
追踪表模板
Phase 1 完成后创建 {output_dir}/tracking.md：
# Agent Dev Tracking
| Phase | 状态 | 产出文件 | 确认时间 |
|-------|------|----------|----------|
| 1. 需求发现 | ✅ 已确认 | agent-spec.md | {timestamp} |
| 2. 架构设计 | ⏳ 进行中 | — | — |
| 3. 工具定义 | 🔲 未开始 | — | — |
| 4. Prompt 与编排 | 🔲 未开始 | — | — |
| 5. 代码生成 | 🔲 未开始 | — | — |
| 6. 验证迭代 | 🔲 未开始 | — | — |
## 关键决策记录
| # | 决策 | 原因 | Phase |
|---|------|------|-------|
| 1 | Agent 类型: {type} | {reason} | 1 |
| 2 | 框架: {framework} | {reason} | 1 |
与其他 Skill 的协作
| Skill | 调用时机 | 用途 |
|---|
agent-patterns-catalog | Phase 2 | 匹配最佳 Agent 架构模式 |
adk-framework-adapters | Phase 5 | 加载框架特定代码模板和惯用模式 |
systematic-debugging | Phase 6 | 遇到复杂错误时切换到系统化调试 |
tdd-workflow | Phase 5-6 | 测试先行策略（可选） |
默认命令入口
/agent-dev/agent-dev --quick/agent-dev --import
