零基础玩转MCP-Agent：用Ollama本地大模型构建智能工作流编排系统

【免费下载链接】mcp-agent Build effective agents using Model Context Protocol and simple workflow patterns 项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent

你是否还在为复杂任务的多步骤协调而烦恼？是否想在本地环境中运行强大的AI工作流而不依赖云端服务？本文将带你通过MCP-Agent（Model Context Protocol Agent）框架，使用Ollama本地大模型实现Orchestrator工作流，轻松搞定任务拆分、并行处理和结果合成。读完本文，你将掌握：

• 5分钟搭建Ollama+MCP-Agent开发环境
• 用Orchestrator模式实现任务自动拆解与分配
• 3种工作流规划策略的实战应用
• 完整的本地AI工作流监控与优化方案

技术架构概览

MCP-Agent的Orchestrator工作流是一种基于模型上下文协议（Model Context Protocol）的任务协调机制，能够将复杂目标拆解为可并行执行的子任务，并调度不同能力的Agent协同完成。其核心优势在于：

• 去中心化执行：无需中心化服务器，支持本地部署
• 动态任务规划：根据实时结果调整执行步骤
• 多模型兼容：无缝对接Ollama、兼容接口等多种模型提供商
• 资源可控：精确监控token消耗与执行成本

图1：Orchestrator工作流的核心组件与数据流向 官方文档

环境快速部署

1. 基础环境准备

首先克隆项目仓库并安装依赖：

git clone https://gitcode.com/GitHub_Trending/mc/mcp-agent
cd mcp-agent
pip install uv
uv sync
uv pip install -r requirements.txt

2. Ollama模型配置

安装Ollama并下载所需模型：

# 安装Ollama (Linux示例)
curl https://ollama.ai/install.sh | sh

# 启动Ollama服务
systemctl start ollama

# 拉取适合工作流编排的模型
ollama pull llama3:8b
ollama pull mistral:7b-instruct

3. MCP-Agent配置

创建Ollama专用配置文件：

cd examples/model_providers/mcp_basic_ollama_agent
cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml

编辑配置文件，添加Ollama连接信息：

# mcp_agent.secrets.yaml
ollama_api_base: "http://localhost:11434/v1"
ollama_api_key: "ollama"  # Ollama默认无需真实API密钥

Ollama模型集成实现

MCP-Agent通过OllamaAugmentedLLM类实现与Ollama的无缝集成，该类继承自兼容接口，同时针对本地模型特点进行了优化：

# src/mcp_agent/workflows/llm/augmented_llm_ollama.py
class OllamaAugmentedLLM(OpenAIAugmentedLLM):
    """
    Augmented LLM implementation for Ollama models with context management
    This implementation uses Ollama's OpenAI-compatible ChatCompletion API.
    """
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.provider = "Ollama"
        self.context_window = 4096  # 根据Ollama模型实际能力调整
        
    async def _create_client(self):
        # 使用Ollama的兼容端点
        return AsyncOpenAI(
            base_url=self.config.base_url or "http://localhost:11434/v1",
            api_key=self.config.api_key or "ollama",  # Ollama默认API密钥
        )

基础使用示例

以下是使用Ollama模型的最小示例代码：

# examples/model_providers/mcp_basic_ollama_agent/main.py
import asyncio
from mcp_agent.app import MCPApp
from mcp_agent.workflows.llm.augmented_llm_ollama import OllamaAugmentedLLM
from mcp_agent.workflows.llm.augmented_llm import RequestParams

app = MCPApp(name="ollama_orchestrator_demo")

async def run_ollama_workflow():
    async with app.run() as agent_app:
        # 初始化Ollama增强型LLM
        llm = OllamaAugmentedLLM(
            context=agent_app.context,
            config=agent_app.config
        )
        
        # 执行简单生成任务
        result = await llm.generate_str(
            message="用50字总结MCP-Agent的核心功能",
            request_params=RequestParams(
                model="llama3:8b",
                temperature=0.7,
                max_tokens=100
            )
        )
        
        print(f"Ollama模型输出: {result}")

if __name__ == "__main__":
    asyncio.run(run_ollama_workflow())

运行这段代码将得到类似以下输出：

Ollama模型输出: MCP-Agent是基于模型上下文协议的智能代理框架，支持工作流编排、多Agent协作与动态任务规划，可集成Ollama等本地模型实现去中心化AI应用。

Orchestrator工作流实战

Orchestrator工作流是MCP-Agent的核心功能，它能够将复杂任务自动拆解为子任务，并调度不同Agent协同完成。以下是使用Ollama模型运行Orchestrator工作流的完整实现。

1. 工作流定义与Agent配置

# examples/workflows/workflow_orchestrator_worker/main.py (修改为Ollama版本)
from mcp_agent.workflows.orchestrator.orchestrator import Orchestrator
from mcp_agent.workflows.llm.augmented_llm_ollama import OllamaAugmentedLLM

# 创建专业化Agent
finder_agent = Agent(
    name="finder",
    instruction="从文件系统或网络获取指定内容",
    server_names=["fetch", "filesystem"]
)

analyzer_agent = Agent(
    name="analyzer",
    instruction="分析文本内容并提取关键信息",
    server_names=["fetch"]
)

writer_agent = Agent(
    name="writer",
    instruction="将分析结果整理为结构化报告",
    server_names=["filesystem"]
)

# 定义复杂任务
task = """分析指定目录下所有Markdown文件，提取每个文件的核心观点，
生成一份包含文件摘要、关键论点和相互关系的分析报告，
并保存为"content_analysis.md"。"""

2. 三种工作流规划策略

Orchestrator支持三种规划策略，适用于不同场景需求：

2.1 全量规划（Full Planning）

提前生成完整执行计划，适合目标明确、步骤固定的任务：

# 全量规划示例
orchestrator = Orchestrator(
    llm_factory=OllamaAugmentedLLM,
    available_agents=[finder_agent, analyzer_agent, writer_agent],
    plan_type="full",  # 生成完整执行计划
    max_planning_steps=15,
    name="full_planner"
)

2.2 迭代规划（Iterative Planning）

逐步规划执行，根据中间结果动态调整下一步，适合探索性任务：

# 迭代规划示例
orchestrator = Orchestrator(
    llm_factory=OllamaAugmentedLLM,
    available_agents=[finder_agent, analyzer_agent, writer_agent],
    plan_type="iterative",  # 逐步规划执行
    max_iterations=20,
    name="iterative_planner"
)

2.3 混合规划（Hybrid Planning）

关键步骤预先规划，细节步骤动态生成，平衡效率与灵活性：

# 混合规划示例
orchestrator = Orchestrator(
    llm_factory=OllamaAugmentedLLM,
    available_agents=[finder_agent, analyzer_agent, writer_agent],
    plan_type="hybrid",  # 混合规划策略
    critical_steps=["内容获取", "结果整合"],  # 预先规划的关键步骤
    name="hybrid_planner"
)

3. 执行工作流与监控

# 执行Orchestrator工作流
async def run_orchestrator():
    # 定义复杂任务
    task = """分析项目中的所有README文件，提取各模块功能描述，
    识别模块间依赖关系，生成一份Markdown格式的项目架构报告，
    并保存到"project_architecture.md"。"""
    
    # 执行工作流
    result = await orchestrator.generate_str(
        message=task,
        request_params=RequestParams(
            model="mistral:7b-instruct",
            temperature=0.4,
            max_tokens=4000
        )
    )
    
    # 获取执行摘要
    summary = await orchestrator.get_execution_summary()
    print(f"执行摘要: {summary}")
    
    return result

# 运行并监控
asyncio.run(run_orchestrator())

执行过程中，Orchestrator会生成类似以下的执行计划：

执行计划:
1. 获取项目结构信息 (finder_agent)
2. 识别所有README文件路径 (finder_agent)
3. 并行分析各README内容:
   - 提取模块功能描述 (analyzer_agent)
   - 识别模块依赖关系 (analyzer_agent)
4. 整合分析结果 (orchestrator)
5. 生成架构报告 (writer_agent)
6. 保存报告到文件系统 (writer_agent)

2. 工作流可视化

Orchestrator工作流的执行过程可以通过内置的可视化工具进行监控：

# 工作流执行监控
node = await orchestrator.get_token_node()
if node:
    display_token_usage(node, context)

这将生成类似以下的层次化执行报告：

└── assignment_grader [orchestrator]
    ├─ Total: 8,742 tokens
    ├─ Input: 5,218
    └─ Output: 3,524
        ├── planner [llm]
        │   ├─ Total: 2,145 tokens
        │   ├─ Input: 1,320
        │   └─ Output: 825
        ├── finder_agent [agent]
        │   ├─ Total: 1,842 tokens
        │   ├─ Input: 976
        │   └─ Output: 866
        ├── analyzer_agent [agent]
        │   ├─ Total: 3,258 tokens
        │   ├─ Input: 1,985
        │   └─ Output: 1,273
        └── writer_agent [agent]
            ├─ Total: 1,497 tokens
            ├─ Input: 937
            └─ Output: 560

图2：Orchestrator工作流的并行任务执行过程 官方文档

性能优化与最佳实践

1. Ollama模型选择策略

不同的Ollama模型适用于不同类型的任务：

模型	参数量	适用场景	性能特点
llama3:8b	8B	通用工作流规划	平衡速度与能力
mistral:7b-instruct	7B	指令跟随任务	响应速度快
llama3:70b	70B	复杂任务规划	能力强但资源消耗大
codellama:7b	7B	代码相关任务	代码理解能力强

2. 工作流优化技巧

• 合理设置规划步数：max_planning_steps建议设为预期步骤的1.5倍
• 控制并行度：根据CPU/内存资源调整max_parallel_tasks
• 优化模型参数：对规划阶段使用较高temperature(0.6-0.8)，执行阶段使用较低值(0.2-0.4)
• 启用上下文重用：设置context_reuse=True减少重复计算

3. 资源监控与调优

使用MCP-Agent内置的监控工具跟踪资源使用情况：

# 资源监控示例
from mcp_agent.utils.performance import ResourceMonitor

async def monitored_workflow():
    monitor = ResourceMonitor()
    monitor.start()
    
    # 执行工作流...
    result = await orchestrator.generate_str(...)
    
    # 获取资源使用报告
    report = monitor.stop()
    print(f"CPU使用率: {report.cpu_usage}%")
    print(f"内存使用: {report.memory_usage}MB")
    print(f"执行时间: {report.execution_time}s")
    
    return result

常见问题解决方案

1. Ollama连接失败

症状：ConnectionRefusedError: [Errno 111] Connection refused

解决方案：

• 检查Ollama服务状态：systemctl status ollama
• 确认配置文件中的地址正确：ollama_api_base: "http://localhost:11434/v1"
• 验证Ollama是否正常响应：curl http://localhost:11434/api/tags

2. 工作流执行超时

症状：TimeoutError: Task exceeded maximum allowed duration

解决方案：

• 增加超时设置：orchestrator = Orchestrator(timeout=300, ...)
• 减少单次任务复杂度
• 使用更小的模型或启用模型量化：ollama pull llama3:8b-q4_0

3. 内存占用过高

症状：工作流执行过程中程序崩溃或被系统终止

解决方案：

• 限制并行任务数量：max_parallel_tasks=2
• 使用量化模型减少内存占用
• 增加系统交换空间或升级硬件

总结与扩展

通过本文介绍的方法，你已经掌握了如何在MCP-Agent中使用Ollama本地模型运行Orchestrator工作流。这种架构的核心优势在于：

1. 本地部署：无需依赖云端服务，保护数据隐私
2. 资源高效：通过任务拆分和并行执行最大化硬件利用率
3. 灵活扩展：支持添加新的Agent类型和工作流模式
4. 成本可控：避免云端API的使用成本累积

进阶学习资源

• MCP-Agent官方文档
• Orchestrator工作流深度解析
• Ollama模型调优指南
• MCP-Agent SDK开发手册

后续扩展方向

1. 尝试Swarm工作流模式，实现更灵活的Agent协作
2. 集成Temporal实现工作流的持久化与恢复
3. 开发自定义Agent处理特定领域任务
4. 构建基于Web的工作流监控界面

现在，你已经具备了使用MCP-Agent和Ollama构建本地AI工作流系统的全部知识。立即动手实践，将复杂任务交给AI工作流自动处理吧！

【免费下载链接】mcp-agent Build effective agents using Model Context Protocol and simple workflow patterns 项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent