在人工智能飞速迭代的今天，AI Agent 早已跳出“概念炒作”的范畴，成为连接大语言模型与实际应用的核心载体。它不再是实验室里的理论模型，而是能够自主理解需求、规划任务、调用工具、完成目标的“智能体”，小到个人本地的知识库问答工具，大到企业级高并发服务，再到低成本的端侧硬件控制，都能看到它的身影。

很多开发者在接触 AI Agent 时，常常会陷入“工具选择焦虑”，面对 Ollama、LangChain、vLLM 等五花八门的技术工具，不知道从何入手；不清楚不同技术栈的适配场景，盲目堆砌工具导致项目难以落地；甚至混淆了核心概念，让开发之路走得磕磕绊绊。本文将从基础概念出发，系统梳理 AI Agent 的完整技术栈，拆解轻量级、生产级、端侧硬件三种主流方案的细节，对比核心工具的差异与选型逻辑，提供清晰的升级路径，帮助无论是新手还是资深开发者，都能理清思路，找到适合自己场景的落地方案。

本文不追求晦涩的技术理论，而是以“实用落地”为核心，结合具体代码示例、工具对比和场景分析，让你既能理解 AI Agent 的底层逻辑，也能快速上手搭建属于自己的 AI Agent 系统，从入门原型到生产级部署，全程打通无阻碍。

一、基础概念：理清 AI Agent 的核心模块

在开始构建 AI Agent 之前，我们首先要理清其核心模块的层次关系，避免被繁杂的工具和概念绕晕。AI Agent 本质上是一个“模拟人类行为”的智能系统，它的核心逻辑的是“感知-认知-记忆-行动”，而各个工具和组件，都是为这一核心逻辑服务的。

1.1 概念层级图

从底层到上层，AI Agent 的概念层级可简单梳理为：LLM 基座 → 推理层 → 能力扩展层 → 协议层 → 应用层。其中，LLM 基座是整个系统的核心，推理层负责让 LLM 能够稳定运行，能力扩展层让 LLM 拥有记忆和行动能力，协议层实现各模块的高效对接，应用层则是面向用户的具体场景。

1.2 核心概念解析

我们用“人类”来类比 AI Agent 的各个核心组件，就能快速理解它们的定位和作用，具体如下：

• LLM 基座：最底层的核心组件，相当于人类的“大脑”，负责核心的推理、思考和内容生成。它是 AI Agent 的基础，所有的智能行为都依赖于 LLM 的能力，常见的有 Qwen、Llama、Mistral 等开源模型，以及 GPT-4、Claude 等闭源模型。

• 推理层工具：相当于让“大脑”能够正常运转的“培养皿”，负责在本地或云端运行 LLM 基座。我们不需要关心 LLM 的底层实现，只需要通过这类工具，就能快速调用 LLM 的能力，常见的有 Ollama、vLLM 等。

• 知识库/RAG：相当于人类的“记忆和资料库”，负责给 LLM 补充领域知识，解决 LLM 自身“不知道”的问题。比如 LLM 不知道你的公司内部制度、行业规范，通过知识库/RAG，就能将这些专属知识“喂”给 LLM，让它成为你的“专属顾问”。

• Skill/Tools：相当于人类的“手脚和工具”，负责让 LLM 能够执行具体的动作。LLM 本身只能“思考”，无法直接操作外部系统，而 Skill/Tools 就为它提供了“行动”的能力，比如调用 API、操作文件、控制硬件设备等。

• MCP：相当于人类的“神经系统的通信协议”，负责统一 LLM 与外部工具、数据源的对接标准。以前，每个工具都需要单独与 LLM 对接，适配成本很高，而 MCP 就像是“AI 的 USB 接口标准”，实现了工具的“即插即用”，大大降低了开发成本。

这里重点说一下两个最基础、最常用的工具：Ollama 和 MCP。Ollama 是一个本地 LLM 运行工具，它的核心优势是“简单易用”，类似于 Docker 管理容器的方式，来管理和运行开源大模型，一行命令就能在本地跑起一个大模型，比如“ollama run qwen2:7b”，就能快速启动 Qwen2 7B 模型，非常适合开发者快速体验和原型开发。

MCP（Model Context Protocol）是 Anthropic 提出的标准化协议，我们可以把它理解为“AI 的万能接口”。它的核心价值是解决了 AI 工具对接碎片化的问题，以前开发一个 AI Agent，需要为每个工具单独写适配器，而有了 MCP，所有遵循 MCP 协议的工具，都能直接对接 LLM，无需额外开发，实现了“即插即用”，这也是后续很多 AI Agent 方案能够快速落地的关键。

二、本地推理工具全览

推理工具是 AI Agent 的“基础支撑”，它决定了 LLM 能够以什么样的性能、在什么样的环境中运行。根据使用场景和用户群体的不同，本地推理工具可以分为三类：图形化/易上手、命令行/开发者向、生产环境/高性能。不同类型的工具，适配的场景和人群不同，我们可以根据自己的需求灵活选型。

2.1 图形化/易上手

这类工具主要面向非技术用户或新手开发者，核心优势是“可视化操作”，无需编写代码，通过鼠标点击就能完成 LLM 的下载、启动和调用，非常适合快速体验本地 LLM 的能力。

• LM Studio：目前最友好的桌面 GUI 推理工具，支持 Windows、Mac、Linux 系统。界面简洁直观，支持拖拽下载各类开源模型，启动模型后，就能直接进行对话交互，还能简单配置模型参数，新手零门槛上手。

• Jan：开源桌面应用，界面比 LM Studio 更简洁，专注于“轻量、快速”。支持本地模型的管理和运行，还能对接外部 API，隐私性较强，适合普通用户日常使用。

• GPT4All：主打“隐私保护”，所有模型运行都在本地，数据不会上传到云端。支持多种开源模型，界面操作简单，适合隐私敏感用户，比如处理内部文档、个人隐私数据等场景。

2.2 命令行/开发者向

这类工具主要面向开发者，核心优势是“灵活、可定制”，需要通过命令行或代码进行操作，适合开发者在本地进行原型开发、工具调试，能够灵活配置模型参数、对接其他开发工具。

• llama.cpp：底层 C++ 推理引擎，是很多上层推理工具（比如 Ollama）的基础。核心优势是“极致性能”，对硬件资源的占用较低，支持多种量化方式，能够在性能有限的设备上运行大模型，适合追求极致性能的开发者。

• LocalAI：核心特点是“兼容 OpenAI API 格式”。如果你的代码原本是对接 OpenAI API 的，使用 LocalAI 后，无需修改代码，就能直接替换为本地模型，大大降低了本地模型的适配成本，适合需要迁移 OpenAI 项目的开发者。

• text-generation-webui：功能最全的 Web UI 推理工具，支持命令行启动，也能通过 Web 界面操作。支持几乎所有主流开源模型，能够灵活配置模型参数、实现 RAG、工具调用等功能，适合需要丰富功能的开发者。

2.3 生产环境/高性能

这类工具主要面向企业和生产环境，核心优势是“高吞吐、高可靠、可扩展”，能够支持高并发请求，适合大规模部署，为企业级 AI Agent 提供稳定的推理支撑。

• vLLM：目前最主流的生产级推理引擎，由 UC Berkeley 团队开发。核心技术是 PagedAttention（分页注意力），类似于操作系统的虚拟内存技术，能够大幅提升显存利用率，支持动态批处理，吞吐量是 Ollama 的 10 倍以上，适合高并发生产部署。

• TGI：HuggingFace 出品的生产级推理引擎，与 HuggingFace 生态深度集成。支持多 GPU 部署、动态批处理、流式输出等功能，稳定性强，适合已经使用 HuggingFace 模型的企业，能够快速对接现有模型资源。

• SGLang：伯克利出品，核心优势是“结构化生成性能强”。针对结构化输出场景（比如 JSON、代码）进行了优化，推理速度快，适合需要大量结构化输出的生产场景，比如 API 接口调用、数据格式化等。

2.4 选型建议

选型的核心原则是“匹配场景和需求”，无需追求最先进、最强大的工具，适合自己的才是最好的，具体建议如下：

• 如果只是自己玩、快速体验本地 LLM，不需要编写代码 → 选择 LM Studio 或 Jan，零门槛上手。

• 如果是开发者，需要对接代码、进行原型开发，或者需要兼容 OpenAI API → 选择 Ollama（简单易用）、LocalAI（兼容 OpenAI）或 llama.cpp（极致性能）。

• 如果是企业级生产部署，需要支持高并发、高可靠 → 选择 vLLM 或 TGI，其中 vLLM 吞吐量更高，适合高并发场景，TGI 更适合 HuggingFace 生态用户。

• 如果是边缘部署、资源受限（比如嵌入式设备） → 选择 llama.cpp，对硬件资源占用低，支持轻量化运行。

三、AI Agent 完整架构

理解了核心概念和推理工具后，我们再来看一个完整的 AI Agent 架构。一个成熟的 AI Agent，不仅仅是“LLM + 工具”的简单组合，而是由多个层次组成的完整系统，每个层次都有明确的职责，相互配合，才能实现“自主感知、自主思考、自主行动”的核心能力。

完整的 AI Agent 架构，从上层到下层，分为：感知层、认知层、记忆层、行动层、编排层、基础设施层，每个层次相互依赖、协同工作，构成一个闭环系统。

3.1 整体架构图

整体架构流程可概括为：感知层接收用户输入 → 认知层进行思考和规划 → 记忆层提供知识支撑和状态存储 → 行动层执行具体操作 → 编排层协调各模块流转 → 基础设施层保障系统稳定运行，最终将结果反馈给用户。

3.2 感知层（输入处理）

感知层是 AI Agent 与外界交互的“入口”，负责接收和处理用户的各类输入，将其转化为 AI Agent 能够理解的格式，相当于人类的“眼睛、耳朵”。

感知层的核心模块和作用如下：

• 多模态解析：处理文本、图像、语音、视频等多种类型的输入。比如将语音输入转化为文本（语音识别）、将图像输入转化为文字描述（OCR、图像识别），常见的工具和技术有 Whisper（语音识别）、CLIP（图像文本对齐）、OCR 工具等。

• 意图识别：理解用户输入的真实需求。用户的输入可能比较模糊，比如“查一下明天的天气”，意图识别模块需要准确判断出用户的需求是“查询明日天气”，并将其转化为 AI Agent 能够执行的指令，常见的实现方式有 NLU 模块、分类器等。

• 上下文管理：维护对话历史和交互上下文，确保 AI Agent 能够理解用户的连贯需求。比如用户先问“推荐一款手机”，再问“它的价格是多少”，上下文管理模块需要记住上一轮的“手机”，才能准确回答价格，常见的实现方式有滑动窗口、摘要压缩等。

3.3 认知层（大脑）

认知层是 AI Agent 的“核心大脑”，负责接收感知层处理后的输入，进行思考、推理、规划和决策，相当于人类的“大脑思考过程”。它是 AI Agent 智能性的核心，决定了 AI Agent 能够解决什么样的问题、做出什么样的决策。

认知层的核心模块和作用如下：

• LLM 基座：核心推理组件，负责基础的语言理解、推理和生成。所有的思考和决策，最终都依赖于 LLM 的能力，选择合适的 LLM 基座，是认知层高效工作的基础。

• 规划器 Planner：负责任务分解和执行计划制定。当用户提出一个复杂需求时，规划器需要将其分解为多个简单、可执行的子任务，并制定出执行顺序，比如用户需求“写一篇关于 AI Agent 的文章并发布到公众号”，规划器会分解为“确定文章大纲 → 撰写正文 → 编辑排版 → 发布公众号”等子任务，常见的实现方式有 ReAct、Plan-and-Execute 等框架。

• 推理引擎：负责复杂逻辑推理和多步推理。对于一些需要多步思考的问题，比如数学计算、逻辑分析，推理引擎会引导 LLM 逐步思考，确保推理过程的准确性，常见的实现方式有 Chain-of-Thought（思维链）等。

3.4 记忆层

记忆层负责存储 AI Agent 的各类知识和状态，为认知层提供思考和决策的支撑，相当于人类的“记忆系统”。根据记忆的时效性和用途，记忆层分为短期记忆、长期记忆、工作记忆和知识库/RAG 四类。

记忆层的核心模块和作用如下：

• 短期记忆：存储当前会话的上下文信息，时效性短，会话结束后可删除。比如当前对话的历史记录，用于保障对话的连贯性，常见的实现方式有 Context Window 管理。

• 长期记忆：存储跨会话的知识和信息，时效性长，可长期复用。比如用户的偏好、历史操作记录、常用知识等，常见的实现方式有向量数据库（Milvus、ChromaDB）。

• 工作记忆：存储任务执行过程中的中间状态和临时信息，任务结束后可清除。比如任务分解后的子任务、执行过程中的结果反馈等，常见的实现方式有 Redis、内存缓存。

• 知识库/RAG：存储外部领域知识，用于补充 LLM 自身的知识缺口。比如企业内部制度、行业规范、专业资料等，通过 RAG 技术，AI Agent 能够快速检索相关知识，为用户提供准确回答，常见的实现方式有 LangChain、LlamaIndex 对接向量数据库。

3.5 行动层（手脚）

行动层是 AI Agent 的“执行机构”，负责将认知层做出的决策，转化为具体的动作，与外部系统进行交互，相当于人类的“手脚”。它的核心作用是让 AI Agent 能够“落地执行”，而不仅仅是“纸上谈兵”。

行动层的核心模块和作用如下：

• Tools/Skills：具体的执行工具和能力函数，负责执行各类具体动作。比如搜索信息、调用 API、操作文件、控制硬件设备等，开发者可以根据需求自定义 Tools/Skills，常见的实现方式有 Function Calling。

• MCP 连接器：通过 MCP 协议，实现与外部工具、设备的标准化对接。无需为每个工具单独开发适配器，实现工具的“即插即用”，大大降低了开发成本，常见的实现方式有 MCP Server 和 MCP Toolkit。

• 代码执行：运行认知层生成的代码，实现复杂的逻辑操作。比如数据处理、自动化脚本执行等，为了保证安全，通常会在沙箱环境中运行代码，避免影响系统安全。

• 外部系统集成：对接各类外部系统，实现更广泛的功能扩展。比如对接数据库、ERP 系统、机器人控制系统等，让 AI Agent 能够融入企业现有的系统生态，常见的实现方式有 API Gateway。

3.6 编排层

编排层是 AI Agent 的“协调中心”，负责协调感知层、认知层、记忆层、行动层的工作，管理任务的流转和状态，确保各个模块能够协同工作，高效完成用户需求，相当于人类的“中枢神经系统”。

编排层的核心模块和作用如下：

• 工作流引擎：定义任务的执行流程和规则，引导各模块按照既定流程执行任务。比如定义“感知 → 认知 → 行动 → 反馈”的闭环流程，常见的框架有 LangGraph、Dify。

• 多 Agent 协调：当存在多个 AI Agent 时，负责协调它们的工作，实现分工协作，共同完成复杂任务。比如一个 Agent 负责信息检索，一个 Agent 负责内容生成，一个 Agent 负责编辑排版，多 Agent 协调模块负责分配任务、同步信息，常见的框架有 AutoGen、CrewAI。

• 状态管理：追踪任务的执行进度、处理执行过程中的异常情况。比如任务执行失败时，能够重新规划任务；任务中断时，能够保存中间状态，后续继续执行，常见的实现方式有状态机、DAG（有向无环图）。

• 人机协作：在关键节点引入人工介入，确保任务执行的准确性。比如复杂决策、敏感操作等场景，AI Agent 会将相关信息反馈给人类，由人类确认后再继续执行，常见的实现方式有 Human-in-the-loop。

3.7 基础设施层

基础设施层是 AI Agent 系统的“基石”，负责保障整个系统的稳定运行、安全可靠、可观测，为上层各模块提供支撑，相当于人类的“身体基础”。

基础设施层的核心模块和作用如下：

• 可观测性：负责日志收集、任务追踪、系统调试，帮助开发者了解系统的运行状态，及时发现和解决问题。常见的工具有 LangSmith（专门用于 LLM 应用的可观测性工具）、Prometheus、Grafana 等。

• 安全护栏：负责输入过滤、输出审核、权限管理，保障系统的安全。比如过滤恶意输入、审核 AI 生成的内容，避免出现违规、有害信息；控制用户权限，避免未授权操作，保障数据安全。

• 成本控制：负责监控 Token 用量、优化显存和内存占用、制定缓存策略，降低系统的运行成本。比如通过缓存复用常见的查询结果，减少 LLM 的调用次数；通过量化模型，降低显存占用。

• 评估系统：负责对 AI Agent 的性能、效果进行评测，通过 A/B 测试等方式，优化系统性能和用户体验。比如评测 AI Agent 的回答准确性、任务执行成功率、响应速度等指标，不断迭代优化。

四、轻量级方案：Ollama + LangChain + ChromaDB + Gradio

了解了完整架构后，我们从最基础、最易上手的轻量级方案开始，手把手教你搭建 AI Agent。这是一套本地化、低成本、快速验证的经典组合，无需复杂的部署环境，不需要大量的硬件资源，非常适合原型开发、个人项目和企业内部工具，开发者可以在本地快速搭建、调试和验证自己的 AI Agent 想法。

这套方案的核心优势是“简单易用、成本低、数据隐私安全”，所有组件都可以在本地运行，数据不出本地，适合隐私敏感场景；同时，组件之间的对接非常简单，有丰富的代码示例，新手也能快速上手。

4.1 架构图

这套轻量级方案的架构流程为：Ollama 提供本地 LLM 推理能力 → LangChain 负责编排和协调 → ChromaDB 作为向量数据库存储知识库 → Gradio 提供快速 Web 界面，方便用户交互 → 同时通过自定义 Skill/Tools 和 MCP 协议，扩展 AI Agent 的能力，实现完整的“感知-认知-记忆-行动”闭环。

4.2 Ollama — 本地 LLM 引擎

Ollama 是这套方案的“核心推理组件”，负责在本地运行开源大模型，为整个 AI Agent 提供思考和生成能力。它的安装和使用非常简单，支持 Windows、Mac、Linux 系统，甚至可以在树莓派等嵌入式设备上运行。

安装完成后，只需一行命令，就能启动一个开源大模型，比如：

ollama run qwen2:7b

这条命令会自动下载 Qwen2 7B 模型，并启动对话交互模式，你可以直接与模型对话，测试模型的能力。

Ollama 的核心优势如下：

• 数据不出本地，隐私安全：所有模型运行都在本地，用户数据不会上传到云端，适合处理内部文档、个人隐私数据等场景。

• 无 API 调用费用：无需调用第三方 API，无需支付额外的费用，适合个人开发者和小团队。

• 支持多种主流开源模型：除了 Qwen2，还支持 Llama、Mistral、DeepSeek 等多种主流开源模型，开发者可以根据需求灵活选择。

需要注意的是，Ollama 运行大模型需要一定的显存资源，7B 模型大约需要 8GB VRAM，如果进行量化处理（比如 4-bit 量化），显存占用可以降低到 4-6GB，普通的游戏本也能满足需求。

4.3 LangChain — 编排框架

LangChain 是这套方案的“编排核心”，负责连接 Ollama、ChromaDB、Gradio 等组件，实现任务的编排、工具的调用、记忆的管理，相当于 AI Agent 的“中枢神经”。它的核心价值是“降低开发成本”，提供了丰富的组件和接口，开发者无需从零开发，就能快速搭建 AI Agent。

首先，我们需要安装 LangChain 相关依赖，然后通过简单的代码，就能连接本地 Ollama，创建 AI Agent：

from langchain_community.llms import Ollama
from langchain.agents import create_react_agent

# 连接本地 Ollama，指定使用的模型
llm = Ollama(model="qwen2:7b")

# 定义工具（这里可以自定义工具，比如搜索工具、计算工具等）
tools = [search_tool, calculator_tool, your_custom_tool]

# 创建 React Agent，让 LLM 能够自主决定调用哪个工具
agent = create_react_agent(llm, tools, prompt)

LangChain 的核心能力如下：

• Chain：串联多个处理步骤，实现复杂的逻辑流程。比如“接收用户输入 → 检索知识库 → 调用 LLM 生成回答 → 反馈给用户”，可以通过 Chain 串联起来，实现自动化执行。

• Agent：让 LLM 能够自主决定调用哪个工具、执行哪个步骤。比如用户提出一个需要搜索的问题，Agent 会自主调用搜索工具，获取信息后，再生成回答。

• Retriever：对接向量数据库，实现 RAG 功能，快速检索知识库中的相关知识，补充 LLM 的知识缺口。

• Memory：管理对话历史和上下文信息，保障对话的连贯性，让 AI Agent 能够记住用户的上一轮提问，理解连贯需求。

4.4 ChromaDB — 向量数据库

ChromaDB 是这套方案的“记忆核心”，作为轻量级向量数据库，负责存储知识库中的文档向量，实现知识的快速检索和复用。它的核心优势是“简单易用、无需额外部署”，纯 Python 实现，能够直接嵌入到 Python 项目中，数据可以持久化到本地文件，非常适合中小规模的知识库场景。

下面是 ChromaDB 与 LangChain 集成的代码示例，用于创建知识库并实现检索功能：

from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import OllamaEmbeddings

# 使用 Ollama 的 embedding 模型，将文档转化为向量
embeddings = OllamaEmbeddings(model="nomic-embed-text")

# 创建向量库，将自定义文档传入，实现数据持久化
vectorstore = Chroma.from_documents(
    documents=your_docs,  # your_docs 是你的自定义文档列表
    embedding=embeddings,
    persist_directory="./chroma_db"  # 数据持久化到本地目录
)

# 将向量库转化为 Retriever，用于后续的知识检索
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})  # k=3 表示检索前3条相关知识

ChromaDB 的核心特点如下：

• 纯 Python 实现，无需额外服务：不需要部署独立的数据库服务，直接嵌入到 Python 项目中，使用简单。

• 数据持久化：支持将向量数据持久化到本地文件，下次启动项目时，无需重新导入文档，直接加载即可。

• 适合中小规模场景：能够高效处理几十万条以内的文档向量，满足个人项目和企业内部工具的需求。

4.5 Gradio — 快速 Web 界面

Gradio 是这套方案的“交互入口”，负责提供快速、简单的 Web 界面，让用户能够通过浏览器与 AI Agent 进行交互，无需编写代码，非常适合原型展示和内部使用。它的核心优势是“零代码/低代码”，只需几行代码，就能创建一个美观、易用的 Web 界面。

下面是 Gradio 与 AI Agent 集成的代码示例，创建一个简单的对话界面：

import gradio as gr

# 定义对话函数，接收用户输入和对话历史，返回 AI 回答
def chat(message, history):
    # 调用之前创建的 Agent，处理用户输入
    response = agent.invoke({"input": message})
    # 返回 AI 生成的回答
    return response["output"]

# 创建 ChatInterface 界面，设置标题和交互逻辑
demo = gr.ChatInterface(chat, title="我的 AI 助手")
# 启动 Web 服务，默认端口是 7860，浏览器访问 http://localhost:7860 即可使用
demo.launch()

运行这段代码后，会自动启动 Web 服务，你可以通过浏览器访问对应的地址，与 AI Agent 进行对话交互。Gradio 还支持自定义界面样式、添加输入输出组件，满足不同的交互需求。

4.6 知识库 — ChromaDB + RAG

知识库是 AI Agent 的“知识储备”，通过 ChromaDB + RAG 技术，我们可以将自定义的领域知识导入到 AI Agent 中，让它成为“专属顾问”。比如导入企业内部的电力巡检规范，AI Agent 就能回答相关的专业问题。

下面是将 ChromaDB 检索器封装为工具，集成到 LangChain Agent 中的代码示例：

from langchain.tools.retriever import create_retriever_tool

# 将 ChromaDB 检索器封装为工具，指定工具名称和描述
knowledge_tool = create_retriever_tool(
    retriever,  # 之前创建的 ChromaDB 检索器
    name="电力规范知识库",  # 工具名称
    description="查询电力巡检规范、操作手册等内部文档，当用户询问相关问题时，调用此工具"  # 工具描述，让 LLM 知道何时调用
)

# 将知识库工具添加到 Agent 的工具列表中
tools.append(knowledge_tool)

这样，当用户询问与电力规范相关的问题时，AI Agent 会自主调用“电力规范知识库”工具，检索相关知识，然后结合 LLM 的推理能力，生成准确的回答。

4.7 Skill/Tools — 自定义能力函数

Skill/Tools 是 AI Agent 的“行动能力”，通过自定义工具，我们可以让 AI Agent 执行具体的动作，比如查询设备状态、发送控制指令等。LangChain 提供了简单的装饰器，让我们能够快速定义自定义工具。

下面是自定义工具的代码示例，实现查询设备状态和发送巡检指令的功能：

from langchain.tools import tool

# 自定义工具：查询指定设备的实时运行状态
@tool
def query_device_status(device_id: str) -> str:
    """查询指定设备的实时运行状态，参数 device_id 是设备的唯一标识"""
    # 调用实际的 API，获取设备状态（这里替换为你的真实 API 调用逻辑）
    status = your_api.get_status(device_id)
    # 返回设备状态信息
    return f"设备 {device_id} 状态：{status}"

# 自定义工具：向巡检机器人发送任务指令
@tool  
def send_inspection_command(robot_id: str, task: str) -> str:
    """向巡检机器人发送任务指令，参数 robot_id 是机器人唯一标识，task 是任务描述"""
    # 调用机器人控制 API，发送指令（这里替换为你的真实 API 调用逻辑）
    result = robot_control_api.dispatch(robot_id, task)
    # 返回指令执行结果
    return result

# 将自定义工具添加到 Agent 的工具列表中
tools.extend([query_device_status, send_inspection_command])

自定义工具的关键是“明确工具的功能和参数”，并通过文档字符串（docstring）描述清楚，让 LLM 能够理解工具的用途，以及何时、如何调用工具。

4.8 MCP — 标准化接入

通过 MCP 协议，我们可以实现工具的“即插即用”，无需为每个工具单独编写对接代码。LangChain 提供了 MCP 集成工具，只需简单配置，就能对接遵循 MCP 协议的工具和设备。

下面是 MCP 与 LangChain 集成的代码示例：

from langchain_mcp import MCPToolkit

# 初始化 MCP Toolkit，指定 MCP Server 的地址
mcp_toolkit = MCPToolkit(server_url="http://localhost:3000")

# 获取所有遵循 MCP 协议的工具
mcp_tools = mcp_toolkit.get_tools()

# 将 MCP 工具添加到 Agent 的工具列表中，实现即插即用
tools.extend(mcp_tools)

这样，所有接入 MCP Server 的工具，都能直接被 AI Agent 调用，无需额外开发适配代码，大大提高了开发效率和工具的复用性。

4.9 完整示例

下面是这套轻量级方案的完整代码示例，整合了 Ollama、LangChain、ChromaDB、Gradio，实现了一个简单的知识库问答 AI Agent：

from langchain_community.llms import Ollama
from langchain_community.embeddings import OllamaEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.chains import RetrievalQA
import gradio as gr

# 1. 初始化模型和嵌入模型
llm = Ollama(model="qwen2:7b")  # 本地 LLM 模型
embeddings = OllamaEmbeddings(model="nomic-embed-text")  # 嵌入模型，用于文档向量化

# 2. 加载知识库（这里替换为你的自定义文档列表）
# your_docs = [Document(page_content="文档内容1", metadata={"source": "文档1"}), ...]
# 这里假设已经提前导入了文档，直接加载本地向量库
vectorstore = Chroma(
    persist_directory="./my_knowledge_base",  # 向量库持久化目录
    embedding_function=embeddings
)

# 3. 创建 RAG Chain，实现知识库问答
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    retriever=vectorstore.as_retriever(search_kwargs={"k": 3}),  # 检索前3条相关知识
    return_source_documents=True  # 返回回答的来源文档，提高可信度
)

# 4. 定义对话函数，对接 Gradio 界面
def answer(question, history):
    # 调用 RAG Chain，处理用户提问
    result = qa_chain.invoke({"query": question})
    # 提取回答来源，显示给用户
    sources = [doc.metadata.get("source", "") for doc in result["source_documents"]]
    # 拼接回答和来源，返回给用户
    return f"{result['result']}\n\n📎 来源: {', '.join(set(sources))}"

# 5. 创建 Gradio Web 界面，启动服务
gr.ChatInterface(answer, title="知识库问答 AI 助手").launch()

运行这段代码后，你可以通过浏览器访问 Web 界面，输入与知识库相关的问题，AI Agent 会检索知识库中的相关知识，生成准确的回答，并显示回答的来源，非常适合内部知识库查询场景。

4.10 适用场景

这套轻量级方案有明确的适用场景和局限性，我们可以根据自己的需求，判断是否适合使用这套方案：

• 适合的场景：个人项目开发、企业内部工具（如内部知识库问答）、快速原型验证（验证 AI Agent 的想法是否可行）、数据隐私敏感场景（数据不出本地）、小团队项目（成本低、开发效率高）。

• 不适合的场景：高并发生产环境（Ollama 不支持高并发）、需要顶级推理能力的场景（本地开源模型的推理能力有限）、复杂多 Agent 协作场景（LangChain 的编排能力有限）、大规模文档场景（ChromaDB 适合几十万条以内的文档）。

五、MCP vs ROS：两种”通信协议”的对比

在讨论 AI Agent 与机器人系统的对接时，经常会提到 MCP 和 ROS 两种协议。很多开发者会混淆这两种协议的定位和用途，其实它们在设计哲学上非常相似，但作用领域和核心需求完全不同。简单来说，MCP 之于 AI Agent，就像 ROS 之于机器人系统，都是“胶水层”，负责解决“组件对接碎片化”的问题，但对接的对象和场景截然不同。

5.1 核心相似点

MCP 和 ROS 的设计理念和核心价值非常相似，都是为了解决“组件对接复杂”的问题，实现“标准化、即插即用”，具体相似点如下：

共同点	MCP	ROS
解决的问题	AI 工具对接碎片化，每个工具需要单独适配 LLM	机器人组件对接碎片化，每个传感器、执行器需要单独写驱动
设计理念	标准化协议，实现工具的即插即用，降低适配成本	标准化通信，实现机器人组件的即插即用，降低开发成本
架构模式	Server/Client（服务器/客户端）模式，工具作为客户端，对接 MCP Server	Node/Topic/Service（节点/话题/服务）模式，组件作为节点，通过话题和服务通信
核心价值	不用为每个工具写适配器，提高工具复用性，加快 AI Agent 开发速度	不用为每个传感器写驱动，提高组件复用性，加快机器人开发速度
一句话总结：MCP 和 ROS 都是“标准化的胶水层”，核心目的都是“降低对接成本、实现组件复用”，只是应用的领域不同。

5.2 关键区别

虽然 MCP 和 ROS 的设计理念相似，但由于它们对接的对象、应用的场景不同，存在很多关键区别，具体如下：

维度	MCP	ROS
通信对象	LLM ↔ 软件工具（如 API、数据库、自定义函数等），主要是软件层面的对接	机器人节点 ↔ 节点（如传感器、执行器、控制算法等），主要是硬件和软件的对接
实时性	弱实时性，秒级响应即可满足需求。AI Agent 的工具调用，通常不需要毫秒级的响应速度	强实时性，需要毫秒级控制。机器人的运动控制、传感器数据采集，需要极高的实时性，否则会影响机器人的运行
数据类型	主要是文本、JSON、语义等结构化或半结构化数据，用于 LLM 的理解和处理	主要是传感器数据、控制指令、点云等二进制数据，用于机器人的控制和感知
典型场景	AI Agent 的工具调用、知识库检索、API 对接等软件层面的场景	机器人的运动控制、SLAM（即时定位与地图构建）、轨迹规划等硬件控制场景

5.3 在具身智能中的协作

具身智能是 AI Agent 的重要发展方向，指的是 AI Agent 拥有物理身体，能够在物理世界中感知和行动（比如机器人）。在具身智能系统中，MCP 和 ROS 并不是替代关系，而是上下游协作关系，各自负责不同的环节，共同实现“认知-执行”的闭环。

它们的协作分工如下：

• MCP：负责处理“认知层”的工具调用。比如 AI Agent 需要查询机器人的运行状态、获取环境信息，通过 MCP 协议对接相关的软件工具，获取所需的数据，为认知决策提供支撑。

• ROS：负责处理“执行层”的实时控制。比如 AI Agent 做出“移动到某个位置”的决策后，通过 ROS 协议对接机器人的运动控制节点，发送控制指令，控制机器人的运动，同时接收传感器数据，反馈执行结果。

简单来说，在具身智能系统中，MCP 负责“大脑与软件工具的通信”，ROS 负责“大脑与物理身体的通信”，两者协同工作，让 AI Agent 既能“思考”，也能在物理世界中“行动”。

六、生产级方案：vLLM + LangGraph + Milvus + FastAPI

当轻量级方案无法满足需求时，比如需要对外提供商业服务、支持高并发请求、处理复杂任务流程，就需要升级到生产级方案。这套生产级方案的核心优势是“高吞吐、高可靠、可扩展”，能够支持大规模部署，为企业级 AI Agent 提供稳定的支撑，适合对外提供 API 服务、复杂决策系统等场景。

这套方案与轻量级方案的核心区别在于：用高性能的 vLLM 替代 Ollama，用复杂编排能力的 LangGraph 替代 LangChain，用分布式向量数据库 Milvus 替代 ChromaDB，用生产级 API 框架 FastAPI 替代 Gradio，全方位提升系统的性能、可靠性和可扩展性。

6.1 架构图

这套生产级方案的架构流程为：vLLM 提供高性能 LLM 推理能力，支持高并发请求 → LangGraph 负责复杂任务编排和状态管理，支持循环、条件分支等复杂流程 → Milvus 作为分布式向量数据库，存储大规模知识库 → FastAPI 提供生产级 API 服务，支持流式输出、权限管理等功能 → 同时整合可观测性、安全护栏等基础设施，保障系统稳定运行，对外提供高质量的 AI Agent 服务。

6.2 vLLM — 高性能推理引擎

vLLM 是这套生产级方案的“核心推理组件”，替代了轻量级方案中的 Ollama，核心优势是“高吞吐、高显存利用率”，能够支持高并发请求，适合生产环境部署。它的底层采用 PagedAttention 技术，类似于操作系统的虚拟内存技术，能够将 GPU 显存分页管理，大幅提升显存利用率，避免显存浪费，吞吐量是 Ollama 的 10 倍以上。

下面是 vLLM 的启动命令示例，用于启动一个生产级推理服务，兼容 OpenAI API 格式：

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2-7B-Instruct \  # 指定使用的模型
    --tensor-parallel-size 2 \  # 多卡并行，使用 2 块 GPU
    --gpu-memory-utilization 0.9  # 显存利用率设置为 90%，充分利用硬件资源

vLLM 的核心技术优势如下：

• PagedAttention 技术：显存利用率提升 2-4 倍，能够在有限的显存资源下，同时处理更多的并发请求。

• Continuous Batching：动态批处理技术，无需等待凑齐一批请求再进行推理，而是动态接收请求、动态处理，大幅提升吞吐量和响应速度。

• Tensor Parallelism：支持多卡并行，能够将单个大模型拆分到多块 GPU 上运行，提升推理速度和并发能力。

• 兼容 OpenAI API：提供与 OpenAI API 兼容的接口，现有对接 OpenAI API 的代码，无需修改，就能直接替换为 vLLM，降低迁移成本。