Fast Agent

从这里开始

[!提示] 请参阅 https://fast-agent.ai 获取最新文档。

fast-agent 是一种与 LLM 交互的灵活方式，非常适合用作编码代理、开发工具包、评估或工作流程平台。

要启动具有 shell 支持的交互式会话，请安装 uv 并运行

uvx fast-agent-mcp@latest -x

要开始使用 Hugging Face 推理提供商进行编码或使用您的 OpenAI Codex 计划：

# Code with Hugging Face Inference Providers
uvx fast-agent-mcp@latest --pack hf-dev

# Code with Codex (agents optimized for OpenAI)
uvx fast-agent-mcp@latest --pack codex

使用 ! 输入 shell，或运行 shell 命令，例如 ! cd web && npm run build。

使用 /skills 命令管理技能，并使用 /connect 连接到 MCP 服务器。 默认 fast-agent 注册表包含可让您设置 LSP、代理和工具挂钩、压缩策略、自动化等的技能。

# /connect supports stdio or streamable http (with OAuth)

# Start a STDIO server
/connect @modelcontextprotocol/server-everything

# Connect to a Streamable HTTP Server
/connect https://huggingface.co/mcp

建议安装 fast-agent 来设置 shell 别名和其他工具。

# Install fast-agent
uv tool install -U fast-agent-mcp

# Run fast-agent with opus, shell support and subagent/smart mode
fast-agent --model opus -x --smart

将本地模型与通用提供程序结合使用，或自动为 llama.cpp 创建正确的配置：

fast-agent model llamacpp

任何 fast-agent 设置或程序都可以与任何 ACP 客户端一起使用 - 最简单的方法是使用 fast-agent-acp：

# Run fast-agent inside Toad
toad acp "fast-agent-acp -x --model sonnet"

fast-agent 使您能够在几分钟内创建复杂的多模式代理和工作流程并与之交互。 它是第一个具有完整、端到端测试的 MCP 功能支持（包括采样和启发）的框架。

fast-agent 是 CLI 优先，具有可选的由 Prompt_toolkit 支持的交互式终端提示（TUI 风格的输入、补全和终端内菜单）； 响应可以通过 rich 实时流式传输到终端，而无需依赖全屏 Curses UI 或外部 GUI 覆盖。

简单的声明性语法可让您专注于将提示和 MCP 服务器编写为 build effective agents。

模型支持非常全面，通过 TensorZero 对 Anthropic、OpenAI 和 Google 提供商以及 Azure、Ollama、Deepseek 和其他数十个提供商提供本机支持。 结构化输出、PDF 和 Vision 支持易于使用且经过充分测试。 直通和回放 LLM 可以为您的应用程序快速开发和测试 Python 粘合代码。

最近的功能包括：

• 特工技能（SKILL.md）
• MCP-UI 支持 |
• OpenAI Apps SDK（Skybridge）
• 外壳模式
• 先进的 MCP 传输诊断
• MCP 引出

fast-agent 是唯一允许您检查可流 HTTP 传输使用情况的工具 - 这是确保可靠、合规部署的关键功能。 OAuth 支持密钥环存储密钥。 使用fast-agent auth命令进行管理。

[!重要]

文档作为子模块包含在内。 克隆时，使用 --recurse-submodules 获取所有内容：

> git clone --recurse-submodules https://github.com/evalstate/fast-agent.git
> ```>
 > 或者，如果您已经克隆：
 >
 >
```bash
> git submodule update --init --recursive
> ```>
 > 文档源也可从以下位置获取：https://github.com/evalstate/fast-agent-docs

 ### 代理应用程序开发

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

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

简单的模型选择使测试模型 <-> MCP 服务器交互变得轻松。 您可以阅读有关该项目背后动机的更多信息 [here](https://llmindset.co.uk/resources/fast-agent/)

 ![2025-03-23-fast-agent](https://github.com/user-attachments/assets/8f6dbb69-43e3-4633-8e12-5572e9614728)

 ## 开始：

 首先安装 Python 的 [uv package manager](https://docs.astral.sh/uv/)。 然后：
```bash
uv pip install fast-agent-mcp          # install fast-agent!
fast-agent go                          # start an interactive session
fast-agent go --url https://hf.co/mcp  # with a remote MCP
fast-agent go --model=generic.qwen2.5  # use ollama qwen 2.5
fast-agent go --pack analyst --model haiku  # install/reuse a card pack and launch it
fast-agent scaffold                    # create an example agent and config files
uv run agent.py                        # run your first agent
uv run agent.py --model='o3-mini?reasoning=low'    # specify a model
uv run agent.py --transport http --port 8001  # expose as MCP server (server mode implied)
fast-agent quickstart workflow  # create "building effective agents" examples

--server 仍然可用于向后兼容，但已弃用； --transport 现在自动将代理切换到服务器模式。

对于打包的入门代理，请使用 fast-agent go --pack <name> --model <model>。 如果需要，这会将包安装到选定的快速代理环境中，然后 正常启动 go。 --model 是没有明确说明的卡牌的后备方案 模型设定； 直接在 AgentCard 中声明的模型仍然获胜。

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

[!提示] Windows 用户 - 文件系统和 Docker MCP 服务器需要进行一些配置更改 - 配置文件中详细介绍了必要的更改。

基本代理

定义代理非常简单：

@fast.agent(
  instruction="Given an object, respond only with an estimate of its size."
)

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

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 fast_agent import FastAgent

# Create the application
fast = FastAgent("Agent Example")

@fast.agent(
  instruction="Given an object, respond only with an estimate of its size."
)
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。

模型字符串还接受查询覆盖。 例如：

• uv run sizer.py --model "gpt-5?reasoning=low"
• uv run sizer.py --model "claude-sonnet-4-6?web_search=on"
• uv run sizer.py --model "claude-sonnet-4-5?context=1m"

对于 Anthropic 模型，仅早期 Sonnet 4 / Sonnet 4.5 需要 ?context=1m 仍然需要显式 1M 上下文选择加入的模型。 克劳德十四行诗 4.6 和 Claude Opus 4.6 默认情况下已经使用了长上下文窗口，因此 ?context=1m 被接受是为了向后兼容，但在那里是不必要的。

组合代理并使用 MCP 服务器

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

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

@fast.agent(
    "url_fetcher",
    "Given a URL, provide a complete and comprehensive summary",
    servers=["fetch"], # Name of an MCP Server defined in fastagent.config.yaml
)
@fast.agent(
    "social_media",
    """
    Write a 280 character social media post for any given text.
    Respond only with the post, never use hashtags.
    """,
)
@fast.chain(
    name="post_writer",
    sequence=["url_fetcher", "social_media"],
)
async def main():
    async with fast.run() as agent:
        # using chain workflow
        await agent.post_writer("http://llmindset.co.uk")

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

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

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

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

创客

MAKER（“具有 K 投票错误减少功能的大规模分解代理流程”）包装一个工作代理并对其进行重复采样，直到响应达到所有替代方案的 k 投票余量（“先到先得 k ”投票）。 这对于长链简单步骤很有用，否则极少会出现错误。

• 参考：Solving a Million-Step LLM Task with Zero Errors
• 图片来源：Lucid Programmer（公关作者）

@fast.agent(
  name="classifier",
  instruction="Reply with only: A, B, or C.",
)
@fast.maker(
  name="reliable_classifier",
  worker="classifier",
  k=3,
  max_samples=25,
  match_strategy="normalized",
  red_flag_max_length=16,
)
async def main():
  async with fast.run() as agent:
    await agent.reliable_classifier.send("Classify: ...")

代理作为工具

代理作为工具工作流程接受复杂的任务，将其分解为子任务，并根据主代理指令将其他代理调用为工具。

此模式的灵感来自 OpenAI Agents SDK Agents as tools 功能。

通过将子代理公开为工具，您可以直接在指令中实现路由、并行化和协调器工作人员 decomposition（并将它们组合起来）。 支持每回合多个工具调用并并行执行。

常见的使用模式可以组合：

• 路由：根据用户提示选择正确的专业工具。
• 并行化：在独立的项目/项目上展开，然后聚合。
• Orchestrator-workers：将任务分解为范围内的子任务（通常通过简单的 JSON 计划），然后协调执行。

@fast.agent(
    name="NY-Project-Manager",
    instruction="Return NY time + timezone, plus a one-line project status.",
    servers=["time"],
)
@fast.agent(
    name="London-Project-Manager",
    instruction="Return London time + timezone, plus a one-line news update.",
    servers=["time"],
)
@fast.agent(
    name="PMO-orchestrator",
    instruction=(
        "Get reports. Always use one tool call per project/news. "  # parallelization
        "Responsibilities: NY projects: [OpenAI, Fast-Agent, Anthropic]. London news: [Economics, Art, Culture]. "  # routing
        "Aggregate results and add a one-line PMO summary."
    ),
    default=True,
    agents=["NY-Project-Manager", "London-Project-Manager"],  # orchestrator-workers
)
async def main() -> None:
    async with fast.run() as agent:
        await agent("Get PMO report. Projects: all. News: Art, Culture")

扩展示例和所有参数示例在存储库中可用，如下所示 examples/workflows/agents_as_tools_extended.py。

MCP OAuth (v2.1)

对于 SSE 和 HTTP MCP 服务器，默认情况下以最少的配置启用 OAuth。 本地回调服务器用于捕获授权代码，如果端口不可用，则使用粘贴 URL 回退。

• fastagent.config.yaml 中的最小每服务器设置：

mcp:
  servers:
    myserver:
      transport: http # or sse
      url: http://localhost:8001/mcp # or /sse for SSE servers
      auth:
        oauth: true # default: true
        redirect_port: 3030 # default: 3030
        redirect_path: /callback # default: /callback
        # scope: "user"       # optional; if omitted, server defaults are used

• OAuth 客户端使用 PKCE 和内存中令牌存储（不将令牌写入磁盘）。
• 令牌持久性：默认情况下，令牌通过 keyring 安全地存储在您的操作系统钥匙串中。 如果钥匙串不可用（例如无头容器），则会话将使用内存存储。
• 要强制每个服务器仅在内存中，请设置：

mcp:
  servers:
    myserver:
      transport: http
      url: http://localhost:8001/mcp
      auth:
        oauth: true
        persist: memory

• 要禁用特定服务器的 OAuth，请为该服务器设置 auth.oauth: false。

MCP Ping（可选）

MCP ping 实用程序可由对等方（客户端或服务器）启用。 请参阅Ping overview。

客户端 ping 是按服务器配置的（默认：30 秒间隔，3 次丢失 ping）：

mcp:
  servers:
    myserver:
      ping_interval_seconds: 30 # optional; <=0 disables
      max_missed_pings: 3 # optional; consecutive timeouts before marking failed

工作流程

链

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

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

# we can them prompt it directly:
async with fast.run() as agent:
  await agent.post_writer()

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

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

人工输入

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

@fast.agent(
    instruction="An AI agent that assists with basic tasks. Request Human Input when needed.",
    human_input=True,
)

await agent("print the next number in the sequence")

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

并行

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

@fast.agent("translate_fr", "Translate the text to French")
@fast.agent("translate_de", "Translate the text to German")
@fast.agent("translate_es", "Translate the text to Spanish")

@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 对于整合来自不同法学硕士的想法也很有用。

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

评估器-优化器

评估器-优化器结合了 2 个代理：一个用于生成内容（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("produce a report on how to make the perfect espresso")

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

请参阅 evaluator.py 工作流程示例，或 fast-agent quickstart researcher 了解更完整的示例。

路由器

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

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

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

协调器

给定一个复杂的任务，Orchestrator 使用 LLM 生成一个计划，将任务分配给可用的代理。 规划和聚合提示由 Orchestrator 生成，它受益于使用功能更强大的模型。 计划可以在开始时构建一次 (plan_type="full") 或迭代构建 (plan_type="iterative")。

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

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

代理功能

呼叫代理

为了简洁起见，所有定义都允许省略名称和指令参数：

@fast.agent("You are a helpful agent")          # Create an agent with a default name.
@fast.agent("greeter","Respond cheerfully!")    # Create an agent with the name "greeter"

moon_size = await agent("the moon")             # Call the default (first defined agent) with a message

result = await agent.greeter("Good morning!")   # Send a message to an agent by name using dot notation
result = await agent.greeter.send("Hello!")     # You can call 'send' explicitly

await agent.greeter()                           # If no message is specified, a chat session will open
await agent.greeter.prompt()                    # that can be made more explicit
await agent.greeter.prompt(default_prompt="OK") # and supports setting a default prompt

agent["greeter"].send("Good Evening!")          # Dictionary access is supported if preferred

定义代理

基础代理

@fast.agent(
  name="agent",                          # name of the agent
  instruction="You are a helpful Agent", # base instruction for the agent
  servers=["filesystem"],                # list of MCP Servers for the agent
  model="o3-mini?reasoning=high",        # specify a model for the agent
  use_history=True,                      # agent maintains chat history
  request_params=RequestParams(temperature= 0.7), # additional parameters for the LLM (or RequestParams())
  human_input=True,                      # agent can request human input
)

＃＃＃＃ 链

@fast.chain(
  name="chain",                          # name of the chain
  sequence=["agent1", "agent2", ...],    # list of agents in execution order
  instruction="instruction",             # instruction to describe the chain for other workflows
  cumulative=False,                      # whether to accumulate messages through the chain
  continue_with_final=True,              # open chat with agent at end of chain after prompting
)

＃＃＃＃ 平行线

@fast.parallel(
  name="parallel",                       # name of the parallel workflow
  fan_out=["agent1", "agent2"],          # list of agents to run in parallel
  fan_in="aggregator",                   # name of agent that combines results (optional)
  instruction="instruction",             # instruction to describe the parallel for other workflows
  include_request=True,                  # include original request in fan-in message
)

评估器-优化器

@fast.evaluator_optimizer(
  name="researcher",                     # name of the workflow
  generator="web_searcher",              # name of the content generator agent
  evaluator="quality_assurance",         # name of the evaluator agent
  min_rating="GOOD",                     # minimum acceptable quality (EXCELLENT, GOOD, FAIR, POOR)
  max_refinements=3,                     # maximum number of refinement iterations
)

路由器

@fast.router(
  name="route",                          # name of the router
  agents=["agent1", "agent2", "agent3"], # list of agent names router can delegate to
  model="o3-mini?reasoning=high",        # specify routing model
  use_history=False,                     # router maintains conversation history
  human_input=False,                     # whether router can request human input
)

协调器

@fast.orchestrator(
  name="orchestrator",                   # name of the orchestrator
  instruction="instruction",             # base instruction for the orchestrator
  agents=["agent1", "agent2"],           # list of agent names this orchestrator can use
  model="o3-mini?reasoning=high",        # specify orchestrator planning model
  use_history=False,                     # orchestrator doesn't maintain chat history (no effect).
  human_input=False,                     # whether orchestrator can request human input
  plan_type="full",                      # planning approach: "full" or "iterative"
  plan_iterations=5,                     # maximum number of full plan attempts, or iterations
)

创客

@fast.maker(
  name="maker",                           # name of the workflow
  worker="worker_agent",                  # worker agent name
  k=3,                                    # voting margin (first-to-ahead-by-k)
  max_samples=50,                         # maximum number of samples
  match_strategy="exact",                 # exact|normalized|structured
  red_flag_max_length=256,                # flag unusually long outputs
  instruction="instruction",              # optional instruction override
)

代理作为工具

@fast.agent(
  name="orchestrator",                    # orchestrator agent name
  instruction="instruction",              # orchestrator instruction (routing/decomposition/aggregation)
  agents=["agent1", "agent2"],            # exposed as tools: agent__agent1, agent__agent2
  max_parallel=128,                       # cap parallel child tool calls (OpenAI limit is 128)
  child_timeout_sec=600,                  # per-child timeout (seconds)
  max_display_instances=20,               # collapse progress display after top-N instances
)

功能工具

直接在代码中将 Python 函数注册为工具 — 无需 MCP 服务器或外部文件。 支持同步和异步功能。 默认情况下，函数名称和文档字符串用作工具名称和描述，或者您可以使用 name= 和 description= 覆盖它们。

每代理工具 (@agent.tool) — 将工具范围限定为特定代理：

@fast.agent(name="writer", instruction="You write things.")
async def writer(): ...

@writer.tool
def translate(text: str, language: str) -> str:
    """Translate text to the given language."""
    return f"[{language}] {text}"

@writer.tool(name="summarize", description="Produce a one-line summary")
def summarize(text: str) -> str:
    return f"Summary: {text[:80]}..."

全局工具 (@fast.tool) — 可供所有未声明自己工具的代理使用：

@fast.tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"Sunny in {city}"

@fast.agent(name="assistant", instruction="You are helpful.")
# assistant gets get_weather (global @fast.tool)

具有 @agent.tool 或 function_tools= 的代理只能看到自己的工具 - 不会注入全局变量。 使用 function_tools=[] 无需工具即可显式选择退出全局变量。

多式联运支持

直接使用内置 prompt-server 或 MCP 类型将资源添加到提示。 可以使用便利类来简单地执行此操作，例如：

  summary: str =  await agent.with_resource(
      "Summarise this PDF please",
      "mcp_server",
      "resource://fast-agent/sample.pdf",
  )

MCP 工具结果转换

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

• OpenAI 支持文本
• Anthropic 支持文本和图像
• Google 支持文本、图像、PDF 和视频（例如 video/mp4）。

注意：内嵌视频数据限制为 20MB。 对于较大的文件，请使用文件 API。 直接支持 YouTube URL。

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

提示

apply_prompt(name,arguments) 支持 MCP 提示，它始终返回一条助理消息。 如果来自 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"

秘密文件

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

交互式外壳

文档

该文档站点作为子模块包含在 docs/ 中。 要在本地使用文档：

# Install docs dependencies (first time only)
uv run scripts/docs.py install

# Generate reference docs from source code
uv run scripts/docs.py generate

# Run the dev server (http://127.0.0.1:8000)
uv run scripts/docs.py serve

# Or generate and serve in one command
uv run scripts/docs.py all

生成器直接从源代码中提取配置字段描述、模型别名和 API 引用，以保持文档同步。

项目笔记

fast-agent 建立在 Sarmad Qadri 的 mcp-agent 项目之上。

贡献

欢迎贡献和 PR - 请随意提出问题进行讨论。 完整的贡献指南和路线图很快就会推出。 联系我们！