使用简单、可组合的模式，借助模型上下文协议构建高效智能体。

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

概述

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

[!注] 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="使用文件系统和 fetch 来回答问题。",
            server_names=["filesystem", "fetch"],
        )
        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            answer = await llm.generate_str("用两句话概括 README.md。")
            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 参考以及高级模式。本自述文件提供了高层次的概览，帮助您快速上手。

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

目录

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

快速入门

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

您只需运行以下命令，即可在两分钟内开始使用：

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]"）。

快速入门

[!提示] 在 examples 目录中，有多个示例应用可供您快速上手。要运行示例，您可以克隆此仓库，或使用 uvx mcp-agent init --template basic --dir my-first-agent 生成一个新项目。

cd examples/basic/mcp_basic_agent # 或其他示例目录
# 方法 A：使用 secrets YAML 文件
# cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml 并编辑内容
uv run main.py

以下是一个基础的“查找”代理，它利用 fetch 和文件系统服务器来查找文件、阅读博客并发布推文。示例链接：

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="""你可以读取本地文件或抓取 URL。
                当被要求时，请返回所需的信息。""",
            server_names=["fetch", "filesystem"], # 该代理可使用的 MCP 服务器
        )

        async with finder_agent:
            # 自动初始化 MCP 服务器，并将它们的工具添加到 LLM 的使用列表
            tools = await finder_agent.list_tools()
            logger.info(f"可用工具:", data=tools)

            # 将 OpenAI 的 LLM 绑定到代理（默认为 GPT-4o）
            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

            # 这将通过文件系统服务器进行文件查找和读取
            result = await llm.generate_str(
                message="请逐字显示 README.md 中的内容"
            )
            logger.info(f"README.md 内容: {result}")

            # 使用 fetch 服务器从 URL 获取内容
            result = await llm.generate_str(
                message="请打印 https://www.anthropic.com/research/building-effective-agents 上前两段文字"
            )
            logger.info(f"博客简介: {result}")

            # 默认支持多轮交互
            result = await llm.generate_str("用 128 字的推文概括上述内容")
            logger.info(f"推文: {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",
          "<添加您的目录>",
        ]

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

代理输出

为什么选择 mcp-agent？

目前市面上已经有许多 AI 框架。然而，mcp-agent 是唯一一个专为共享协议——MCP——构建的框架。mcp-agent 将 Anthropic 的 Building Effective Agents 模式与开箱即用的 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("应用已就绪", data={"服务器": list(running_app.context.server_registry.registry)})

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

Agents & AgentSpec

代理将指令与其可能调用的 MCP 服务器（以及可选函数）绑定在一起。AgentSpec 定义可以从磁盘加载，并通过工厂辅助工具转换为代理或增强型大语言模型。

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="研究员",
    instruction="使用网络和文件系统访问功能研究主题",
    server_names=["fetch", "filesystem"],
)

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

async with app.run() as running_app:
    specs = load_agent_specs_from_file(
        str(Path("examples/basic/agent_factory/agents.yaml")),
        context=running_app.context,
    )

文档：Agents • 代理工厂辅助工具 • 示例：examples/basic/agent_factory。

增强型大语言模型

增强型大语言模型将提供商 SDK 与代理的工具、记忆和结构化输出助手封装在一起。将它附加到代理上，即可解锁 generate、generate_str 和 generate_structured 方法。

from pydantic import BaseModel
from mcp_agent.workflows.llm.augmented_llm import RequestParams
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

class Summary(BaseModel):
    title: str
    verdict: str

async with agent:
    llm = await agent.attach_llm(OpenAIAugmentedLLM)
    report = await llm.generate_str(
        message="根据 CHANGELOG.md 草拟一段三句话的发布说明",
        request_params=RequestParams(maxTokens=400, temperature=0.2),
    )
    structured = await llm.generate_structured(
        message="返回一个包含 `title` 和 `verdict` 的 JSON 对象，总结 README 文件。",
        response_model=Summary,
    )

文档：增强型大语言模型 • 示例：examples/basic/mcp_basic_agent以及 gallery.md 中列出的工作流项目。

工作流与装饰器

MCPApp 装饰器可以将协程转换为持久性的工作流和工具。相同的注解既适用于 asyncio 也适用于 Temporal 执行。

from datetime import timedelta
from mcp_agent.executor.workflow import Workflow, WorkflowResult

@app.workflow
class PublishArticle(Workflow[WorkflowResult[str]]):
    @app.workflow_task(schedule_to_close_timeout=timedelta(minutes=5))
    async def draft(self, topic: str) -> str:
        return f"- 关于 {topic} 的简介\n- 重点内容\n- 下一步"

    @app.workflow_run
    async def run(self, topic: str) -> WorkflowResult[str]:
        outline = await self.draft(topic)
        return WorkflowResult(value=outline)

文档：装饰器参考 • 示例：examples/workflows。

配置与密钥

设置可以从 mcp_agent.config.yaml、mcp_agent.secrets.yaml、环境变量以及可选的预加载字符串中加载。请勿将密钥存储在源代码控制中。

# mcp_agent.config.yaml
execution_engine: asyncio
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
openai:
  default_model: gpt-4o-mini

# mcp_agent.secrets.yaml（已忽略于 git）
openai:
  api_key: "${OPENAI_API_KEY}"

文档：配置参考 • 指定密钥。

MCP 集成

可以通过编程方式连接到现有的 MCP 服务器，或将多个服务器聚合为一个统一的接口。

from mcp_agent.mcp.gen_client import gen_client

async with app.run():
    async with gen_client("filesystem", app.server_registry, context=app.context) as client:
        resources = await client.list_resources()
        app.logger.info("文件系统资源", data={"URIs": [r.uri for r in resources.resources]})

文档：MCP 集成概述 • 示例：examples/mcp。

工作流模式

关键代理模式以 AugmentedLLM 的形式实现。可以使用工厂辅助函数来配置这些模式，或查看 gallery.md 中列出的可运行项目。

模式	辅助函数	简介	文档
并行（Map-Reduce）	create_parallel_llm(...)	扇出专家任务，并将结果扇入汇总。	并行
路由器	create_router_llm(...) / create_router_embedding(...)	将请求路由到最佳的代理、服务器或函数。	路由器
意图分类器	create_intent_classifier_llm(...) / create_intent_classifier_embedding(...)	在自动化之前，将用户输入归类到不同的意图中。	意图分类器
协调者-工作者	create_orchestrator(...)	生成计划并协调工作者代理。	规划者
深度研究	create_deep_orchestrator(...)	长期限的研究，包含知识提取和策略检查。	深度研究
评估者-优化者	create_evaluator_optimizer_llm(...)	不断迭代，直到评估者批准结果。	评估者-优化者
蜂群	create_swarm(...)	多代理交接，与 OpenAI Swarm 兼容。	蜂群

持久化执行

将 execution_engine 切换为 temporal，即可实现暂停/恢复、重试、人工干预以及持久化历史记录等功能，而无需更改工作流代码。可以在应用旁边运行一个工作进程来托管活动。

from mcp_agent.executor.temporal import create_temporal_worker_for_app

async with create_temporal_worker_for_app(app) as worker:
    await worker.run()

文档：持久化代理 • Temporal 后端 • 示例：examples/temporal。

代理服务器

将 MCPApp 暴露为标准的 MCP 服务器，以便 Claude Desktop、Cursor 或自定义客户端可以调用您的工具和工作流。

from mcp_agent.server import create_mcp_server_for_app

@app.tool
def grade_story(story: str) -> str:
    return "报告..."

if __name__ == "__main__":
    server = create_mcp_server_for_app(app)
    server.run_stdio()

文档：代理服务器 • 示例：examples/mcp_agent_server。

CLI 参考

uvx mcp-agent 可用于搭建项目、管理密钥、检查工作流以及部署到云端。

uvx mcp-agent init --template basic             # 搭建新项目
uvx mcp-agent deploy my-agent                   # 部署到 mcp-agent 云平台

文档：CLI 参考 • 入门指南。

身份验证

可以从密钥文件中加载 API 密钥，也可以使用内置的 OAuth 客户端获取并持久化 MCP 服务器的令牌。

# mcp_agent.config.yaml 摘录
oauth:
  providers:
    github:
      client_id: "${GITHUB_CLIENT_ID}"
      client_secret: "${GITHUB_CLIENT_SECRET}"
      scopes: ["repo", "user"]

文档：高级身份验证 • 服务器身份验证 • 示例：examples/basic/oauth_basic_agent。

高级功能

可观测性与控制

通过配置启用结构化日志记录和 OpenTelemetry，并以编程方式跟踪令牌使用情况。

# mcp_agent.config.yaml
logger:
  transports: [console]
  level: info
otel:
  enabled: true
  exporters:
    - console

TokenCounter 可以跟踪代理、工作流和 LLM 节点的令牌使用情况。您可以附加监听器来实时接收更新或触发警报。

# 在 `async with app.run() as running_app:` 中
# 当启用了追踪时，token_counter 会存在于运行应用的上下文中。
token_counter = running_app.context.token_counter

class TokenMonitor:
    async def on_token_update(self, node, usage):
        print(f"[{node.name}] 总计={usage.total_tokens}")

monitor = TokenMonitor()
watch_id = await token_counter.watch(
    callback=monitor.on_token_update,
    node_type="llm",
    threshold=1_000,
    include_subtree=True,
)

await token_counter.unwatch(watch_id)

文档：可观测性 • 示例：examples/tracing。

工作流编排

使用工厂辅助函数（路由器、并行管道、编排器等）混合搭配 AgentSpecs，构建更高级别的工作流。

from mcp_agent.workflows.factory import create_router_llm

# 如上所示，可以通过 load_agent_specs_from_file 加载规格。
async with app.run() as running_app:
    router = await create_router_llm(
        agents=specs,
        provider="openai",
        context=running_app.context,
    )

文档：工作流编排 • 示例：examples/basic/agent_factory。

信号与人工输入

暂停工作流以等待审批或额外数据。Temporal 会持久化存储状态，直到操作员恢复执行。

from mcp_agent.human_input.types import HumanInputRequest

response = await self.context.request_human_input(
    HumanInputRequest(
        prompt="批准草稿吗？",
        required=True,
        metadata={"workflow_id": self.context.workflow_id},
    )
)

可通过 mcp-agent cloud workflows resume … --payload '{"content": "approve"}' 恢复执行。文档：部署代理——人工输入 • 示例：examples/human_input/temporal。

应用配置

当需要动态配置（如测试环境、多租户主机）而无需使用 YAML 文件时，可以以编程方式构建 Settings 对象。

from mcp_agent.config import Settings, MCPSettings, MCPServerSettings

settings = Settings(
    execution_engine="asyncio",
    mcp=MCPSettings(
        servers={
            "fetch": MCPServerSettings(command="uvx", args=["mcp-server-fetch"]),
        }
    ),
)
app = MCPApp(name="configured_app", settings=settings)

文档：配置您的应用。

图标

为代理和工具添加图标，以便支持图像显示的 MCP 客户端（如 Claude Desktop、Cursor）能够渲染更丰富的用户界面。

from base64 import standard_b64encode
from pathlib import Path
from mcp_agent.icons import Icon

icon_data = standard_b64encode(Path("my-icon.png").read_bytes()).decode()
icon = Icon(src=f"data:image/png;base64,{icon_data}", mimeType="image/png", sizes=["64x64"])

app = MCPApp(name="my_app_with_icon", icons=[icon])

@app.tool(icons=[icon])
async def my_tool() -> str:
    return "带着风格的问候"

文档：MCPApp 图标 • 示例：examples/mcp_agent_server/asyncio。

MCP 服务器管理

使用 MCPAggregator 或 gen_client 来管理 MCP 服务器连接，并暴露组合后的工具集。

from mcp_agent.mcp.mcp_aggregator import MCPAggregator

async with MCPAggregator.create(server_names=["fetch", "filesystem"]) as aggregator:
    tools = await aggregator.list_tools()

文档：连接到 MCP 服务器 • 示例：examples/basic/mcp_server_aggregator。

云部署

部署到 mcp-agent 云平台，享受托管的 Temporal 执行、密钥管理和 HTTPS 的 MCP 端点服务。

uvx mcp-agent login
uvx mcp-agent deploy my-agent
uvx mcp-agent cloud apps list

文档：云概览 • 部署快速入门 • 示例：examples/cloud。

示例

浏览 gallery.md，查看按概念分组的可运行示例、演示视频和社区项目。每个条目都注明了对应的文档页面以及在本地运行所需的命令。

常见问题解答

使用 mcp-agent 的核心优势是什么？

mcp-agent 提供了一种简化的途径，用于利用 MCP（模型上下文协议）服务器公开的功能来构建 AI 代理。

MCP 层次较低，而该框架负责处理与服务器连接、LLM 交互、外部信号（如人工输入）的处理，以及通过持久化执行支持持久状态等底层机制。这使开发者能够专注于 AI 应用的核心业务逻辑。

核心优势：

• 🤝 互操作性：确保任何由任意数量 MCP 服务器暴露的工具都能无缝集成到您的代理中。
• ⛓️ 可组合性与可定制性：实现了定义明确的工作流，同时以可组合的方式支持复合工作流，并允许在模型提供商、日志记录、编排器等方面进行完全自定义。
• 💻 程序化控制流：让开发变得更简单，您只需编写代码，而无需考虑图、节点和边的概念。对于分支逻辑，直接使用 if 语句；对于循环，则使用 while 循环。
• 🖐️ 人工输入与信号：支持暂停工作流以等待外部信号，例如人工输入，这些信号会以工具调用的形式暴露给代理。

使用 mcp-agent 是否需要 MCP 客户端？

不需要。您可以随时随地使用 mcp-agent，因为它会为您自动创建 MCP 客户端。这使得您能够在 Claude Desktop 等 MCP 主机之外，直接利用 MCP 服务器。

以下是设置 mcp-agent 应用程序的几种方式：

MCP-Agent 服务器

您可以将 mcp-agent 应用程序本身作为 MCP 服务器公开（参见 示例），从而使 MCP 客户端能够通过 MCP 服务器的标准工具 API 与复杂的 AI 工作流进行交互。这实际上就是一个“服务器中的服务器”。

MCP 客户端或主机

您也可以直接将 mcp-agent 嵌入到 MCP 客户端中，以管理跨多个 MCP 服务器的编排工作。

独立运行

您还可以以独立方式使用 mcp-agent 应用程序（即它们不属于任何 MCP 客户端）。示例均为独立应用程序。

如何部署到云端？

登录后运行 uvx mcp-agent deploy <app-name>。CLI 会打包您的项目、配置密钥，并暴露一个由持久化 Temporal 运行时支持的 MCP 端点。请参阅 [云快速入门](https://docs.mcp-agent.com/get-started/ cloud)，获取分步截图和 CLI 输出。

API 参考文档在哪里？

所有类、装饰器和 CLI 命令都在 docs.mcp-agent.com 上进行了文档化。API 参考和 llms-full.txt 文件旨在方便 LLM 或其他工具轻松地理解整个 API 表面。

让我分享一个有趣的事实吧！

我曾考虑将这个项目命名为 silsila（سلسلہ），在乌尔都语中意为“事件链”。最终选择了更直白的 mcp-agent，不过项目中仍有一个彩蛋，向 silsila 致敬。

贡献

我们欢迎各种形式的贡献——修复 bug、新增示例、撰写文档或提出功能需求。请从 CONTRIBUTING.md 开始，发起讨论，或加入我们的 Discord 社区。

没有众多开源贡献者的不懈努力，mcp-agent 核心不可能实现。感谢大家！

mcp-agent 快速上手指南

mcp-agent 是一个基于 Model Context Protocol (MCP) 的简洁、可组合框架，旨在帮助开发者构建高效的 AI Agent。它完整实现了 MCP 协议，自动管理服务器连接生命周期，并支持从简单脚本到基于 Temporal 的生产级持久化工作流。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL 推荐)
• Python: 版本 3.10 或更高
• 包管理器: 推荐使用 uv (极速 Python 包管理工具)，也可使用 pip
• LLM API Key: 准备好 OpenAI、Anthropic 或其他支持的 LLM 供应商的 API Key
• Node.js (可选): 如果需要使用基于 npm 的 MCP 服务器（如文件系统服务），请确保已安装 Node.js

国内开发者提示：

• 安装 uv 时若遇网络问题，可使用国内镜像或二进制文件直接下载。
• 使用 pip 安装时，建议配置清华源或阿里源加速：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...

安装步骤

推荐使用 uv 来初始化和管理工作区，它能更快速地处理依赖。

1. 初始化项目

# 创建项目目录并进入
mkdir hello-mcp-agent && cd hello-mcp-agent

# 使用 uv 初始化项目
uv init

# 添加 mcp-agent 核心库及 OpenAI 支持 (可根据需要替换为 anthropic, google 等)
uv add "mcp-agent[openai]"

如果不使用 uv，也可以使用 pip 安装：

pip install "mcp-agent[openai]"

2. 配置密钥

在项目根目录下创建 mcp_agent.secrets.yaml 文件（该文件应加入 .gitignore），填入你的 LLM API Key：

openai:
  api_key: "sk-your-openai-api-key-here"

或者直接将密钥设置为环境变量：

export OPENAI_API_KEY="sk-your-openai-api-key-here"

基本使用

以下是一个最小化的示例，展示如何创建一个名为 "finder" 的 Agent。该 Agent 能够调用 filesystem (文件系统) 和 fetch (网络获取) 这两个 MCP 服务器来回答问题。

1. 创建配置文件 mcp_agent.config.yaml

定义 Agent 可以使用的 MCP 服务器。这里我们配置了官方提供的 fetch 和 filesystem 服务。

execution_engine: asyncio
logger:
  transports: [console]
  level: info

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args:
        [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "." 
        ]
        # 注意：将 "." 替换为你希望 Agent 访问的具体目录路径，例如 "/Users/yourname/documents"

openai:
  default_model: gpt-4o

2. 编写代码 main.py

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 = Agent(
            name="finder",
            instruction="Use filesystem and fetch to answer questions.",
            server_names=["filesystem", "fetch"],
        )
        
        async with agent:
            # 挂载 LLM (默认使用配置中的 gpt-4o)
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            
            # 执行任务：读取本地文件
            answer = await llm.generate_str("Summarize README.md in two sentences.")
            print(f"Summary: {answer}")

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

3. 运行 Agent

确保当前目录下有 README.md 文件（或修改代码中的文件名），然后运行：

uv run main.py

输出示例： Agent 将自动启动配置的 MCP 服务器，调用工具读取文件，并返回由 LLM 生成的总结内容。

下一步建议：

• 查看 examples 目录获取更多复杂模式（如 Map-Reduce、路由、评估器优化器等）。
• 访问 官方文档 了解如何部署到云端或使用 Temporal 实现持久化执行。