前言：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
    @abstractmethod
    def name(self) -> str:
        """工具名称"""
        pass
    
    @abstractmethod
    def use(self, params: Dict[str, Any]) -> Any:
        """
        工具主逻辑
        Args:
            params: 参数字典
        Returns:
            执行结果
        """
        pass

2.2定义一个天气查询Tool

import requests
from typing import Dict, Any

class Weather(Tool):
    """天气查询工具，获取指定城市的天气信息"""
    
    @property
    def name(self) -> str:
        return "weather"
    
    def use(self, params: Dict[str, Any]) -> Dict:
        city = params.get("city", "北京")
        # 实际调用天气API
        response = 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:
    """支持多种格式的文档加载器"""
    @staticmethod
    def 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 FAISS

class 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 db
    
    def load_index(self, path):
        return FAISS.load_local(path, self.embeddings)

 3.3完整RAG实现

class LocalKnowledgeBase:
    def __init__(self):
        self.vectordb = VectorDB()
        self.retriever = None
    
    def 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 Cache

cache = 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