前言：Agent 具备自主性、环境感知能力和决策执行能力，能够根据环境的变化自动调整行为，以实现特定的目标。

一、Agent 的原理

Agent(智能体)被提出时，具有四大能力 感知、分析、决策和执行。是一种能够在特定环境中自主行动、感知环境、做出决策并与其他Agent或人类进行交互的计算机程序或实体。它们具备自主性、反应性、社交性和适应性等特点，能够根据环境的变化调整自己的行为，以达到预设的目标。基于大模型构建的Agent，主要利用LLM进行进行语义理解和推理分析，结合任务分析能力通过外部工具Tool。利用RAG构建知识库来创建Memory。

 1、Planning

类比人脑，通过对任务的拆解，分解为多个小任务，通过构思方案，分步骤操作，得到最终的答案即可终止。如：ReAct、CoT（思维链）。

2、Memory

模拟大脑的记忆功能，分为长期记忆和短期记忆。长期记忆为用户行为特征、外部知识库等，短期记忆为多轮对话形式存储上下文，任务结束即可清理。

3、Tools

工具，顾名思义通过外部构建的工具辅助完成决策。如：代码分析，网页读取，天气查询等。

4、Action

通过对Planning、Memory、Tools三者的调用，完成对用户输入的回答。如：智能查询天气预报，智能机器人抓取物体等。

二、具体案例（天气查询）

1. Planning（规划）

目标：明确任务需求，制定查询计划。

• 用户输入：用户提出天气查询需求（例如：“今天北京的天气怎么样？”）。

• 任务拆解：

  • 确定查询地点（北京）、时间（今天）。

  • 检查是否需要更详细的参数（如温度单位、是否需要降水概率等）。

• 输出：生成一个结构化查询意图，例如：

{"action": "weather_query","location": "北京","date": "今天","params": ["temperature", "weather_condition"]
}

2. Memory（记忆）

目标：利用历史数据或上下文优化查询。

• 短期记忆：检查对话历史中是否已有相关信息（例如用户之前提过“北京”或“今天”）。

  • 例：若用户刚问过“上海天气”，可确认是否需对比两地天气。

• 长期记忆：检索用户偏好（如用户曾设置温度单位为“摄氏度”）。

• 输出：补充查询参数，例如：

{"unit": "celsius","user_preference": "show_humidity"
}

3. Tools（工具）

目标：选择并调用合适的天气查询工具。

• 工具匹配：识别可用工具（如 WeatherAPI、OpenWeatherMap 等）。

• 工具参数：将规划阶段的意图转化为工具所需的输入格式。

  • 例：调用 WeatherAPI 的请求参数：

weather_tool.query(location="北京", date="2023-11-20", unit="celsius")

• 异常处理：准备备用工具或提示用户补充信息（如地点模糊时询问“您指的是北京市朝阳区吗？”）。

4. Action（执行）

目标：执行工具并返回用户可理解的结果。

• 调用工具：发送请求至天气 API，获取原始数据。

  • 示例 API 返回：

{"location": "北京","date": "2023-11-20","temperature": 15,"condition": "晴","humidity": "40%"
}

• 结果格式化：将数据转换为自然语言响应。

  • 最终输出：

    “今天北京天气晴朗，气温 15 摄氏度，湿度 40%。”

• 错误处理：如查询失败，反馈原因（如“网络错误”或“地点不存在”

完整流程示例

1. 用户输入：“今天北京湿度怎么样？”

2. Planning：解析出 action=weather_query, location=北京, date=今天, params=[humidity]。

3. Memory：发现用户偏好“显示百分比”。

4. Tools：调用 OpenWeatherMap 的湿度查询接口。

5. Action：返回“今天北京湿度为 40%”。

三、具体实现

具体构建思路如下：

SimpleAgent/  
├── SimpleAgent.py                # 主代理类（入口）
├── llm/                          # 语言模型模块
│   ├── __init__.py               # 初始化文件
│   └── base_model.py             # 抽象模型基类
├── memory/                       # 记忆管理模块
│   ├── __init__.py
│   └── memory.py                 # 长短期记忆类
├── rag/                          # 检索增强生成模块
│   ├── __init__.py
│   └── rag.py                    # RAG检索生成模块
├── tool/                         # 工具模块
│   ├── __init__.py
│   ├── calculator.py             # 计算器工具
│   ├── weather.py                # 天气查询工具
│   └── base_tool.py              # 工具基类
└── callback/                     # 回调处理模块├── __init__.py└── event_handler.py          # 事件处理回调

llm /base_model.py  主要调用大模型作为核心。用来回答基本问题

memory/memory.py 主要用来保存对话数据，主要做简单的多轮对话

rag/rag.py 主要用来实现检索功能来使用本地知识库，使用langchain框架加载向量数据库Faiss

tool/  定义了工具基类，通过工具基类实现了calculator和weather 两个工具。

主要解析SimpleAgent:

1、如何利用大模型理解用户意图

        提示工程(Prompt Engineering)、语义相似度分析、意图分类技术、多轮对话管理

        推荐使用提示词工程

请分析用户意图并选择操作。可用工具：{tools_list}用户输入：{prompt}请返回严格的JSON格式：{{"tool": "工具名" | null,"action": "use" | "direct_response","params": "参数" | null,}}

tool_list包含工具名和工具描述，如果用户的需求工具可以实现，则通过工具调用，反之则用LLM直接回答。

print(agent.available_tools)
# 输出: {'calculator': '数学计算器工具...', 'weather': '天气查询工具...'}

2、如何定义工具和调用

2.1定义工具前，需要设置一个工具基类。

class Tool(ABC):"""工具基类"""def __init__(self):self._is_core = False  # 是否为核心工具@property@abstractmethoddef name(self) -> str:"""工具名称"""pass@abstractmethoddef use(self, params: Dict[str, Any]) -> Any:"""工具主逻辑Args:params: 参数字典Returns:执行结果"""pass

2.2定义一个天气查询Tool

import requests
from typing import Dict, Anyclass Weather(Tool):"""天气查询工具，获取指定城市的天气信息"""@propertydef name(self) -> str:return "weather"def use(self, params: Dict[str, Any]) -> Dict:city = params.get("city", "北京")# 实际调用天气APIresponse = requests.get(f"https://api.weather.com/{city}")return response.json()

 2.3 工具的调用

直接调用

result = agent.tool_use(tool_name="weather",params={"expression": "北京"}
)

通过LLM自动调度（用户自然语言输入 → Agent自动选择工具 → 返回结果：）

response = agent.llm_tool_dispatcher("查询北京的天气")

2.4 工具调用详解

通过使用_llm_analyze_intent()生成如下的意图结构化决策：

{"tool": "cweather","action": "use","params": {"expression": "北京"}
}

通过tool_use()方法调用，得到反馈结果。将反馈结果推送大模型转换为自然语言进行回复。

2.5 工具的添加

根据自己设置的base_tool来定义对应的工具（记得添加工具描述），然后在Agent中注册该工具

3、如何设置本地知识库（基于langchain）

3.1 文本文档的处理

from langchain.document_loaders import (PyPDFLoader,Docx2txtLoader,UnstructuredFileLoader
)class DocumentLoader:"""支持多种格式的文档加载器"""@staticmethoddef load(file_path: str):if file_path.endswith('.pdf'):loader = PyPDFLoader(file_path)elif file_path.endswith('.docx'):loader = Docx2txtLoader(file_path)else:  # txt/html等loader = UnstructuredFileLoader(file_path)return loader.load()

3.2. 向量数据库配置

from langchain.embeddings import HuggingFaceEmbeddings
from langchain.vectorstores import FAISSclass VectorDB:"""基于FAISS的本地向量数据库"""def __init__(self):self.embeddings = HuggingFaceEmbeddings(model_name="GanymedeNil/text2vec-large-chinese")def create_index(self, docs, save_path="vector_db"):db = FAISS.from_documents(docs, self.embeddings)db.save_local(save_path)return dbdef load_index(self, path):return FAISS.load_local(path, self.embeddings)

 3.3完整RAG实现

class LocalKnowledgeBase:def __init__(self):self.vectordb = VectorDB()self.retriever = Nonedef build_knowledge_base(self, file_paths: list):"""构建知识库"""all_docs = []for path in file_paths:docs = DocumentLoader.load(path)all_docs.extend(docs)self.vectordb.create_index(all_docs)print("知识库构建完成")def load_existing_knowledge(self, db_path):"""加载已有知识库"""self.retriever = self.vectordb.load_index(db_path)def query(self, question: str, top_k=3) -> list:"""检索知识"""if not self.retriever:raise ValueError("请先加载知识库")docs = self.retriever.similarity_search(question, k=top_k)return [doc.page_content for doc in docs]

3.4 与Agent的交互

class EnhancedAgent(SimpleAgent):def __init__(self, *args, **kwargs):super().__init__(*args, **kwargs)self.knowledge_base = LocalKnowledgeBase()def rag_response(self, query: str) -> str:"""增强的RAG响应"""# 1. 检索相关知识contexts = self.knowledge_base.query(query)# 2. 构造增强提示prompt = f"""基于以下上下文回答问题：{contexts}问题：{query}答案："""# 3. 生成最终回复return self.generate_response(prompt)

3.5 RAG 使用技巧

1、使用缓存或者保存为本地向量库，方便以后的查询

agent = EnhancedAgent("SmartBot")# 首次构建（耗时操作）
agent.knowledge_base.build_knowledge_base(["data/产品手册.pdf","data/常见问题.docx"
])
# 后续使用直接加载
agent.knowledge_base.load_existing_knowledge("vector_db")

from diskcache import Cachecache = Cache("query_cache")@cache.memoize(expire=3600)
def cached_query(question):return self.knowledge_base.query(question)

2、采用混合查询策略

def hybrid_search(query):# 语义检索semantic_results = self.retriever.similarity_search(query)# 关键词检索keyword_results = self.retriever.search(query, search_type="mmr")return combine_results(semantic_results, keyword_results)

3、关于知识库的更新

def update_knowledge(file_path):new_docs = load_documents(file_path)self.retriever.add_documents(new_docs)self.retriever.save("vector_db")

四、总结

基于大语言模型(LLM)的智能代理(Agent)实现，具有工具使用、记忆和检索增强生成(RAG)能力。

核心组件

1. 语言模型(LanguageModel)：基础的大模型接口

2. 记忆系统(Memory)：存储对话历史

3. 工具系统(Tool)：可扩展的工具框架

4. 回调系统(CallbackHandler)：事件处理机制

5. RAG系统：检索增强生成功能

主要功能解析

1. 初始化与基础功能

• __init__ 初始化代理名称、语言模型、记忆、回调和工具系统

• greet 简单的问候功能

• generate_response 基础文本生成功能

2. 工具系统

• _init_tools 初始化默认工具(计算器和天气查询)

• register_tool/unregister_tool 工具的动态注册与卸载

• tool_use 安全执行工具调用，带超时控制和错误处理

• available_tools 获取可用工具清单

3. 意图理解与调度

• _llm_analyze_intent 核心意图理解方法：

  • 构造包含可用工具信息的提示词

  • 要求LLM返回结构化JSON响应

  • 使用正则表达式提取JSON结果

  • 验证结果结构有效性

• llm_tool_dispatcher 主调度方法：

  • 如果有文件路径，使用RAG处理

  • 否则分析用户意图

  • 根据意图决定使用工具或直接响应

  • 格式化工具结果为自然语言

4. RAG功能

• rag 方法实现检索增强生成：

  • 加载文档

  • 检索相关信息

  • 生成回答

5. 辅助功能

• 日志记录

• 错误处理

• 回调系统(用于监控和扩展)

• 结果格式化

 完整代码：https://github.com/rescal-xuan/SimpleAgent