我的第一个工具调用Agent：从零构建“知识库+计算器+时间+文件”四合一智能体

case1_tool_agent/
├── config.py                    # 配置集中管理（路径、模型、端口）
├── requirements.txt             # 依赖锁定版本
├── .env.example                 # 环境变量模板
├── tools/                       # 工具模块（可复用）
│   ├── __init__.py
│   ├── calculator.py            # 计算器工具
│   ├── time_tool.py             # 时间工具
│   ├── file_tool.py             # 文件读写工具
│   └── rag_retriever.py         # 知识库检索工具
├── agent/                       # Agent核心
│   ├── __init__.py
│   └── builder.py               # Agent构建工厂
├── web/                         # Web服务
│   ├── app.py                   # Flask主应用
│   └── templates/
│       └── index.html           # 极简Chat界面
├── scripts/                     # 辅助脚本
│   ├── test_tools.py            # 工具单元测试
│   └── test_cli.py              # 命令行交互测试
├── chroma_db/                   # 知识库（复用已有）
│   └── chroma.sqlite3
└── workspace/                   # 文件工具工作目录

# -*- coding: utf-8 -*-
# @author: javy21
# @blog: https://blog.csdn.net/javy21
"""
计算器工具：执行数学表达式计算
"""

import logging
from langchain.tools import tool

logger = logging.getLogger(__name__)

@tool
def calculate(expression: str) -> str:
    """
    执行数学计算，输入数学表达式，返回计算结果。

    Args:
        expression: 数学表达式，如 '3+5' 或 '10*2/3'

    Returns:
        计算结果字符串，或错误信息
    """
    # 安全检查：只允许数字、运算符、括号、空格
    allowed_chars = set("0123456789+-*/().% ")
    if not all(c in allowed_chars for c in expression):
        error_msg = f"表达式包含非法字符：{expression}"
        logger.warning(error_msg)
        return f"计算错误：{error_msg}"

    try:
        result = eval(expression)
        logger.info(f"计算成功: {expression} = {result}")
        return f"计算结果：{result}"
    except ZeroDivisionError:
        return "计算错误：除数不能为零"
    except Exception as e:
        return f"计算错误：表达式格式错误 - {str(e)}"

# -*- coding: utf-8 -*-
# @author: javy21
# @blog: https://blog.csdn.net/javy21
"""
时间工具：获取当前日期和时间
"""

import logging
from datetime import datetime
from langchain.tools import tool

logger = logging.getLogger(__name__)

@tool
def get_current_time(format: str = "%Y-%m-%d %H:%M:%S") -> str:
    """
    获取当前日期和时间，可指定输出格式。

    Args:
        format: 时间格式字符串，默认 '%Y-%m-%d %H:%M:%S'

    Returns:
        格式化后的当前时间字符串
    """
    now = datetime.now()
    result = now.strftime(format)
    logger.info(f"获取当前时间: {result}")
    return result

# -*- coding: utf-8 -*-
# @author: javy21
# @blog: https://blog.csdn.net/javy21
"""
文件读写工具：在workspace目录下读写文件（防路径穿越）
"""

import logging
from pathlib import Path
from langchain.tools import tool

from config import WORKSPACE_DIR

logger = logging.getLogger(__name__)

@tool
def read_file(filename: str) -> str:
    """读取指定文件的内容。"""
    # 安全检查：防止路径穿越攻击
    if ".." in filename or filename.startswith("/"):
        return "读取失败：非法文件名"

    filepath = WORKSPACE_DIR / filename
    if not filepath.exists():
        return f"读取失败：文件 '{filename}' 不存在"

    try:
        content = filepath.read_text(encoding="utf-8")
        logger.info(f"读取文件成功: {filename}")
        return f"文件内容：\n{content}"
    except Exception as e:
        return f"读取失败：{str(e)}"

@tool
def write_file(filename: str, content: str) -> str:
    """将内容写入指定文件。"""
    if ".." in filename or filename.startswith("/"):
        return "写入失败：非法文件名"

    filepath = WORKSPACE_DIR / filename
    try:
        filepath.write_text(content, encoding="utf-8")
        logger.info(f"写入文件成功: {filename}")
        return f"成功写入文件：{filename}"
    except Exception as e:
        return f"写入失败：{str(e)}"

# -*- coding: utf-8 -*-
# @author: javy21
# @blog: https://blog.csdn.net/javy21
"""
知识库检索工具：基于Chroma向量库的语义检索
"""

import logging
from langchain.tools import tool
from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import HuggingFaceEmbeddings

from config import CHROMA_DIR, EMBEDDING_MODEL, RETRIEVAL_TOP_K

logger = logging.getLogger(__name__)

_vectordb = None

def _get_vectordb():
    """懒加载向量数据库（单例模式）"""
    global _vectordb
    if _vectordb is None:
        logger.info(f"正在加载向量数据库: {CHROMA_DIR}")
        embeddings = HuggingFaceEmbeddings(model_name=EMBEDDING_MODEL)
        _vectordb = Chroma(
            persist_directory=str(CHROMA_DIR),
            embedding_function=embeddings,
        )
        logger.info("向量数据库加载完成")
    return _vectordb

@tool
def search_knowledge(query: str) -> str:
    """从知识库中检索与查询相关的文档片段。"""
    try:
        vectordb = _get_vectordb()
        docs = vectordb.similarity_search(query, k=RETRIEVAL_TOP_K)

        if not docs:
            return "未找到相关信息。"

        contents = [doc.page_content for doc in docs]
        result = "\n\n---\n\n".join(contents)
        logger.info(f"检索成功: '{query}' -> {len(docs)} 个片段")
        return f"检索结果：\n{result}"
    except Exception as e:
        return f"检索失败：{str(e)}"

# -*- coding: utf-8 -*-
# @author: javy21
# @blog: https://blog.csdn.net/javy21
"""
Agent构建器：创建和配置LangChain Agent
"""

import logging
from langchain_community.llms import Ollama
from langchain.agents import initialize_agent, AgentType
from langchain.memory import ConversationBufferMemory

from config import OLLAMA_BASE_URL, MODEL_NAME, TEMPERATURE
from tools import calculate, get_current_time, read_file, write_file, search_knowledge

logger = logging.getLogger(__name__)

def create_agent(verbose: bool = True):
    """创建并返回一个配置好的Agent实例"""
    # 1. 初始化大模型
    logger.info(f"初始化模型: {MODEL_NAME} @ {OLLAMA_BASE_URL}")
    llm = Ollama(
        model=MODEL_NAME,
        base_url=OLLAMA_BASE_URL,
        temperature=TEMPERATURE,
    )

    # 2. 注册工具（顺序影响决策优先级）
    tools = [
        search_knowledge,    # 知识库检索
        calculate,           # 计算器
        get_current_time,    # 时间查询
        read_file,           # 文件读
        write_file,          # 文件写
    ]

    # 3. 设置记忆（对话缓冲）
    memory = ConversationBufferMemory(
        memory_key="chat_history",
        return_messages=True,
    )

    # 4. 创建Agent（使用支持多参数工具的Agent类型）
    agent = initialize_agent(
        tools,
        llm,
        agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,
        memory=memory,
        verbose=verbose,
        handle_parsing_errors=True,
        max_iterations=10,
        early_stopping_method="generate",
    )

    logger.info("Agent创建成功")
    return agent

@app.route("/api/chat", methods=["POST"])
def chat():
    data = request.get_json()
    user_input = data.get("message", "").strip()
    if not user_input:
        return jsonify({"error": "消息不能为空"}), 400

    try:
        response = agent.run(user_input)
        return jsonify({"response": response})
    except Exception as e:
        logger.error(f"处理失败：{str(e)}")
        return jsonify({"error": f"处理失败：{str(e)}"}), 500