Agent开发入门教程

适合读者：

1.刚开始做 Agent 项目，想快速落地最小可用版本

2.需要在“简单查询、复杂交互、知识问答”之间做架构选型

3.希望统一前后端、模型、工具与存储技术栈

一、先理解整体架构

从上到下可以分为 6 层：

1. 用户层：工作台、LangSmith 等入口

2. Agent 编排层：Agent Manager、LangGraph 编排、Agent Factory、FC（Function Calling）

3. 工具层：静态工具组（本地注册）+ 动态工具组（按用户配置加载）

4. 领域能力层：MCP Server、领域 Sub Agent、高阶 Sub Agent

5. 知识与记忆：知识来源、记忆系统（长期/短期）

6. 基础设施层：基础设施、可观测、数据存储

一句话：`Top Agent` 负责调度，`工具层` 负责执行，`知识层` 负责补充上下文，`基础设施` 保障稳定运行。

二、入门落地路径（推荐）

按复杂度递进，避免一开始过度设计。

1. 先跑通 FC 直连工具

路径：`Top Agent -> FC 工具 -> 后端 API`

适合：单次调用、简单 CRUD、无需复杂推理。

2. 再接 MCP Agent（复杂交互）

路径：`Top Agent -> 包装工具 -> Sub Agent(LangGraph) -> MCP Server -> 后端服务`

适合：多轮工具调用、复杂业务规则、需要 Sub Agent 自主推理。

3. 最后补 RAG 检索能力

路径：`Top Agent -> retriever_tools -> Retriever -> Embedding -> ChromaDB`

适合：文档/手册查询、FAQ、操作指南。

三、技术栈清单（按层）

前端

• Vue `3.x / 2.x`
• TypeScript `5.x`
• Vite `5.x` / Webpack `5.x`
• Tailwind CSS `3.x`
• shadcn/ui `latest`
• element-plus `^2.10.4`
• antDesign Vue `4.x`

后端

• Python `3.x`
• FastAPI `0.100+`
• Uvicorn `0.23+`
• SQLModel `0.0.14+`
• Pydantic `2.x`

Agent 与模型

• LangChain `0.2+`
• LangGraph `0.1+`
• langchain-mcp-adapters `latest`
• Qwen `2.5`（主力模型）
• OpenAI API（兼容协议）

检索与数据

• ChromaDB `0.4+`
• OpenAI Embedding `text-embedding-3`
• Redis `7.x`（会话/Token 缓存）
• MySQL `8.x`（业务数据）
• 阿里云 OSS（文件存储）

观测与运维

• Langfuse / LangSmith / SLS（链路观测、日志与评估）

四、选型速记

• 简单任务：优先 `FC`，实现快、链路短、易维护。
• 复杂任务：优先 `MCP + Sub Agent + LangGraph`，可扩展多工具编排。
• 知识问答：优先 `RAG`，配合向量库与记忆系统。

五、最小可用实施建议（MVP）

1. 后端先提供稳定 API（FastAPI + Pydantic 校验）。

2. Top Agent 先接 FC 跑通 1 个核心业务场景。

3. 再按业务需要逐步引入 MCP、Sub Agent、RAG。

4. 同步接入日志、Tracing、重试和超时机制。