AI Agent / 系统课时
搭建完整工程骨架
搭建完整工程骨架
本篇解决 Agent 项目代码规模增长后模块混乱的问题。通过划分核心模块、明确依赖方向并运行最小链路,建立一个可以继续扩展的工程基础。
学习目标
- 理解 Agent 工程中的核心模块职责
- 创建清晰的项目目录和依赖边界
- 完成最小端到端运行验证
Agent 工程模块划分
一个可维护的 Agent 系统不应把模型调用、工具执行、接口服务和数据存储全部写在同一个目录中。合理拆分可以降低耦合,让不同能力独立演进。
常见工程结构包括:
- Agent Core:负责推理循环、任务规划和状态管理
- API Server:负责接收外部请求和返回结果
- Project Engine:负责业务流程编排
- Tool System:负责工具注册、调用和权限控制
- Storage:负责记忆、配置和运行数据保存
- Sandbox:负责隔离执行环境
- Client:负责用户交互入口
模块关系如下:

建立最小项目结构
一个初始项目可以先保持简单,但需要提前确定边界。
text
agent-project/
├── api/
├── core/
├── engine/
├── tools/
├── storage/
├── sandbox/
└── client/每个模块只负责自己的职责。例如 core 不应该直接操作数据库,工具系统不应该直接处理 HTTP 请求,这样后续替换组件时影响范围更小。
实现最小端到端链路
工程骨架建立后,需要验证一次完整请求是否能够流转。
python
class AgentCore:
def run(self, task: str) -> str:
return f"完成任务: {task}"
class ApiServer:
def __init__(self):
self.agent = AgentCore()
def handle(self, request: str):
return self.agent.run(request)
server = ApiServer()
result = server.handle("生成测试报告")
print(result)预期输出
text
完成任务: 生成测试报告这个验证不关注复杂能力,而是确认模块之间的调用方向正确,后续接入真实模型、工具和存储时可以逐步替换实现。
验证工程设计是否合理
最小链路运行后,需要检查几个边界:
- API 是否只负责请求入口,不包含 Agent 内部逻辑
- Core 是否能够独立测试
- Tool System 是否可以增加新工具而不修改核心代码
- Storage 是否可以替换不同实现
- Sandbox 是否隔离危险执行行为
如果模块之间存在循环依赖,通常说明职责划分还不清晰,需要重新调整边界。
本课总结
- Agent 工程需要通过模块拆分控制复杂度。
- 清晰的依赖方向比一开始堆叠大量功能更重要。
- 最小端到端链路验证能够提前发现架构问题。
下一课预告
下一阶段将继续完善 Agent 核心能力,包括任务规划、状态管理和工具调用机制。
按自己的节奏,确认真正理解。