告别繁琐流程：5分钟上手MCP-Agent多智能体协作

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

还在为复杂任务的多步骤协调而烦恼？MCP-Agent（Model Context Protocol Agent，模型上下文协议智能体）通过简单工作流模式实现高效智能体协作，让你轻松应对多智能体任务编排。本文将带你从环境搭建到实战案例，掌握MCP-Agent的核心功能与使用方法。

环境准备与快速安装

MCP-Agent支持通过CLI工具快速初始化项目，适用于各类Python环境。官方推荐使用uv包管理器以获得最佳性能。

安装步骤

# 创建项目目录
mkdir mcp-basic-agent && cd mcp-basic-agent

# 初始化MCP-Agent项目
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"
uv sync

配置文件结构将自动生成，包含：

• mcp_agent.config.yaml - 智能体配置
• mcp_agent.secrets.yaml - 密钥管理
• main.py - 主程序入口

详细安装指南可参考官方文档。

核心概念：智能体与工作流

MCP-Agent基于两大核心组件构建：智能体（Agent） 和工作流（Workflow）。

智能体（Agent）

智能体是具备特定能力的独立单元，通过MCP服务器连接外部资源。典型定义如下：

from mcp_agent.agents.agent import Agent

finder_agent = Agent(
    name="finder",
    instruction="""你拥有文件系统访问和URL获取能力。
    识别用户请求的最匹配资源，调用适当工具并返回URI和内容。""",
    server_names=["fetch", "filesystem"],  # 关联的MCP服务器
)

每个智能体可配置专用指令集和权限控制，实现功能隔离与安全访问。

工作流（Workflow）

工作流定义任务执行逻辑，支持两种实现方式：

• 工具装饰器：适用于简单无状态函数
• Workflow类：适用于复杂有状态流程

基础工作流示例：

from mcp_agent.executor.workflow import Workflow, WorkflowResult

@app.workflow
class TextProcessingWorkflow(Workflow[str]):
    @app.workflow_run
    async def run(self, input_text: str) -> WorkflowResult[str]:
        processed = await self.process_text(input_text)
        return WorkflowResult(value=processed)
    
    async def process_text(self, text: str) -> str:
        return text.upper()

工作流支持类型安全的输入输出处理、自动重试机制和状态管理，详细说明见工作流文档。

实战案例：学生作业自动批改系统

下面通过"多智能体协作批改学生短篇故事"案例，展示Orchestrator（编排器）工作流的强大能力。该案例将协调5个专业智能体完成复杂评估任务。

场景需求

1. 从本地文件加载短篇故事
2. 并行执行三项评估：
   • 语法拼写检查（proofreader智能体）
   • 事实逻辑一致性检查（fact_checker智能体）
   • APA格式规范检查（style_enforcer智能体）
3. 生成综合评估报告
4. 保存报告到本地文件

智能体配置

# 定义专业智能体
proofreader = Agent(
    name="proofreader",
    instruction="""检查故事的语法、拼写和标点错误，
    识别影响清晰度的 awkward phrasing（拗口表达），
    提供详细修改建议。""",
    server_names=["fetch"]
)

fact_checker = Agent(
    name="fact_checker",
    instruction="""验证故事中的事实一致性，识别情节、
    角色行为或场景中的矛盾点，突出逻辑连贯性问题。""",
    server_names=["fetch"]
)

style_enforcer = Agent(
    name="style_enforcer",
    instruction="""根据APA格式指南评估故事风格，
    分析叙事流畅度、表达清晰度和语气一致性，
    提出增强故事性的改进建议。""",
    server_names=["fetch"]
)

编排器实现

orchestrator = Orchestrator(
    llm_factory=OpenAIAugmentedLLM,
    available_agents=[finder_agent, writer_agent, proofreader, fact_checker, style_enforcer],
    plan_type="full",  # 生成完整执行计划
    name="assignment_grader",
)

# 执行复杂任务
result = await orchestrator.generate_str(
    message="""加载short_story.md中的学生短篇故事，
    根据https://owl.purdue.edu的APA格式指南，
    生成包含语法、事实一致性和风格评估的报告，
    保存为graded_report.md""",
    request_params=RequestParams(model="gpt-4o")
)

编排器将自动生成执行计划，示例如下：

{
  "steps": [
    {
      "description": "加载短篇故事",
      "tasks": [{"description": "读取short_story.md内容", "agent": "finder"}]
    },
    {
      "description": "生成评估反馈",
      "tasks": [
        {"description": "语法拼写检查", "agent": "proofreader"},
        {"description": "事实一致性检查", "agent": "fact_checker"},
        {"description": "APA风格评估", "agent": "style_enforcer"}
      ]
    },
    {
      "description": "生成综合报告",
      "tasks": [{"description": "编译评估结果", "agent": "writer"}]
    }
  ]
}

执行流程与监控

执行过程中可通过令牌使用树监控资源消耗：

assignment_grader [orchestrator]
├─ Total: 12,450 tokens ($0.0623)
├─ Input: 8,200
└─ Output: 4,250
   ├── proofreader [agent]
   │   ├─ Total: 3,200 tokens ($0.0160)
   │   ├─ Input: 2,100
   │   └─ Output: 1,100
   ├── fact_checker [agent]
   │   ├─ Total: 2,850 tokens ($0.0143)
   │   ├─ Input: 1,900
   │   └─ Output: 950
   └── style_enforcer [agent]
       ├─ Total: 3,500 tokens ($0.0175)
       ├─ Input: 2,200
       └─ Output: 1,300

完整案例代码见workflow_orchestrator_worker。

工作流模式与应用场景

MCP-Agent提供多种预设工作流模式，满足不同业务需求：

主流工作流类型

模式	特点	适用场景
Orchestrator	动态规划多智能体协作	复杂评估、内容创作、研究分析
Parallel	并行任务执行	批量处理、多源数据聚合、并发测试
Router	请求分发与路由	意图识别、技能匹配、负载均衡
Swarm	群体智能协作	创意生成、问题解决、头脑风暴

典型应用场景

1. 开发项目管理

   • 代码重构：分析代码库→识别问题→实施修复→验证结果
   • 功能开发：需求分析→设计→编码→测试→文档

2. 市场研究

   • 竞品分析：数据收集→趋势识别→用户调研→报告生成
   • 营销活动：受众分析→内容创作→设计→效果测试

3. 运营自动化

   • 事件响应：告警分析→影响评估→解决方案→实施
   • 合规审计：数据收集→政策审查→差距分析→整改计划

高级功能与最佳实践

执行引擎选择

MCP-Agent支持两种执行引擎：

• asyncio：轻量级异步执行，适合简单工作流
• Temporal：分布式耐用执行，支持状态恢复和长时间运行任务

配置示例：

execution_engine: temporal
temporal:
  host: localhost
  port: 7233
  namespace: default
  task_queue: mcp-agent

性能优化建议

1. 智能体设计

   • 单一职责原则：每个智能体专注特定能力
   • 最小权限原则：仅授予必要的服务器访问权限

2. 工作流优化

   • 并行执行独立任务：减少总体执行时间
   • 增量结果缓存：避免重复计算

3. 资源监控

   • 启用令牌计数：跟踪API使用成本
   • 实施超时控制：防止长时间运行任务阻塞

详细最佳实践参见有效模式指南。

总结与后续学习

通过本文，你已掌握MCP-Agent的核心概念和使用方法，包括环境搭建、智能体定义、工作流编排和实战应用。MCP-Agent通过模型上下文协议和灵活工作流模式，简化了多智能体协作的复杂性，让你能够专注于业务逻辑实现。

进阶学习资源

• 工作流模式库：探索更多预设工作流
• MCP服务器开发：自定义资源访问服务
• 评估与测试：智能体性能优化

立即访问官方代码库，开始构建你的多智能体协作系统！

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