AI Agent / 系统课时

组织 Agent 项目目录

组织 Agent 项目目录

这一课把 Agent 项目按模型、工具、状态、流程、评测和接口拆成清晰边界,并给出一套可直接创建的最小目录。目标不是追求目录数量,而是让依赖方向可控、模块职责稳定。

学习目标

  • 按变化原因拆分模型、工具、状态、流程、评测和接口代码。
  • 建立单向依赖规则,避免工作流与基础模块相互引用。
  • 用最小目录起步,并知道项目变大后该继续拆哪里。

先按变化原因拆目录

目录设计的核心不是“文件放得整齐”,而是把不同变化频率的代码隔开。模型适配会随供应商变化,工具会随外部能力变化,状态定义会随任务上下文变化,工作流负责组合这些能力,接口层只处理 HTTP 或 CLI 边界,评测则应尽量独立于生产入口。

Agent 项目模块边界与依赖方向

目录 主要职责 不应承载
models/ 模型客户端、供应商适配、请求与响应转换 业务流程编排
tools/ 搜索、数据库、文件等可调用能力 Agent 主流程
state/ 会话状态、任务状态、持久化结构 HTTP 路由
workflows/ 节点编排、决策、重试与流程控制 供应商细节
evals/ 数据集、评测器、回归脚本 在线请求入口
api/ HTTP/CLI 入参、鉴权、响应转换 模型和工具实现

建立最小目录

下面创建最小 src 目录和可运行入口。把脚本保存为 init_layout.py,在项目根目录运行。脚本只新建缺失文件,重跑会保留已有内容。

python
from pathlib import Path

root = Path("agent_app")
files = {
    "src/agent/__init__.py": "",
    "src/agent/models/__init__.py": "",
    "src/agent/tools/__init__.py": "",
    "src/agent/state/__init__.py": "",
    "src/agent/workflows/__init__.py": "",
    "src/agent/api/__init__.py": "",
    "src/agent/workflows/main.py": 'def run():\n    return "agent-layout-ready"\n',
    "src/agent/api/cli.py": "from agent.workflows.main import run\n\nif __name__ == '__main__':\n    print(run())\n",
    "evals/.gitkeep": "",
    "tests/.gitkeep": "",
}

for name, content in files.items():
    path = root / name
    path.parent.mkdir(parents=True, exist_ok=True)
    try:
        with path.open("x", encoding="utf-8") as file:
            file.write(content)
    except FileExistsError:
        pass

进入 agent_app/src,执行 python -m agent.api.cli,预期输出 agent-layout-ready。从 src 目录运行是这个小例子的约定。真正打包时,可通过 pyproject.toml 声明包所在目录并做可编辑安装,届时就不必切换到 src。前两课的模型客户端可以移到 models/,移动后应把对应 import 一起改成包内路径。

约束依赖方向

推荐把依赖方向固定为 api -> workflows -> models/tools/state。接口层负责接收外部请求并调用工作流;工作流可以组合模型、工具和状态,但基础模块不反向导入工作流或接口层。

评测代码可以调用工作流来跑离线样本,却不应被线上代码依赖。测试可以按需要访问各模块,但测试辅助代码也不要混回生产目录。这样做能显著减少循环依赖,并让模型客户端、工具或接口框架可以独立替换。

什么时候继续拆分

当某个目录开始同时承担两个明显不同的变化原因时再拆。例如 tools/ 同时包含数据库、浏览器和内部服务调用,可以继续按领域分子目录;workflows/ 出现多个完全独立的 Agent 流程时,也可以按业务场景拆开。

反过来,如果项目只有一个模型、两个工具和一条流程,就没有必要一开始引入插件系统、依赖注入容器或复杂分层。目录结构的验收标准是:新人能快速找到代码,修改一个模块不会迫使无关模块一起变化,依赖方向也能保持单向。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

组织 Agent 项目目录

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通