Agent项目目录结构

核对日期：2026-05-09。

1. 定义与边界

Agent 项目目录结构是对代码、Prompt、工具定义、评测集、运行配置、部署脚本和观测配置的边界划分。它不是“把所有文件放进一个 agents/ 目录”，而是让每类资产都有清晰 owner、发布节奏和回滚方式。

生产项目至少要区分：

业务编排代码：Agent loop、planner、executor、router。
Prompt 资产：系统 Prompt、工具说明、few-shot 示例、输出格式。
工具接口：tool schema、权限策略、适配器、mock。
状态与会话：数据库迁移、状态 schema、存储接口。
评测与回放：测试集、红队用例、trace fixture、基准报告。
部署与运维：容器、Kubernetes、队列 worker、告警和仪表盘配置。

2. 为什么重要

Agent 项目最常见的失控点是 Prompt、工具和业务代码耦合在同一个文件里。短期迭代快，长期会导致无法评审、无法定位回归、无法复现线上问题。目录结构的目标是把变更类型显式化：改 Prompt 要跑 Prompt 回归，改工具 schema 要跑契约测试，改模型路由要跑成本与质量评测。

3. 核心机制

推荐把 Agent 资产按“运行层”和“治理层”分开：

agent-app/
  src/
    agents/
      support_agent/
        graph.py
        policy.py
        prompts/
        tools.py
    tools/
      crm/
      billing/
      search/
    runtime/
      state_store.py
      session_store.py
      queue.py
      tracing.py
    safety/
      guardrails.py
      pii.py
      approvals.py
  prompts/
    support_agent/
      system.prompt.md
      tool_instructions.prompt.md
      changelog.md
  evals/
    datasets/
    graders/
    regression/
  traces/
    fixtures/
  deploy/
    docker/
    k8s/
    terraform/
  docs/
    runbooks/

关键原则：

Prompt 文件要独立存储，不要散落在业务函数字符串里。
工具 schema 与工具实现分离，schema 变更要有兼容策略。
runtime 层只提供状态、队列、缓存、trace 等基础设施接口，不夹带业务 Prompt。
evals 与 traces 是一等资产，和代码一起进入版本管理。

4. 架构模式

模式	适用场景	风险
单体 Agent 应用	小团队、少量工具、低并发	长任务阻塞 API，Prompt 与业务代码容易耦合。
API + Worker	有长任务、工具耗时不稳定、需要重试	要设计任务状态、幂等和回放。
Graph/Workflow 项目	多步骤、可中断、需要 human-in-the-loop	图状态 schema 复杂，迁移成本高。
多 Agent 包结构	多角色、多团队维护	角色边界不清会变成分布式 Prompt 混乱。

5. 工程实现

目录结构应配合 CI 检查：

# .github/workflows/agent-ci.yml
checks:
  - prompt_lint
  - tool_schema_contract_test
  - unit_test
  - eval_regression
  - replay_golden_traces
  - secrets_scan

每个 Agent 模块建议暴露统一入口：

class AgentModule:
    name: str
    version: str
    prompt_version: str

    def build_graph(self): ...
    def required_tools(self) -> list[str]: ...
    def state_schema(self) -> dict: ...
    def eval_suites(self) -> list[str]: ...

6. 生产实践

config/ 只放非敏感默认值，密钥进入密钥管理系统。
每个可部署组件有独立 Dockerfile 或构建目标：API、worker、scheduler、migration。
deploy/ 中区分 dev、staging、prod，避免“本地默认配置就是生产配置”。
Prompt、模型和工具版本写入每条 trace，支持回放。
数据库迁移和状态 schema 迁移必须可回滚或可双读。

7. 常见反模式

把 Prompt、工具说明、业务逻辑全部写在一个 agent.py。
用环境变量切换大量业务行为，导致线上不可追踪。
只保存最终回答，不保存中间 tool call 和模型输入摘要。
evals 目录缺失，Prompt 变更靠人工试几条样例。
工具 schema 没有版本号，调用方和服务端无法做兼容。

8. 评测方法

目录完整性检查：核心目录是否存在，是否有 owner 和 README。
变更影响检查：Prompt/tool/schema/runtime 任一变更是否触发对应测试。
回放检查：抽取线上 trace fixture，确认新版本能复现或解释差异。
发布检查：每个部署物是否能追溯到 git commit、Prompt version、model version。

9. 安全与治理

prompts/ 不保存真实用户隐私样本，评测数据要脱敏或合成。
traces/fixtures/ 进入仓库前必须做 PII 扫描。
工具目录按权限域划分，例如 tools/billing 不应被所有 Agent 默认加载。
Prompt、工具权限、模型路由配置需要 code review。

10. 权威资料

The Twelve-Factor App: https://12factor.net/
OpenAI Agents SDK docs: https://developers.openai.com/api/docs/guides/agents
OpenAI Deployment checklist: https://developers.openai.com/api/docs/guides/deployment-checklist
OpenTelemetry Generative AI semantic conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/
Kubernetes documentation: https://kubernetes.io/docs/

11. 二次精修：生产级目录模板

生产 Agent 项目的目录结构要服务三件事：可回放、可评测、可审计。下面模板适合单 Agent、多工具、带队列和离线评测的项目。

agent-service/
  app/
    api/                    # HTTP/gRPC 入口，只做鉴权、限流、请求封装
    agents/                 # Agent 编排，不直接写外部副作用
    tools/                  # 工具适配器，按权限域拆分
    workflows/              # 可确定的业务流程
    state/                  # 状态 schema、迁移、存储接口
    prompts/                # prompt 模板、metadata、变更记录
    memory/                 # 短期上下文、长期记忆、检索策略
    queues/                 # 任务定义、消费者、重试策略
    observability/          # log、trace、metrics、redaction
    safety/                 # guardrail、审批、权限策略
  evals/
    datasets/               # jsonl/yaml 数据集
    graders/                # judge rubric、程序化断言
    regression/             # 发布门禁样本
  ops/
    dashboards/             # 仪表盘定义
    alerts/                 # 告警规则
    runbooks/               # 值班处置手册
    dr/                     # 灾备、回放、恢复演练
  traces/
    fixtures/               # 脱敏后的典型 trace

目录	必须产物	发布门禁
`prompts/`	prompt id、version、owner、适用模型、变更说明	prompt 变更触发离线 eval
`tools/`	tool schema、权限等级、超时、幂等键策略	contract test 和越权测试通过
`state/`	JSON Schema、迁移脚本、保留周期	旧状态可读，新状态可回滚
`queues/`	task schema、retry policy、DLQ 规则	重复投递不会重复副作用
`evals/`	dataset、rubric、基线报告	CI gate 分数不低于阈值
`ops/`	dashboard、alert、runbook	告警有 owner 和处置步骤

12. 目录与发布流水线

change_manifest:
  change_id: "chg_20260509_prompt_router_v3"
  owner: "agent-platform"
  touched_domains: ["prompts", "tools"]
  risk_level: "medium"
  required_checks:
    - prompt_snapshot_diff
    - tool_contract_test
    - offline_eval_core
    - pii_redaction_scan

13. 安全与治理补强

权限策略不能藏在业务代码里，至少要有 safety/policies/*.yaml，并在 CI 中校验高危工具默认关闭。
评测数据、trace fixture、用户反馈样本进入仓库前要脱敏，保留原始数据时应放在受控数据仓库。
目录 owner 要能映射到值班人；没有 owner 的工具、prompt、队列不能发布。
外部依赖版本要锁定，模型名、prompt version、tool version 要写入 trace，便于事后回放。
不要把“示例项目目录”当生产目录。生产目录必须包含评测、观测、运维和灾备材料。

14. 补充权威资料

OpenAI Agents SDK: https://openai.github.io/openai-agents-python/ （核对日期：2026-05-09）
OpenAI Evals guide: https://platform.openai.com/docs/guides/evals （核对日期：2026-05-09）
OpenTelemetry semantic conventions for GenAI: https://opentelemetry.io/docs/specs/semconv/gen-ai/ （核对日期：2026-05-09）

1. 定义与边界​

2. 为什么重要​

3. 核心机制​

4. 架构模式​

5. 工程实现​

6. 生产实践​

7. 常见反模式​

8. 评测方法​

9. 安全与治理​

10. 权威资料​

11. 二次精修：生产级目录模板​

12. 目录与发布流水线​

13. 安全与治理补强​

14. 补充权威资料​