Agent 项目结构（Agent Project Structure）

Agent 项目结构（Agent Project Structure）

概念解释

Agent 项目结构，指的是在开发 AI Agent 应用时，如何组织代码文件、配置、工具定义、提示词等资源的目录约定。它不是某种框架或技术，而是一套"文件该放哪里"的工程实践。

传统 Python 项目通常只需要关心源代码和测试代码的分离。但 Agent 应用多了几样特殊的东西：提示词文件（Prompt）、工具定义（Tool/Skill）、模型配置（API Key、温度参数等）、知识库数据。如果这些东西和业务代码混在一起，项目一旦长大就会变成"找不到文件"的噩梦。

Agent 项目结构的核心思路是关注点分离（Separation of Concerns）——把不同职责的文件放进不同的目录，让开发者、Prompt 工程师、运维人员各自只需要关注自己负责的那个文件夹。

关键结构

一个典型的 Agent 项目包含以下一级目录，每个目录承担一种职责：

结构 1：src/ 源代码目录

src/ 是整个项目的心脏，采用 Python 社区推荐的 src layout（源码布局）。这种布局把应用代码放在 src/包名/ 下，强制开发者通过安装（pip install -e .）来使用包，避免了"本地能跑、别人跑不通"的导入路径问题。

src/ 内部通常再分为三个子目录：core/（核心框架逻辑）、agents/（具体 Agent 定义）、utils/（通用工具函数）。

结构 2：config/ 配置目录

Agent 应用高度依赖配置——同一份代码，换一套配置就能变成完全不同的 Agent。config/ 目录集中管理所有可配置项，核心原则是敏感信息（API Key 等）绝不写死在代码里，而是通过 .env 文件或环境变量注入。

典型内容：.env（本地环境变量，不提交到 Git）、.env.example（模板，告诉队友需要哪些变量）、settings.yaml（Agent 行为参数）。

结构 3：tools/ 工具目录

工具是 Agent 的"手和脚"。tools/ 目录把每种工具按功能分子目录（如 search/、database/），并定义统一的基类接口。这样添加新工具只需要"实现接口 + 放到对应目录"，不用动核心代码。

结构 4：prompts/ 提示词目录

提示词是 Agent 的"大脑指令"。把 Prompt 从代码字符串中抽出来，集中存放在 prompts/ 目录，按用途分为 system_prompts/（系统级）和 user_prompts/（用户交互模板）。好处是 Prompt 工程师可以独立修改提示词，不用碰 Python 代码。

核心原理

原理说明

Agent 项目结构的运作逻辑可以用四个字概括：各司其职。

程序启动时，config/ 先被加载，读取环境变量和配置文件，确定"用哪个模型、什么温度、开启哪些工具"。然后 tools/ 中的工具通过注册机制挂载到 Agent 上，告诉 Agent "你现在能做哪些事"。接着 prompts/ 中的提示词被加载，告诉 Agent "你应该怎么思考和行动"。最后 src/ 中的核心逻辑把这些组装起来，形成一个可以接收用户输入、调用工具、返回结果的完整 Agent。

关键设计决策有三个：

1. 配置外置：遵循 12-Factor App（十二要素应用）原则，把配置存在环境变量中，而不是硬编码在代码里。这样同一份代码可以在开发、测试、生产三个环境之间无缝切换。

2. 工具接口统一：所有工具实现同一个基类接口（名称、描述、参数定义、执行方法），Agent 核心代码不需要知道每个工具的具体实现细节。

3. 提示词与代码分离：Prompt 是 Agent 中变化最频繁的部分，把它独立出来，方便做版本管理和 A/B 测试。

Mermaid 图解

上半部分是初始化流程：配置 -> 工具 -> 提示词 -> Agent 组装，顺序不能乱（工具注册需要知道配置中开启了哪些工具，Agent 初始化需要知道有哪些工具和提示词可用）。

下半部分是运行时循环：收到用户消息后，Agent 根据提示词思考策略，调用工具执行，拿到结果后组装回复。这个循环中涉及的工具和提示词全部来自前面加载的目录。

运行示例

以下伪代码展示一个最小 Agent 项目的目录结构和初始化过程，不依赖任何第三方框架：

# 项目结构（伪代码展示目录关系）
# my_agent_project/
# ├── src/my_agent/core/agent.py   ← 当前文件
# ├── config/.env                   ← 环境变量
# ├── tools/search/web_search.py    ← 搜索工具
# └── prompts/system_prompts/       ← 系统提示词

import os
from pathlib import Path

class SimpleAgent:
    """最小 Agent 骨架，展示目录结构如何串联"""

    def __init__(self, project_root: str):
        root = Path(project_root)

        # 1. 加载配置（对应 config/ 目录）
        self.model = os.getenv("LLM_MODEL", "gpt-4o")

        # 2. 加载提示词（对应 prompts/ 目录）
        prompt_file = root / "prompts" / "system_prompts" / "base.txt"
        self.system_prompt = prompt_file.read_text(encoding="utf-8")

        # 3. 注册工具（对应 tools/ 目录）
        self.tools = {"web_search": self._search}

    def _search(self, query: str) -> str:
        return f"搜索结果：{query}"

    def run(self, user_input: str) -> str:
        # 核心逻辑：提示词 + 工具 + 用户输入 → 回复
        return f"[{self.model}] 处理：{user_input}"

SimpleAgent 的三个初始化步骤分别对应 config/、prompts/、tools/ 三个目录。实际项目中每个步骤会更复杂（如配置校验、工具自动发现、Prompt 模板渲染），但基本骨架不变。

易混概念辨析

核心区别：

• Agent 项目结构：关注"文件放哪里"，是物理层面的目录组织
• Python 项目结构：Agent 项目结构是它的超集，多了 tools/、prompts/、config/ 等 Agent 特有目录
• 软件架构模式：关注"代码怎么组织"，是逻辑层面的设计决策

适用边界与局限

适用场景

1. 团队协作的 Agent 项目：多人开发时，清晰的目录划分让开发者、Prompt 工程师、运维各管各的目录，减少冲突
2. 需要部署到多环境的项目：通过 config/ 的分层配置，同一份代码可以在开发、测试、生产环境间无缝切换
3. 工具会持续增加的项目：统一的工具接口和目录结构，让新增工具只需"实现接口 + 放到目录"

不适合的场景

1. 一次性脚本或快速原型：如果只是写个 50 行的实验脚本，完整的目录结构反而是负担，一个 main.py 就够了
2. 使用全托管平台的项目：如果用的是 Dify、Coze 等低代码平台，平台本身已经管理了目录结构，不需要自己规划

局限性

1. 初始搭建成本：需要创建多个目录和配置文件，对新手有一定门槛。可以通过项目模板（如 cookiecutter）自动化解决
2. 目录层级较深：开发时需要在多个目录间跳转，不过现代 IDE 的快速导航（Ctrl+P）能很好缓解这个问题

常见误区

思考题

参考资料

1. Python Packaging Authority (PyPA). "src layout vs flat layout". https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/

2. The Twelve-Factor App. "III. Config — Store config in the environment". https://12factor.net/config

3. Kenneth Reitz. "Structuring Your Project". The Hitchhiker's Guide to Python. https://docs.python-guide.org/writing/structure/

4. Satheesh Kumar. "Organizing Files for Agentic AI Systems". Medium. https://medium.com/@sathee12/organizing-files-for-agentic-ai-systems-my-rough-draft-e413dbe241d7

5. GitHub Blog. "How to write a great agents.md: Lessons from over 2,500 repositories". https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/