概述

[!TIP] 文档站点正在建设中，地址为：https://fast-agent.ai。欢迎反馈哪些内容有帮助，哪些没有。这里还有一个LLMs.txt文件：这里

fast-agent 使您能够在几分钟内创建并与复杂的代理和工作流进行交互。它是第一个完全支持端到端测试的MCP功能的框架，包括采样。支持Anthropic（Haiku、Sonnet、Opus）和OpenAI模型（gpt-4o/gpt-4.1系列，o1/o3系列）。

简单的声明式语法让您可以专注于编写提示和MCP服务器，以构建有效的代理。

fast-agent 是多模态的，通过提示、资源和MCP工具调用结果支持Anthropic和OpenAI端点的图像和PDF。包含的直通和回放LLM使您能够快速开发和测试应用程序的Python粘合代码。

[!IMPORTANT]

fast-agent 的文档仓库在这里：https://github.com/evalstate/fast-agent-docs。欢迎提交文档、经验报告或其他您认为对他人有帮助的内容的PR。所有帮助和反馈都非常欢迎。

代理应用程序开发

定义代理应用程序的提示和配置存储在简单的文件中，具有最少的样板代码，便于管理和版本控制。

在工作流执行之前、期间和之后与单个代理和组件进行聊天，以调整和诊断您的应用程序。代理可以请求人工输入以获取完成任务所需的额外上下文。

简单的模型选择使得测试模型 <-> MCP服务器交互变得轻松。您可以在此处阅读有关该项目背后动机的更多信息：这里

开始使用：

首先安装Python的uv包管理器。然后：

uv pip install fast-agent-mcp          # 安装fast-agent！
fast-agent go                          # 启动交互式会话
fast-agent go https://hf.co/mcp        # 使用远程MCP
fast-agent go --model=generic.qwen2.5  # 使用ollama qwen 2.5
fast-agent setup                       # 创建示例代理和配置文件
uv run agent.py                        # 运行您的第一个代理
uv run agent.py --model=o3-mini.low    # 指定模型
fast-agent quickstart workflow  # 创建“构建有效代理”示例

其他快速入门示例包括研究员代理（带有评估器-优化器工作流）和数据分析代理（类似于ChatGPT体验），展示了MCP Roots支持。

[!TIP] Windows用户 - 文件系统和Docker MCP服务器需要进行一些配置更改 - 必要的更改在配置文件中详细说明。

基本代理

定义一个代理非常简单：

@fast.agent(
  instruction="给定一个对象，仅响应其大小的估计值。"
)

然后我们可以向代理发送消息：

async with fast.run() as agent:
  moon_size = await agent("the moon")
  print(moon_size)

或者启动与代理的交互式聊天：

async with fast.run() as agent:
  await agent.interactive()

以下是完整的sizer.py代理应用程序，包含样板代码：

import asyncio
from mcp_agent.core.fastagent import FastAgent

# 创建应用程序
fast = FastAgent("代理示例")

@fast.agent(
  instruction="给定一个对象，仅响应其大小的估计值。"
)
async def main():
  async with fast.run() as agent:
    await agent.interactive()

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

然后可以使用uv run sizer.py运行代理。

使用--model开关指定模型 - 例如uv run sizer.py --model sonnet。

组合代理并使用MCP服务器

要生成示例，请使用fast-agent quickstart workflow。此示例可以使用uv run workflow/chaining.py运行。fast-agent首先在当前目录中查找配置文件，然后递归检查父目录。

代理可以链接起来构建工作流，使用在fastagent.config.yaml文件中定义的MCP服务器：

@fast.agent(
    "url_fetcher",
    "给定一个URL，提供完整且全面的摘要",
    servers=["fetch"], # fastagent.config.yaml中定义的MCP服务器名称
)
@fast.agent(
    "social_media",
    """
    为任何给定文本编写280个字符的社交媒体帖子。
    仅响应帖子，切勿使用标签。
    """,
)
@fast.chain(
    name="post_writer",
    sequence=["url_fetcher", "social_media"],
)
async def main():
    async with fast.run() as agent:
        # 使用链式工作流
        await agent.post_writer("http://llmindset.co.uk")

所有代理和工作流都响应.send("message")或.prompt()以开始聊天会话。

保存为social.py后，我们现在可以从命令行运行此工作流：

uv run workflow/chaining.py --agent post_writer --message "<url>"

添加--quiet开关以禁用进度和消息显示，仅返回最终响应 - 适用于简单的自动化。

工作流

链式

chain工作流提供了一种更声明式的方法来按顺序调用代理：

@fast.chain(
  "post_writer",
   sequence=["url_fetcher","social_media"]
)

# 我们可以直接提示它：
async with fast.run() as agent:
  await agent.post_writer()

这将启动一个交互式会话，为给定的URL生成一个简短的社交媒体帖子。如果提示_chain_，它将返回与链中最后一个代理的聊天。您可以通过输入@agent-name切换代理以提示。

链可以合并到其他工作流中，或包含其他工作流元素（包括其他链）。如果需要，可以设置instruction以精确描述其功能给其他工作流步骤。

人工输入

代理可以请求人工输入以协助完成任务或获取额外上下文：

@fast.agent(
    instruction="一个协助完成基本任务的AI代理。需要时请求人工输入。",
    human_input=True,
)

await agent("打印序列中的下一个数字")

在示例human_input.py中，代理将提示用户提供额外信息以完成任务。

并行

并行工作流将相同的消息同时发送到多个代理（fan-out），然后使用fan-in代理处理组合内容。

@fast.agent("translate_fr", "将文本翻译成法语")
@fast.agent("translate_de", "将文本翻译成德语")
@fast.agent("translate_es", "将文本翻译成西班牙语")

@fast.parallel(
  name="translate",
  fan_out=["translate_fr","translate_de","translate_es"]
)

@fast.chain(
  "post_writer",
   sequence=["url_fetcher","social_media","translate"]
)

如果不指定fan-in代理，parallel将返回组合的代理结果。

parallel对于从不同LLM中集思广益也很有用。

在其他工作流中使用parallel时，请指定instruction以描述其操作。

评估器-优化器

评估器-优化器结合了两个代理：一个生成内容（generator），另一个判断该内容并提供可操作的反馈（evaluator）。消息首先发送给生成器，然后这对代理循环运行，直到评估者对质量满意，或达到最大细化次数。返回生成器的最终结果。

如果生成器的use_history关闭，则在请求改进时返回上一次迭代 - 否则使用对话上下文。

@fast.evaluator_optimizer(
  name="researcher",
  generator="web_searcher",
  evaluator="quality_assurance",
  min_rating="EXCELLENT",
  max_refinements=3
)

async with fast.run() as agent:
  await agent.researcher.send("生成一份关于如何制作完美浓缩咖啡的报告")

在工作流中使用时，它返回最后一个generator消息作为结果。

请参阅evaluator.py工作流示例，或fast-agent quickstart researcher以获得更完整的示例。

路由器

路由器使用LLM评估消息，并将其路由到最合适的代理。路由提示根据代理指令和可用服务器自动生成。

@fast.router(
  name="route",
  agents=["agent1","agent2","agent3"]
)

请查看router.py工作流示例。

协调器

给定一个复杂任务，协调器使用LLM生成一个计划，将任务分配给可用的代理。计划和聚合提示由协调器生成，它受益于使用更强大的模型。计划可以在一开始构建一次（plantype="full"）或迭代构建（plantype="iterative"）。

@fast.orchestrator(
  name="orchestrate",
  agents=["task1","task2","task3"]
)

请参阅orchestrator.py或agent_build.py工作流示例。

代理功能

调用代理

所有定义都允许省略名称和指令参数以简化：

@fast.agent("您是一个有帮助的代理")          # 使用默认名称创建代理。
@fast.agent("greeter","愉快地响应！")    # 创建名为“greeter”的代理

moon_size = await agent("the moon")             # 使用消息调用默认（第一个定义的代理）

result = await agent.greeter("早上好！")   # 使用点表示法按名称向代理发送消息
result = await agent.greeter.send("你好！")     # 您可以显式调用'send'

await agent.greeter()                           # 如果未指定消息，将打开聊天会话
await agent.greeter.prompt()                    # 可以使其更显式
await agent.greeter.prompt(default_prompt="OK") # 并支持设置默认提示

agent["greeter"].send("晚上好！")          # 如果喜欢，支持字典访问

定义代理

基本代理

@fast.agent(
  name="agent",                          # 代理名称
  instruction="您是一个有帮助的代理", # 代理的基本指令
  servers=["filesystem"],                # 代理的MCP服务器列表
  model="o3-mini.high",                  # 指定代理的模型
  use_history=True,                      # 代理维护聊天历史记录
  request_params=RequestParams(temperature= 0.7), # LLM的额外参数（或RequestParams()）
  human_input=True,                      # 代理可以请求人工输入
)

链式

@fast.chain(
  name="chain",                          # 链名称
  sequence=["agent1", "agent2", ...],    # 执行顺序中的代理列表
  instruction="instruction",             # 描述链的指令，供其他工作流使用
  cumulative=False,                      # 是否在链中累积消息
  continue_with_final=True,              # 提示后与链末尾的代理打开聊天
)

并行

@fast.parallel(
  name="parallel",                       # 并行工作流名称
  fan_out=["agent1", "agent2"],          # 并行运行的代理列表
  fan_in="aggregator",                   # 组合结果的代理名称（可选）
  instruction="instruction",             # 描述并行的指令，供其他工作流使用
  include_request=True,                  # 在fan-in消息中包含原始请求
)

评估器-优化器

@fast.evaluator_optimizer(
  name="researcher",                     # 工作流名称
  generator="web_searcher",              # 内容生成器代理名称
  evaluator="quality_assurance",         # 评估器代理名称
  min_rating="GOOD",                     # 最低可接受质量（EXCELLENT, GOOD, FAIR, POOR）
  max_refinements=3,                     # 最大细化次数
)

路由器

@fast.router(
  name="route",                          # 路由器名称
  agents=["agent1", "agent2", "agent3"], # 路由器可以委托的代理名称列表
  model="o3-mini.high",                  # 指定路由模型
  use_history=False,                     # 路由器维护对话历史记录
  human_input=False,                     # 路由器是否可以请求人工输入
)

协调器

@fast.orchestrator(
  name="orchestrator",                   # 协调器名称
  instruction="instruction",             # 协调器的基本指令
  agents=["agent1", "agent2"],           # 此协调器可以使用的代理名称列表
  model="o3-mini.high",                  # 指定协调器计划模型
  use_history=False,                     # 协调器不维护聊天历史记录（无效）。
  human_input=False,                     # 协调器是否可以请求人工输入
  plan_type="full",                      # 计划方法：“full”或“iterative”
  plan_iterations=5,                     # 完整计划尝试的最大次数，或迭代次数
)

多模态支持

使用内置的prompt-server或直接使用MCP类型向提示添加资源。提供了便利类来简化操作，例如：

  summary: str =  await agent.with_resource(
      "请总结此PDF",
      "mcp_server",
      "resource://fast-agent/sample.pdf",
  )

MCP工具结果转换

LLM API对通过其聊天完成API返回为工具调用/函数结果的内容类型有限制：

• OpenAI支持文本
• Anthropic支持文本和图像

对于MCP工具结果，ImageResources和EmbeddedResources被转换为用户消息并添加到对话中。

提示

MCP提示支持apply_prompt(name,arguments)，它始终返回一个助手消息。如果MCP服务器的最后一条消息是“用户”消息，则将其发送给LLM进行处理。应用于代理上下文的提示会被保留 - 这意味着在use_history=False的情况下，代理可以充当精细调整的响应者。

提示也可以通过交互式界面中的/prompt命令交互式应用。

采样

采样LLM按客户端/服务器对配置。在fastagent.config.yaml中指定模型名称如下：

mcp:
  servers:
    sampling_resource:
      command: "uv"
      args: ["run", "sampling_resource_server.py"]
      sampling:
        model: "haiku"

秘密文件

[!TIP] fast-agent将递归查找fastagent.secrets.yaml文件，因此您只需在代理定义的根文件夹中管理此文件。

交互式Shell

项目说明

fast-agent基于Sarmad Qadri的mcp-agent项目构建。

贡献

欢迎贡献和PR - 随时提出问题讨论。完整的贡献指南和路线图即将发布。请联系我们！