十分钟实用教程 | MCP Agent Graph: 基于上下文工程的多智能体系统构建指南

转载自公众号：敢敢AUTOHUB

1. 引言: 从单一模型到多智能体协作

1.1 大语言模型的能力边界

大语言模型(LLM)的发展经历了从简单文本生成到复杂推理的演进过程。早期的应用场景主要集中在问答、翻译、摘要等相对独立的任务上，模型作为一个无状态的推理引擎，接收输入并产生输出。然而，随着应用场景的深化，开发者们逐渐意识到单一模型在处理复杂、多步骤任务时面临着显著的局限性。这些局限性主要体现在以下几个方面: 模型无法访问实时数据，缺乏与外部系统交互的能力，难以维护跨会话的上下文信息，以及在长链条任务中容易出现推理偏差。

为了突破这些限制，AI Agent 的概念应运而生。与传统的 LLM 应用不同，智能体是一个具备自主决策能力的系统实体。它不仅能够理解用户的目标，还能够规划执行路径、调用外部工具、观察执行结果，并根据反馈动态调整策略。智能体的核心能力包括: 目标理解与任务分解、工具选择与调用、环境感知与状态维护、迭代优化与自我修正。这种从被动响应到主动执行的转变，使得 AI 系统能够处理更加开放和复杂的现实任务。

当单个智能体面对跨领域、多阶段的复杂任务时，其能力仍然受限。类比人类社会中的团队协作，多智能体系统(Multi-Agent System, MAS)通过让多个专业化的智能体协同工作，实现了能力的叠加与互补。例如，一个数据分析流程可能需要: 数据采集智能体负责从多个数据源获取原始数据，数据清洗智能体处理缺失值和异常值，分析智能体执行统计计算和建模，报告生成智能体将结果整理成可读的报告。每个智能体专注于其擅长的领域，通过协作完成单一智能体难以胜任的复杂任务。

项目地址：https://github.com/keta1930/mcp-agent-graph

2. MCP Agent Graph 系统架构

2.1 整体架构设计

MCP Agent Graph 采用分层架构设计，从底向上依次为: 基础设施层、协议层、引擎层和应用层。这种分层设计确保了系统的可扩展性和各组件间的解耦。

系统架构图:

基础设施层提供数据存储(MongoDB)、文件管理(MinIO)和缓存服务，为上层提供可靠的持久化支持。协议层实现了 MCP(Model Context Protocol)标准，定义了智能体与外部工具交互的规范接口。引擎层是系统的核心，包含智能体运行时、工作流引擎、记忆管理器等关键组件。应用层则提供了可视化的用户界面，支持智能体的创建、配置、测试和部署。

2.2 数据流与交互模式

系统中的数据流遵循清晰的路径: 用户请求首先到达 API 网关，经过认证和路由后分发到相应的服务。对于对话请求，系统会加载智能体配置、获取历史上下文、执行推理循环，并将结果返回给用户。整个过程中，记忆管理器负责维护短期和长期记忆，MCP 客户端负责与外部工具通信。

用户交互流程:

3. 核心组件深度解析

3.1 智能体(Agent)

智能体是 MCP Agent Graph 中最基本的执行单元。每个智能体都有明确的职责定义，包括系统提示词、可用工具列表、模型配置等。智能体的设计遵循单一职责原则，一个智能体专注于完成一类特定的任务。

智能体的核心属性包括:

from typing import List
from pydantic import BaseModel, Field, field_validator

class AgentConfig(BaseModel):
    """Agent配置数据模型"""
    name: str = Field(..., description="Agent唯一名称")
    card: str = Field(..., description="Agent能力描述卡片")
    model: str = Field(..., description="使用的模型名称")
    instruction: str = Field(default="", description="Agent的系统提示词")
    max_actions: int = Field(default=50, description="最大工具调用次数，范围1-200")
    mcp: List[str] = Field(default_factory=list, description="可用的MCP服务器名称列表")
    system_tools: List[str] = Field(default_factory=list, description="可用的系统内置工具列表")
    category: str = Field(..., description="Agent分类，如coding, analysis, writing等")
    tags: List[str] = Field(default_factory=list, description="Agent标签列表")

    @field_validator('name')
    @classmethod
    def validate_name(cls, v):
        if not v or '/' in v or '\\' in v or '.' in v:
            raise ValueError('名称不能包含特殊字符 (/, \\, .)')
        return v

    @field_validator('max_actions')
    @classmethod
    def validate_max_actions(cls, v):
        if v < 1 or v > 200:
            raise ValueError('max_actions 必须在 1-200 范围内')
        return v

创建智能体的服务层代码:

class AgentService:
    """Agent 服务 - 负责 Agent 业务逻辑和数据库交互"""

    async def create_agent(self, agent_config: Dict[str, Any], user_id: str) -> Dict[str, Any]:
        """创建 Agent"""
        # 验证配置
        is_valid, error_msg = await self.validate_agent_config(agent_config, user_id)
        if not is_valid:
            return {"success": False, "error": f"Agent 配置验证失败: {error_msg}"}

        # 创建 Agent
        agent_id = await mongodb_client.agent_repository.create_agent(agent_config, user_id)

        if agent_id:
            # 同时创建对应的 memory 文档
            agent_name = agent_config.get('name')
            await mongodb_client.memories_collection.insert_one({
                "user_id": user_id,
                "owner_type": "agent",
                "owner_id": agent_name,
                "memories": {},
                "created_at": datetime.now(),
                "updated_at": datetime.now()
            })
            return {"success": True, "agent_id": agent_id, "agent_name": agent_name}
        return {"success": False, "error": "创建 Agent 失败"}

智能体的执行采用 ReAct(Reasoning and Acting)模式，这是一种将推理与行动交织进行的范式。在每个步骤中，智能体首先进行推理分析当前状态，然后决定采取的行动(可能是调用工具或生成回复)，最后观察行动结果并更新状态。

3.2 工作流图(Graph)

工作流图是编排多个智能体协作的核心机制。通过将智能体作为节点、定义节点间的连接关系，可以构建出复杂的任务处理流程。工作流图支持多种拓扑结构:

3.3 记忆系统(Memory)

记忆系统为智能体提供了跨会话的信息持久化能力。系统区分短期记忆和长期记忆两种类型:

短期记忆用于维护当前会话的上下文，包括对话历史、中间结果等。短期记忆的生命周期与会话绑定，会话结束后可选择性地将关键信息转存到长期记忆。

长期记忆则是持久化的知识存储，包括用户偏好、领域知识、历史交互的总结等。长期记忆通过向量检索实现相关信息的快速召回，使智能体能够"记住"过去的经验。

以下是记忆服务的核心实现:

from datetime import datetime
from typing import Dict, Any, List
from app.infrastructure.database.mongodb import mongodb_client

class MemoryService:
    """记忆服务类"""

    def __init__(self):
        self.mongodb_client = mongodb_client

    async def get_all_memories(self, user_id: str) -> Dict[str, Any]:
        """获取用户的所有记忆元数据"""
        cursor = self.mongodb_client.memories_collection.find({"user_id": user_id})
        docs = await cursor.to_list(length=None)

        result = []
        for doc in docs:
            memories = doc.get("memories", {})
            categories_count = len(memories)
            total_items = sum(len(cat.get("items", [])) for cat in memories.values())

            result.append({
                "owner_type": doc.get("owner_type"),
                "owner_id": doc.get("owner_id"),
                "categories_count": categories_count,
                "total_items": total_items,
                "created_at": doc.get("created_at").isoformat(),
                "updated_at": doc.get("updated_at").isoformat()
            })
        return {"success": True, "data": result}

    async def get_owner_memories(
        self, user_id: str, owner_type: str, owner_id: str
    ) -> Dict[str, Any]:
        """获取特定智能体的记忆"""
        doc = await self.mongodb_client.memories_collection.find_one({
            "user_id": user_id,
            "owner_type": owner_type,
            "owner_id": owner_id
        })
        if doc:
            return {"success": True, "memories": doc.get("memories", {})}
        return {"success": False, "message": "记忆不存在"}

3.4 提示词中心(Prompt Center)

提示词中心提供了统一管理可复用提示词模板的能力。通过将常用的提示词模式抽象为模板，开发者可以避免重复编写相似的提示词，同时确保风格和质量的一致性。提示词模板支持变量插值，可以在运行时根据具体场景填充参数。

4. MCP Agent Graph 安装与部署

4.1 系统要求

在部署 MCP Agent Graph 之前，请确保您的系统满足以下要求：

4.2 快速部署步骤

4.2.1 克隆项目

git clone <https://github.com/keta1930/mcp-agent-graph.git>
cd mcp-agent-graph

4.2.2 配置并启动 Docker 服务

进入 Docker 配置目录并创建环境配置文件：

cd docker/mag_services
cp .env.example .env

编辑 .env 文件，配置必要的参数：

# MongoDB 配置
MONGO_ROOT_USERNAME=admin
MONGO_ROOT_PASSWORD=securepassword123
MONGO_DATABASE=mcp-agent-graph
MONGO_PORT=27017

# MongoDB Express 配置 (数据库 Web 管理界面)
MONGO_EXPRESS_PORT=8081
MONGO_EXPRESS_USERNAME=admin
MONGO_EXPRESS_PASSWORD=expresspwd123

# MinIO 配置 (对象存储服务)
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin123
MINIO_API_PORT=9010
MINIO_CONSOLE_PORT=9011
MINIO_SECURE=false

# JWT 配置（生成密钥: python mag/scripts/generate_jwt_secret.py）
JWT_SECRET_KEY=your_generated_secret_key_here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7

# 超级管理员配置
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123

启动 Docker 服务：

docker-compose up -d

验证服务状态：

docker-compose ps

启动后可访问以下服务：

4.2.3 安装 Python 依赖并启动后端

方式一：使用 uv (推荐)

uv 是一个快速的 Python 包管理器：

# 安装 uv (如果尚未安装)
curl -LsSf <https://astral.sh/uv/install.sh> | sh

# 返回项目根目录并同步依赖
uv sync

# 启动后端服务
cd mag
uv run python main.py

方式二：使用 pip

cd ../..  # 返回项目根目录
pip install -r requirements.txt

cd mag
python main.py

后台运行（生产环境）：

nohup python main.py > ../app.log 2>&1 &

4.2.4 访问应用

打开浏览器访问：http://localhost:9999

管理员登录：使用 .env 配置的 ADMIN_USERNAME 和 ADMIN_PASSWORD

新用户注册：使用邀请码注册（管理员在后台生成邀请码）

其他访问端点：

5. 本地部署实践: Ollama + Qwen3 集成

5.1 为什么选择本地部署

在生产环境中，将 LLM 部署在本地具有多方面的优势。首先是数据隐私保护，敏感数据无需传输到外部 API 服务器。其次是低延迟响应，本地推理避免了网络往返时间。第三是成本可控，避免了按调用次数计费的模式。最后是离线可用性，即使在网络不稳定的环境下也能正常工作。

Ollama 是一个轻量级的本地 LLM 运行框架，它简化了模型的下载、配置和运行过程。Qwen3 是阿里巴巴开源的高质量语言模型，支持中英文双语，具有优秀的推理能力。将 Ollama + Qwen3 与 MCP Agent Graph 集成，可以构建一套完全本地化的智能体系统。

5.2 Ubuntu 环境下 Ollama 安装与配置

5.2.1 安装 Ollama

# 一键安装 Ollama (Ubuntu/Debian)
curl -fsSL <https://ollama.com/install.sh> | sh

# 验证安装
ollama --version

5.2.2 配置 Ollama 为系统服务

在 Ubuntu 服务器环境中，建议将 Ollama 配置为 systemd 服务以便自动启动和管理：

# 创建 systemd 服务文件
sudo tee /etc/systemd/system/ollama.service > /dev/null <<EOF
[Unit]
Description=Ollama Service
After=network-online.target

[Service]
ExecStart=/usr/local/bin/ollama serve
User=ollama
Group=ollama
Restart=always
RestartSec=3
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_MODELS=/var/lib/ollama/models"

[Install]
WantedBy=default.target
EOF

# 创建 ollama 用户和目录
sudo useradd -r -s /bin/false -m -d /var/lib/ollama ollama
sudo mkdir -p /var/lib/ollama/models
sudo chown -R ollama:ollama /var/lib/ollama

# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable ollama
sudo systemctl start ollama

# 检查服务状态
sudo systemctl status ollama

5.2.3 环境变量配置

# 编辑环境配置文件
sudo vim /etc/environment

# 添加以下内容：
OLLAMA_MODELS=/var/lib/ollama/models
OLLAMA_HOST=0.0.0.0:11434

# 或者添加到用户 profile
echo 'export OLLAMA_HOST=0.0.0.0:11434' >> ~/.bashrc
source ~/.bashrc

5.3 下载并运行 Qwen3 模型

Ollama 提供了多个 Qwen3 模型版本，可根据硬件配置选择:

# 下载并运行 Qwen3 8B 模型(推荐)
ollama run qwen3:8b

# 或者选择更小的模型以适应有限硬件
ollama run qwen3:4b

# 仅下载模型不运行
ollama pull qwen3:8b

首次运行时会自动下载模型文件，下载完成后即可开始对话测试。

5.4 验证 Ollama API 服务

Ollama 运行后会在本地启动一个 RESTful API 服务，默认监听 http://localhost:11434。可以通过以下方式验证服务状态:

# 检查服务状态
curl <http://localhost:11434/api/tags>

# 预期返回已安装模型列表:
# {"models":[{"name":"qwen3:8b","modified_at":"...","size":...}]}

5.5 在 MCP Agent Graph 中配置 Ollama

MCP Agent Graph 支持 OpenAI 兼容的 API 格式，而 Ollama 提供了这种兼容接口。配置步骤如下:

步骤一: 修改环境配置

在 MCP Agent Graph 的 .env 文件中添加 Ollama 配置:

# Ollama 配置
OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_API_KEY=ollama  # Ollama 不需要真实密钥，但某些客户端要求非空

步骤二: 在模型管理中添加 Ollama 模型

登录 MCP Agent Graph 后台，进入"工作空间 → 模型管理"页面:

点击"添加模型"，填写以下配置:

模型名称: Qwen3-8B-Local
模型标识: qwen3:8b
API 基础地址: <http://localhost:11434/v1>
API 密钥: ollama
模型类型: chat

步骤三: 创建使用 Ollama 的智能体

在"智能体管理"页面创建新智能体，选择刚才添加的 Qwen3 模型:

6. 完整部署流程脚本

以下是一个完整的部署脚本，用于在本地环境中部署 MCP Agent Graph + Ollama:

#!/bin/bash
# deploy.sh - MCP Agent Graph + Ollama 本地部署脚本

set -e

echo "=== MCP Agent Graph 本地部署脚本 ==="

# 1. 检查 Docker 是否安装
if ! command -v docker &> /dev/null; then
    echo "错误: Docker 未安装，请先安装 Docker"
    exit 1
fi

# 2. 安装 Ollama
echo ">>> 安装 Ollama..."
if ! command -v ollama &> /dev/null; then
    curl -fsSL <https://ollama.com/install.sh> | sh
fi

# 3. 下载 Qwen3 模型
echo ">>> 下载 Qwen3 模型..."
ollama pull qwen3:8b

# 4. 克隆 MCP Agent Graph 项目
echo ">>> 克隆项目..."
if [ ! -d "mcp-agent-graph" ]; then
    git clone <https://github.com/keta1930/mcp-agent-graph.git>
fi
cd mcp-agent-graph

# 5. 配置环境变量
echo ">>> 配置环境变量..."
cd docker/mag_services
if [ ! -f ".env" ]; then
    cp .env.example .env
    # 修改默认配置
    sed -i 's/ADMIN_USERNAME=.*/ADMIN_USERNAME=admin/' .env
    sed -i 's/ADMIN_PASSWORD=.*/ADMIN_PASSWORD=admin123/' .env
fi

# 6. 启动 Docker 服务
echo ">>> 启动 Docker 服务..."
docker-compose up -d

# 7. 等待服务就绪
echo ">>> 等待服务启动..."
sleep 10

# 8. 安装 Python 依赖并启动后端
cd ../..
echo ">>> 安装 Python 依赖..."
pip install -r requirements.txt

echo ">>> 启动后端服务..."
cd mag
nohup python main.py > ../app.log 2>&1 &

echo "=== 部署完成 ==="
echo "访问地址: <http://localhost:9999>"
echo "管理员账号: admin"
echo "管理员密码: admin123"
echo ""
echo "Ollama API: <http://localhost:11434>"
echo "已安装模型: qwen3:8b"

7. 总结

本文深入介绍了 MCP Agent Graph 这一基于上下文工程理念构建的多智能体系统框架。从理论基础到实践部署，它提供了一个完整的实验和开发平台，无论是学习多智能体系统的原理，还是构建实际的应用产品，都是一个理想的起点。

参考资源

https://github.com/keta1930/mcp-agent-graph

https://keta1930.github.io/mcp-agent-graph/

https://modelcontextprotocol.io/specification