推荐项目结构

Agently 不要求你必须用某一种目录结构，但当项目超过一个小 demo 时，最好按能力边界拆目录，而不是把所有逻辑都塞进一个 app.py。

适合什么时候读

你准备把 demo 变成真正项目
你希望多人协作时，Prompt、设置、工作流和工具各自有清晰 owner
你想理解官方 Agently Skills 为什么总强调 settings / prompts / workflow / tools / tests

你会学到什么

哪些文件应该归属于设置层、请求层、服务层和工作流层
为什么 Prompt 合约和输出合约不应该散落在 Python 逻辑里
如何给后续接入 Tools、KB、TriggerFlow 预留清晰边界

典型目录图

text

your-project/
├── SETTINGS.yaml
├── app/
│   ├── main.py
│   └── api.py
├── prompts/
│   ├── triage.yaml
│   └── summary.yaml
├── services/
│   ├── ticket_service.py
│   └── news_service.py
├── domain/
│   ├── enums.py
│   └── schemas.py
├── workflow/
│   ├── news_flow.py
│   └── approval_flow.py
├── tools/
│   ├── search.py
│   └── browse.py
├── tests/
│   ├── test_prompts.py
│   └── test_flows.py
├── outputs/
└── logs/

为什么这样拆

`SETTINGS.yaml`

把模型地址、${ENV.xxx}、工具参数、并发开关等部署期配置放这里，而不是散在代码字面量里。

`prompts/`

让 Prompt 和输出契约成为可维护资产：

易于复用
易于 review
易于做 YAML / JSON 配置化

`services/`

承接“业务语义”的那一层。它不直接等于 Agently 本身，而是把模型请求或工作流结果转换成业务接口。

`workflow/`

只有当你需要显式阶段、分支、并发或等待恢复时，再把流程 owning 放到这里。

`tools/`

搜索、浏览、MCP 适配器、外部系统封装都应集中到这里，方便替换和测试。

`tests/`

至少覆盖三类测试：

设置与环境变量是否可加载
Prompt / 输出契约是否稳定
服务或工作流是否按预期返回

最小示例

python

from agently import Agently

Agently.load_settings("yaml_file", "./SETTINGS.yaml", auto_load_env=True)

agent = Agently.create_agent()
agent.load_yaml_prompt("./prompts/triage.yaml")

常见误区

把所有 Prompt 直接写在业务代码里，导致后期难以复用和 review。
先写很多 helper 和 wrapper，再去想哪一层真正拥有这些逻辑。
将运行产物和源码混放，导致目录逐渐失控。

下一步去哪

如果你还没跑通最小请求，先看快速开始
如果你已经在接模型，继续看模型设置总览
如果你想把 Prompt 配置化，继续看工程化 Prompt 管理概览

推荐项目结构 ​

适合什么时候读 ​

你会学到什么 ​

典型目录图 ​

为什么这样拆 ​

SETTINGS.yaml ​

prompts/ ​

services/ ​

workflow/ ​

tools/ ​

tests/ ​

最小示例 ​

常见误区 ​

下一步去哪 ​

相关案例 ​

Related Skills（可选） ​