Ollama + LangChain：零基础搭建本地部署Agent完整教程

在本地电脑运行一个能真正“做事”的 AI Agent，比单纯聊天更有实用价值。通过组合 Ollama 本地推理后端和 LangChain 编排框架，我们可以让大模型在断网环境下调用自定义 Python 函数。本文将带你从零开始，在 Windows 系统上搭建一个最小化的库存查询 Agent，直观看到模型如何识别意图、调用工具并生成最终回答。

本地 Agent 工作流程：用户输入经 LangChain 编排，由 Ollama 模型决定调用本地工具，最终返回结果。

整个流程基于 Windows 10 22H2 或更新版本，使用 Python 3.11 环境。核心组件包括提供本地模型服务的 Ollama 和负责逻辑编排的 LangChain。为了降低门槛，我们选用支持工具调用的轻量级模型 qwen3:4b-instruct。请注意，模型文件大小不等于运行内存需求，请确保电脑留有足够的内存空间。以下操作均在本地完成，无需连接云端 API。

1. 安装 Ollama 并下载指定模型

首先获取 Ollama 的 Windows 安装程序 OllamaSetup.exe，运行并完成安装。安装后，Ollama 会在后台启动本地服务，我们可以通过 PowerShell 与其交互。

打开 PowerShell，依次执行以下命令检查版本并拉取模型：

ollama --version
ollama pull qwen3:4b-instruct
ollama list

PowerShell 终端显示 ollama pull 命令执行成功，模型 qwen3:4b-instruct 出现在列表中。

下载完成后，使用 ollama list 确认列表中已出现 qwen3:4b-instruct。后续 Python 代码中的模型名称必须与此处的标签完全一致，包括大小写和版本号。如果此时提示无法连接，请先确认桌面右下角的 Ollama 图标是否正在运行，排除服务未启动导致的连接错误。

2. 建立独立的 Python 项目环境

为了避免依赖冲突，建议为该项目创建独立的虚拟环境。确保系统中已安装 Python 3.11，并在 PowerShell 中确认 python 命令指向正确版本。

执行以下命令创建项目目录并安装必要库：

mkdir local-agent-demo
cd local-agent-demo
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -U langchain langchain-ollama

这里安装了 langchain 用于 Agent 编排，以及 langchain-ollama 用于连接本地 Ollama 服务。后续所有 Python 命令均通过 .venv\Scripts\python.exe 执行，无需激活环境或修改系统策略。

2. 建立独立的 Python 项目环境

3. 编写带本地工具的 Agent 代码

在项目根目录新建 UTF-8 编码的 agent_demo.py 文件。我们将定义一个简单的库存查询工具，并让 Agent 学会使用它。

复制以下代码到文件中：

import os

# 关闭 LangSmith 追踪，避免需要配置云端密钥
os.environ["LANGSMITH_TRACING"] = "false"

from langchain.agents import create_agent
from langchain.tools import tool
from langchain_ollama import ChatOllama


@tool
def get_stock(product: str) -> str:
    """查询演示库存。product 只接受 keyboard 或 mouse。"""
    inventory = {"keyboard": 7, "mouse": 12}
    if product not in inventory:
        return "未知商品"
    return f"{product} 的库存为 {inventory[product]}"


# 初始化本地模型连接
model = ChatOllama(
    model="qwen3:4b-instruct",
    base_url="http://localhost:11434",
    temperature=0,
)

# 创建 Agent，注入工具和系统提示词
agent = create_agent(
    model=model,
    tools=[get_stock],
    system_prompt=(
        "你是库存查询助手。涉及库存时必须调用 get_stock，"
        "根据工具返回回答，不猜测数量。"
    ),
)

# 执行查询请求
result = agent.invoke(
    {"messages": [
        {"role": "user",
         "content": "请调用 get_stock 查询 keyboard 的库存，用中文回答。"}
    ]},
    config={"recursion_limit": 8},
)

# 打印执行过程
for message in result["messages"]:
    print(message.type, message.content)
    calls = getattr(message, "tool_calls", None)
    if calls:
        print("tool_calls:", calls)

代码中，get_stock 函数通过 @tool 装饰器暴露给模型，其文档字符串和参数类型标注帮助模型理解如何调用。ChatOllama 负责将请求发送给本地服务，而 create_agent 则管理整个调用链：模型决定调用工具 -> 执行 Python 函数 -> 将结果返回模型 -> 模型生成最终回复。

注意 recursion_limit 参数限制了执行步数，防止模型陷入无限循环。如果命中限制，通常意味着模型未能正确结束调用，应检查提示词或工具定义，而非盲目增加限制值。

4. 运行程序并验证工具调用

保持 Ollama 服务运行，在 PowerShell 中执行脚本：

.\.venv\Scripts\python.exe agent_demo.py

程序将输出消息类型、内容及可能的工具调用记录。验收的关键在于观察链路是否完整：

1. 模型是否发起了名为 get_stock 的调用，且参数包含 keyboard；
2. 是否出现了工具返回的消息，内容显示库存为 7；
3. 最终回答是否基于工具返回的数据，而非模型自行编造。

终端输出日志，清晰展示 model 消息、tool_calls 调用记录以及最终的 assistant 回答。

如果输出中只有自然语言回答而没有 tool_calls，请检查模型标签是否正确，以及工具列表是否成功传入 create_agent。若出现导入错误，请确认是否使用了同一虚拟环境下的 Python 解释器。

5. 更换测试用例与保留环境

为了验证 Agent 的泛化能力，将代码中的查询对象改为 mouse 并再次运行。检查输出是否通过 get_stock 获取到库存 12。接着尝试查询字典中不存在的商品，如 monitor，观察工具是否返回“未知商品”，且模型不再虚构数据。

测试完成后，保留 agent_demo.py 并导出依赖清单，以便在其他机器复现：

.\.venv\Scripts\python.exe -m pip freeze > requirements.txt

同时记录当前 Ollama 版本和模型标签。这个最小化 Agent 的成功运行，标志着你已经掌握了本地模型与外部工具交互的核心逻辑。在此基础上，你可以替换 get_stock 为真实的数据库查询或 API 调用，构建更复杂的应用。

5. 更换测试用例与保留环境