8.1 项目架构设计

🎯 小白理解指南：什么是"架构设计"？

架构设计就是画蓝图——在动手写代码之前，先想清楚：

• 代码怎么组织？
• 各部分怎么配合？
• 以后怎么扩展？

就像盖房子要先画图纸，写软件也要先设计架构。 好的架构 = 代码好写、bug 好找、功能好加

设计原则

🎯 小白理解指南：为什么需要设计原则？

设计原则就是写代码的"金科玉律"，遵守它们可以避免很多坑：

原则	意思	反面教材
模块化	每个功能独立，互不干扰	所有代码写在一个文件里
可测试	每个功能都能单独测试	写完才发现不知道怎么测
可扩展	加新功能不用大改	加个功能要改 10 个文件
健壮性	出错不崩溃	网络断了程序就挂

1. 模块化：每个功能独立模块
2. 可测试：单元测试覆盖
3. 可扩展：易于添加新 Tool
4. 健壮性：完善的错误处理

核心组件

🎯 小白理解指南：Agent 的三大核心组件

一个 Agent 就像一个员工，需要三样东西：

1. State（状态）：员工的"工作笔记本"——记录对话、上下文、用过的工具
2. Tools（工具）：员工的"技能"——搜索、计算、查天气
3. Agent（主逻辑）：员工的"大脑"——决定做什么、怎么做

下面的代码就是这三样东西的"骨架"。

1. 状态定义（State）

# state.py - 状态定义
# 🎯 这是 Agent 的"记忆结构"，规定要记住哪些信息

from typing import TypedDict, List
from langchain_core.messages import BaseMessage

class AgentState(TypedDict):
    messages: List[BaseMessage]  # 对话历史（聊了什么）
    context: dict                 # 上下文信息（额外背景）
    tools_used: List[str]         # 用过的工具（做了什么）

🎯 小白提示：TypedDict 确保每个字段类型固定，防止传错数据。

2. Agent 主逻辑

# agent.py - Agent 主逻辑
# 🎯 这是 Agent 的"启动程序"

from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

def create_agent():
    # 创建 LLM（大模型）—— Agent 的"大脑"
    llm = ChatOpenAI(model="gpt-4")

    # 加载工具 —— Agent 的"技能"
    tools = load_tools()

    # 用 LangGraph 组装成完整的 Agent
    # 🎯 create_react_agent 是 LangGraph 提供的"一键创建"函数
    agent = create_react_agent(llm, tools)

    return agent

🎯 小白提示：create_react_agent 帮你处理了 Agent 的"思考→行动→观察"循环，你只需要提供大脑（LLM）和技能（Tools）。

---

下一节：8.2 实现核心功能