使用简单、可组合的模式，通过模型上下文协议（MCP）构建高效的智能体。

示例 | 构建高效智能体 | MCP

概述

mcp-agent 是一个简单、可组合的框架，用于使用模型上下文协议（MCP）构建高效的智能体。

[!Note]
mcp-agent 的愿景是：构建智能体只需要 MCP，并且对于交付高质量的智能体而言，简单的模式比复杂的架构更健壮。

mcp-agent 为你提供以下功能：

1. 完整的 MCP 支持：它完全实现了 MCP，并处理了管理 MCP 服务器连接生命周期的繁琐工作，让你无需操心。
2. 高效的智能体模式：它以可组合的方式实现了 Anthropic 的构建高效智能体中描述的每一种模式，允许你将它们链接在一起。
3. 持久化智能体：它适用于简单的智能体，并可扩展到基于 Temporal 构建的复杂工作流，让你可以暂停、恢复和恢复，而无需对智能体进行任何 API 更改。

总而言之，这是构建健壮的智能体应用程序最简单、最便捷的方式。

我们欢迎各种形式的贡献、反馈以及你帮助改进这个项目。

最小示例

import asyncio

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world")

async def main():
    async with app.run():
        agent = Agent(
            name="finder",
            instruction="Use filesystem and fetch to answer questions.",
            server_names=["filesystem", "fetch"],
        )
        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            answer = await llm.generate_str("Summarize README.md in two sentences.")
            print(answer)


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

# 将你的 LLM API 密钥添加到 `mcp_agent.secrets.yaml` 或在环境变量中设置。
# [入门指南](https://docs.mcp-agent.com/get-started/overview)详细介绍了配置和密钥管理。

一览

文档与 LLM 构建

mcp-agent 的完整文档可在 docs.mcp-agent.com 获取，包括完整的 SDK 指南、CLI 参考和高级模式。本 README 提供了高层次概述以帮助你入门。

• llms-full.txt：包含完整的文档。
• llms.txt：列出文档中关键页面的站点地图。
• 文档 MCP 服务器

目录

• 概述
• 最小示例
• 快速开始
• 为什么选择 mcp-agent
• 核心概念
• MCPApp
• 智能体与 AgentSpec
• 增强型 LLM
• 工作流与装饰器
• 配置与密钥
• MCP 集成
• 工作流模式
• CLI 参考
• 认证
• 高级功能
• 可观测性与控制
• 组合工作流
• 持久化执行
• 智能体服务器
• 信号与人工输入
• 应用配置
• 图标
• MCP 服务器管理
• 云端部署
• 示例
• 常见问题
• 社区与贡献

快速开始

[!TIP]
CLI 可通过 uvx mcp-agent 使用。
要快速上手，可以使用 uvx mcp-agent init 搭建项目，并使用 uvx mcp-agent deploy my-agent 进行部署。

运行以下命令，你可以在 2 分钟内启动并运行：

```bash
mkdir hello-mcp-agent && cd hello-mcp-agent
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"

将 OpenAI API 密钥添加到 mcp_agent.secrets.yaml 或设置 OPENAI_API_KEY 环境变量

uv run main.py
```

安装

我们推荐使用 uv 来管理你的 Python 项目（uv init）。

uv add "mcp-agent"

或者：

pip install mcp-agent

还可以为 LLM 提供商添加可选包（例如 uv add "mcp-agent[openai, anthropic, google, azure, bedrock]"）。

快速开始

[!TIP]
examples 目录包含多个示例应用程序供你入门。
要运行示例，克隆此仓库（或使用 uvx mcp-agent init --template basic --dir my-first-agent 生成一个）

```bash
cd examples/basic/mcp_basic_agent # 或任何其他示例

选项 A：密钥 YAML 文件

cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml

uv run main.py
```

这是一个基本的“查找器”智能体，它使用 fetch 和 filesystem 服务器来查找文件、阅读博客并撰写推文。示例链接：

import asyncio
import os

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world_agent")

async def example_usage():
    async with app.run() as mcp_agent_app:
        logger = mcp_agent_app.logger
        # 这个智能体可以读取文件系统或获取 URL
        finder_agent = Agent(
            name="finder",
            instruction="""You can read local files or fetch URLs.
                Return the requested information when asked.""",
            server_names=["fetch", "filesystem"], # 此智能体可以使用的 MCP 服务器
        )

        async with finder_agent:
            # 自动初始化 MCP 服务器并为其工具供 LLM 使用
            tools = await finder_agent.list_tools()
            logger.info(f"Tools available:", data=tools)

            # 将 OpenAI LLM 附加到智能体（默认为 GPT-4o）
            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

            # 这将使用 filesystem 服务器执行文件查找和读取
            result = await llm.generate_str(
                message="Show me what's in README.md verbatim"
            )
            logger.info(f"README.md contents: {result}")

            # 使用 fetch 服务器从 URL 获取内容
            result = await llm.generate_str(
                message="Print the first two paragraphs from https://www.anthropic.com/research/building-effective-agents"
            )
            logger.info(f"Blog intro: {result}")

            # 默认支持多轮交互
            result = await llm.generate_str("Summarize that in a 128-char tweet")
            logger.info(f"Tweet: {result}")

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

execution_engine: asyncio
logger:
  transports: [console] # 你可以使用 [file, console] 来同时输出到两者
  level: debug
  path: "logs/mcp-agent.jsonl" # 用于文件传输
  # 对于动态日志文件名：
  # path_settings:
  #   path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
  #   unique_id: "timestamp"  # 或 "session_id"
  #   timestamp_format: "%Y%m%d_%H%M%S"

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args:
        [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "<add_your_directories>",
        ]

openai:
  # 密钥（API 密钥等）存储在 mcp_agent.secrets.yaml 文件中，该文件可以被 git 忽略
  default_model: gpt-4o

智能体输出

为什么选择 mcp-agent？

市面上已经有太多的 AI 框架了。但 mcp-agent 是唯一一个专门为共享协议——MCP——构建的框架。mcp-agent 将 Anthropic 的“构建高效智能体”模式与一个开箱即用的 MCP 运行时相结合，让你可以专注于行为，而不是样板代码。团队选择它是因为：

• 可组合性 – 每个模式都以可重用的工作流形式提供，你可以混合搭配。
• MCP 原生 – 任何 MCP 服务器（文件系统、fetch、Slack、Jira、FastMCP 应用）都可以连接，无需自定义适配器。
• 生产就绪 – Temporal 支持的持久化、结构化日志记录、令牌统计和云端部署都是一等公民。
• Python 风格 – 少量装饰器和上下文管理器就能将所有东西连接起来。

文档：欢迎使用 mcp-agent • 高效模式概述。

核心组件

每个项目都围绕一个单一的 MCPApp 运行时展开，该运行时加载配置、注册智能体和 MCP 服务器，并暴露工具/工作流。核心组件指南详细介绍了这些构建模块。

MCPApp

初始化配置、日志记录、追踪和执行引擎，以便所有组件共享一个上下文。

from mcp_agent.app import MCPApp

app = MCPApp(name="finder_app")

async def main():
    async with app.run() as running_app:
        logger = running_app.logger
        logger.info("App ready", data={"servers": list(running_app.context.server_registry.registry)})

文档：MCPApp • 示例：examples/basic/mcp_basic_agent。

智能体与 AgentSpec

智能体将指令与它们可以调用的 MCP 服务器（以及可选函数）耦合在一起。AgentSpec 定义可以从磁盘加载，并通过工厂辅助函数转换为智能体或增强型 LLM。

```python
from pathlib import Path
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.factory import load_agent_specs_from_file

agent = Agent(
name="researcher",
instruction="Research topics using web and filesystem access",
server_names=["fetch", "filesystem"],
)

async with agent:
tools = await agent.list_tools()

async with app