从这里开始

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

fast-agent 是一种灵活的与大语言模型交互的方式，非常适合作为编码助手、开发工具包、评估平台或工作流平台使用。

要启动一个支持 Shell 的交互式会话，请安装 uv 并运行：

uvx fast-agent-mcp@latest -x

要使用 Hugging Face 推理服务进行编码，或者使用你的 OpenAI Codex 计划：

# 使用 Hugging Face 推理服务编码
uvx fast-agent-mcp@latest --pack hf-dev

# 使用 Codex 编码（针对 OpenAI 优化的助手）
uvx fast-agent-mcp@latest --pack codex

通过输入 ! 进入 Shell，或者直接运行 Shell 命令，例如 ! cd web && npm run build。

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

# /connect 支持标准输入输出或可流式传输的 HTTP（带 OAuth）

# 启动一个 STDIO 服务器
/connect @modelcontextprotocol/server-everything

# 连接到一个可流式传输的 HTTP 服务器
/connect https://huggingface.co/mcp

建议安装 fast-agent，以便设置 Shell 别名和其他工具。

# 安装 fast-agent
uv tool install -U fast-agent-mcp

# 以 opus 模型、Shell 支持及子代理/智能模式运行 fast-agent
fast-agent --model opus -x --smart

你可以使用通用提供者来运行本地模型，或者自动生成适用于 llama.cpp 的正确配置：

fast-agent model llamacpp

任何 fast-agent 配置或程序都可以与任意 ACP 客户端配合使用，最简单的方式是使用 fast-agent-acp：

# 在 Toad 中运行 fast-agent
toad acp "fast-agent-acp -x --model sonnet"

fast-agent 能够让你在几分钟内创建并交互复杂的多模态代理和工作流。它是首个具备完整端到端测试的 MCP 功能支持框架，包括采样和诱导机制。

fast-agent 以命令行优先，同时提供一个可选的基于 prompt_toolkit 的交互式终端界面（TUI 风格的输入、补全和终端内菜单）；响应可以实时流式传输到终端，无需依赖全屏的 curses 界面或外部 GUI 叠加层。

简单的声明式语法使你可以专注于编写提示词和 MCP 服务器配置，从而 构建高效的代理。

模型支持非常全面，原生支持 Anthropic、OpenAI 和 Google 提供者，以及通过 TensorZero 支持 Azure、Ollama、Deepseek 等数十家厂商。结构化输出、PDF 和视觉功能的使用简单且经过充分测试。透传和回放 LLM 使你能够快速开发和测试应用程序中的 Python 胶水代码。

近期新增功能包括：

• 代理技能 (SKILL.md)
• MCP-UI 支持
• OpenAI Apps SDK（Skybridge）
• Shell 模式
• 高级 MCP 传输诊断
• MCP 诱导机制

fast-agent 是唯一一款能够检查可流式传输 HTTP 传输使用情况的工具，这一功能对于确保可靠、合规的部署至关重要。它支持 OAuth，并使用 KeyRing 存储机密信息。请使用 fast-agent auth 命令进行管理。

[!IMPORTANT]

文档以子模块形式包含在内。克隆时，请使用 --recurse-submodules 参数以获取所有内容：

git clone --recurse-submodules https://github.com/evalstate/fast-agent.git

或者，如果你已经克隆过仓库：

git submodule update --init --recursive

文档源也可在以下地址查看：https://github.com/evalstate/fast-agent-docs

代理应用开发

定义你的代理应用的提示词和配置存储在简单的文件中，几乎没有样板代码，便于管理和版本控制。

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

简单的模型选择使得测试模型与 MCP 服务器之间的交互变得轻松无压。你可以在此处了解更多关于该项目的背景信息 here。

开始使用：

首先安装 Python 的 uv 包管理器。然后执行以下命令：

uv pip install fast-agent-mcp          # 安装 fast-agent！
fast-agent go                          # 启动交互式会话
fast-agent go --url https://hf.co/mcp  # 使用远程 MCP
fast-agent go --model=generic.qwen2.5  # 使用 Ollama Qwen 2.5 模型
fast-agent go --pack analyst --model haiku  # 安装/复用卡片包并启动
fast-agent scaffold                    # 创建示例智能体及配置文件
uv run agent.py                        # 运行你的第一个智能体
uv run agent.py --model='o3-mini?reasoning=low'    # 指定模型
uv run agent.py --transport http --port 8001  # 以 MCP 服务器模式暴露（自动进入服务器模式）
fast-agent quickstart workflow  # 创建“构建高效智能体”的示例

--server 参数仍可用于向后兼容，但已被弃用；现在 --transport 会自动将智能体切换到服务器模式。

对于预打包的入门智能体，可使用 fast-agent go --pack <name> --model <model>。这会在必要时将卡片包安装到选定的 fast-agent 环境中，然后正常启动 go。--model 是一个备用选项，用于那些未明确指定模型的卡片；如果 AgentCard 中直接声明了模型，则优先使用该模型。

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

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

基础智能体

定义一个智能体非常简单：

@fast.agent(
  instruction="给定一个物体，仅回答其大小的估计值。"
)

随后我们可以向智能体发送消息：

async with fast.run() as agent:
  moon_size = await agent("月球")
  print(moon_size)

或者与智能体进行交互式对话：

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

以下是完整的 sizer.py 智能体应用，包含样板代码：

import asyncio
from fast_agent 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。

模型字符串还支持查询覆盖。例如：

• 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 模型，?context=1m 仅适用于较早的 Sonnet 4 和 Sonnet 4.5 版本，这些版本仍需显式启用 1M 上下文窗口。而 Claude Sonnet 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",
    "给定一个 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 参数可禁用进度和消息显示，仅返回最终响应——这对于简单的自动化任务非常有用。

MAKER

MAKER（“大规模分解式代理流程，结合 K 投票误差减少”）封装了一个工作者智能体，并反复采样，直到某个响应在所有备选方案中领先 k 票为止（即“率先领先 k 票”的投票机制）。这对于由许多简单步骤组成的长链条非常有用，因为在这种情况下，罕见的错误可能会不断累积。

• 参考文献：零错误解决百万步 LLM 任务
• 致谢：Lucid Programmer（论文作者）

@fast.agent(
  name="classifier",
  instruction="仅回复：A、B 或 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("分类：...")

代理作为工具

“代理作为工具”工作流会将一个复杂任务拆分为多个子任务，并根据主代理的指令调用其他代理作为工具来完成这些子任务。

这种模式受到 OpenAI Agents SDK 中“代理作为工具”功能的启发 Agents as tools。

通过将子代理暴露为工具，你可以在指令中直接实现路由、并行化以及协调者-工作者式的分解，并且还可以将它们组合起来。每一轮支持多次工具调用，并且这些调用会并行执行。

常见的使用模式可能包括：

• 路由：根据用户提示选择合适的专家工具。
• 并行化：针对独立的项目或任务进行分流处理，随后再汇总结果。
• 协调者-工作者模式：将任务分解为具有明确范围的子任务（通常通过一个简单的 JSON 计划），然后协调这些子任务的执行。

@fast.agent(
    name="NY-项目经理",
    instruction="返回纽约时间及所在时区，并附上一行项目状态。",
    servers=["time"],
)
@fast.agent(
    name="伦敦-项目经理",
    instruction="返回伦敦时间及所在时区，并附上一行新闻简报。",
    servers=["time"],
)
@fast.agent(
    name="PMO-协调器",
    instruction=(
        "获取报告。每个项目/新闻始终使用一次工具调用。"  # 并行化
        "职责：纽约项目：[OpenAI、Fast-Agent、Anthropic]。伦敦新闻：[经济、艺术、文化]。"  # 路由
        "汇总结果，并添加一行 PMO 总结。"
    ),
    default=True,
    agents=["NY-项目经理", "伦敦-项目经理"],  # 协调者-工作者
)
async def main() -> None:
    async with fast.run() as agent:
        await agent("获取 PMO 报告。项目：全部。新闻：艺术、文化")

扩展示例及所有参数的完整代码可在仓库中的 examples/workflows/agents_as_tools_extended.py 文件中找到。

MCP OAuth (v2.1)

对于 SSE 和 HTTP MCP 服务器，默认情况下只需极少配置即可启用 OAuth。系统会使用本地回调服务器来捕获授权码；如果端口不可用，则会回退到粘贴式 URL 的方式。

• 每个服务器在 fastagent.config.yaml 中所需的最少设置如下：

mcp:
  servers:
    myserver:
      transport: http # 或 sse
      url: http://localhost:8001/mcp # 或 /sse 用于 SSE 服务器
      auth:
        oauth: true # 默认值为 true
        redirect_port: 3030 # 默认值为 3030
        redirect_path: /callback # 默认值为 /callback
        # scope: "user"       # 可选；若未指定，则使用服务器默认值

• 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 概述。

客户端侧的 ping 配置是按服务器进行的（默认间隔 30 秒，允许连续错过 3 次）：

mcp:
  servers:
    myserver:
      ping_interval_seconds: 30 # 可选；设置为 0 或更小则禁用
      max_missed_pings: 3 # 可选；连续超时次数达到此值后标记为失败

工作流

链式工作流

“链式”工作流提供了一种更为声明式的顺序调用代理的方式：

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

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

这将启动一个交互式会话，为给定的 URL 生成一条简短的社交媒体帖子。如果对“链式”工作流发送提示，它会回到与链中最后一个代理的对话界面。你可以通过输入 @代理名 来切换当前代理。

链式工作流可以嵌入到其他工作流中，也可以包含其他工作流元素（包括其他链式工作流）。如有需要，你可以为其设置 instruction，以精确描述其功能供其他工作流步骤使用。

人工输入

代理可以请求人工输入，以协助完成任务或获取更多上下文信息：

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

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

在示例文件 human_input.py 中，代理会提示用户输入更多信息，以便完成任务。

并行工作流

并行工作流会同时向多个代理发送相同的消息（即“扇出”），然后由“扇入”代理处理汇总后的结果。

@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"]
)

如果你没有指定“扇入”代理，“并行”工作流会原样返回所有代理的结果。

“并行”工作流也非常适合整合来自不同 LLM 的想法。

在其他工作流中使用“并行”工作流时，请务必为其设置 instruction，以说明其运作方式。

评估-优化工作流

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

如果生成器关闭了 use_history 功能，那么在请求改进时只会返回上一次的迭代结果；否则会利用对话上下文。

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

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

当它被用于某个工作流时，最终返回的是生成器最后一次生成的消息。

有关更完整的示例，请参阅 evaluator.py 工作流示例，或参考 fast-agent 快速入门 研究员。

路由器

路由器使用大语言模型（LLM）来评估消息，并将其路由到最合适的代理。路由提示会根据代理的指令和可用的服务端自动生成功能。

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

示例请参考 router.py 工作流。

协调器

面对复杂的任务，协调器会利用大语言模型生成一个计划，将任务分配给可用的代理。规划和聚合提示由协调器生成，而协调器受益于使用更强大的模型。计划可以在开始时一次性构建（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")          # 创建一个带有默认名称的代理。
@fast.agent("greeter","Respond cheerfully!")    # 创建一个名为“greeter”的代理。

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

result = await agent.greeter("Good morning!")   # 通过点符号按名称向代理发送消息。
result = await agent.greeter.send("Hello!")     # 也可以显式调用“send”方法。

await agent.greeter()                           # 如果未指定消息，则会开启一次对话。
await agent.greeter.prompt()                    # 可以使对话更加明确。
await agent.greeter.prompt(default_prompt="OK") # 并支持设置默认提示。

agent["greeter"].send("Good Evening!")          # 如果偏好，也可以使用字典访问方式。

定义代理

基础代理

@fast.agent(
  name="agent",                          // 代理名称
  instruction="You are a helpful Agent", // 代理的基础指令
  servers=["filesystem"],                // 代理使用的 MCP 服务列表
  model="o3-mini?reasoning=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,                  // 在合并消息中包含原始请求
)

评估-优化器

@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?reasoning=high",        // 指定路由模型
  use_history=False,                     // 路由器不维护对话历史
  human_input=False,                     // 路由器是否可以请求人工输入
)

协调器

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

MAKER

@fast.maker(
  name="maker",                           // 工作流名称
  worker="worker_agent",                  // 工作者代理名称
  k=3,                                    // 投票优势（领先k票者胜出）
  max_samples=50,                         // 最大样本数量
  match_strategy="exact",                 // 精确匹配|归一化匹配|结构化匹配
  red_flag_max_length=256,                // 标记异常长的输出
  instruction="instruction",              // 可选的指令覆盖
)

代理作为工具

@fast.agent(
  name="orchestrator",                    // 协调器代理名称
  instruction="instruction",              // 协调器的指令（路由/分解/聚合）
  agents=["agent1", "agent2"],            // 作为工具暴露：agent__agent1、agent__agent2
  max_parallel=128,                       // 限制并行子工具调用的数量（OpenAI 的上限为 128）
  child_timeout_sec=600,                  // 每个子调用的超时时间（秒）
  max_display_instances=20,               // 在显示前N个实例后折叠进度显示
)

函数工具

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

按代理的工具（@agent.tool） — 将工具的作用范围限定于特定代理：

@fast.agent(name="writer", instruction="你负责写作。")
async def writer(): ...

@writer.tool
def translate(text: str, language: str) -> str:
    """将文本翻译成指定语言。"""
    return f"[{language}] {text}"

@writer.tool(name="summarize", description="生成一行摘要")
def summarize(text: str) -> str:
    return f"摘要：{text[:80]}..."

全局工具（@fast.tool） — 对所有未声明自己工具的代理都可用：

@fast.tool
def get_weather(city: str) -> str:
    """返回某个城市的当前天气状况。"""
    return f"{city} 天气晴朗"

@fast.agent(name="assistant", instruction="你非常乐于助人。")
# assistant 可以使用全局工具 get_weather

带有 @agent.tool 或 function_tools= 的代理仅能看到自己的工具——不会注入全局工具。如果希望明确排除全局工具，可以使用 function_tools=[]。

多模态支持

可以通过内置的 prompt-server 或直接使用 MCP 类型向提示中添加资源。为此提供了便捷的类，例如：

  summary: str =  await agent.with_resource(
      "请总结这份 PDF 文件",
      "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"

秘密文件

[!TIP] fast-agent 会递归查找 fastagent.secrets.yaml 文件，因此你只需在代理定义的根目录下管理此文件即可。

交互式 Shell

文档

文档站点以子模块形式包含在 docs/ 目录中。要在本地处理文档：

# 安装文档依赖项（仅首次）
uv run scripts/docs.py install

# 从源代码生成参考文档
uv run scripts/docs.py generate

# 启动开发服务器（http://127.0.0.1:8000）
uv run scripts/docs.py serve

# 或者一步完成生成与服务
uv run scripts/docs.py all

生成器会直接从源代码中提取配置字段说明、模型别名和 API 参考，以确保文档始终保持同步。

项目说明

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

贡献

欢迎贡献和提交 PR；如有任何问题，也欢迎随时提出讨论。完整的贡献指南和路线图即将发布。请随时联系我们！

fast-agent 快速上手指南

fast-agent 是一个灵活的 LLM 交互框架，适用于构建编码智能体（Coding Agent）、开发工具包、评估平台及工作流自动化。它支持 CLI 优先操作，具备完整的 MCP（Model Context Protocol）功能，包括采样、询问（Elicitations）及多模态支持。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows（Windows 用户需注意文件系统配置，详见官方文档）。
• Python 环境：推荐安装 uv 包管理器（由 Astral 开发，速度极快）。
  • 国内加速提示：如果 uv 安装或下载慢，可配置国内镜像源。
• 网络环境：访问 Hugging Face、OpenAI 或 Anthropic 等服务需要稳定的网络连接。

安装 uv (推荐)

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装步骤

您可以选择直接运行最新版本的 fast-agent，或者将其安装为本地工具以使用 shell 别名和高级功能。

方式一：直接运行（无需安装）

使用 uvx 直接启动交互式会话：

# 启动带有 Shell 支持的交互式会话
uvx fast-agent-mcp@latest -x

方式二：本地安装（推荐）

安装后可使用 fast-agent 命令，并配置 Shell 别名：

# 安装 fast-agent 工具
uv tool install -U fast-agent-mcp

# 验证安装并启动（示例：使用 Opus 模型，开启 Shell 支持和智能模式）
fast-agent --model opus -x --smart

安装特定功能包

针对特定场景，可以加载预配置的功能包：

# 使用 Hugging Face 推理提供商进行编码
uvx fast-agent-mcp@latest --pack hf-dev

# 使用针对 OpenAI 优化的 Codex 智能体
uvx fast-agent-mcp@latest --pack codex

基本使用

1. 启动交互式会话

安装完成后，运行以下命令进入交互式终端（支持 Shell 命令执行）：

fast-agent go

常用参数示例：

# 连接远程 MCP 服务器
fast-agent go --url https://hf.co/mcp

# 指定本地 Ollama 模型 (例如 qwen2.5)
fast-agent go --model=generic.qwen2.5

# 加载预设包并指定模型
fast-agent go --pack analyst --model haiku

在会话中：

• 输入 ! 进入 Shell 模式，或直接运行 ! cd web && npm run build 执行命令。
• 使用 /skills 管理技能。
• 使用 /connect 连接 MCP 服务器（支持 stdio 或 HTTP）。

# 连接标准 MCP 服务器示例
/connect @modelcontextprotocol/server-everything
/connect https://huggingface.co/mcp

2. 创建第一个 Agent (代码示例)

创建一个名为 sizer.py 的文件，定义一个简单的智能体：

import asyncio
from fast_agent import FastAgent

# 创建应用实例
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())

运行 Agent：

# 运行脚本，指定模型为 sonnet
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"

3. 构建工作流 ( chaining )

fast-agent 支持将多个 Agent 串联成工作流。首先初始化示例项目：

# 创建示例工作流文件
fast-agent quickstart workflow

编辑生成的 workflow/chaining.py，你可以看到如何组合 Agent：

@fast.agent(
    "url_fetcher",
    "Given a URL, provide a complete and comprehensive summary",
    servers=["fetch"], # 引用 fastagent.config.yaml 中定义的 MCP 服务器
)
@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:
        # 执行链式工作流
        await agent.post_writer("http://llmindset.co.uk")

运行工作流：

# 运行工作流，传入消息参数
uv run workflow/chaining.py --agent post_writer --message "<url>"

# 静默模式：仅输出最终结果，不显示进度
uv run workflow/chaining.py --agent post_writer --message "<url>" --quiet

4. 高级特性速览

• MAKER 模式：用于高可靠性任务，通过多次采样和投票机制减少错误。
• Agents as Tools：将子 Agent 作为工具暴露给主 Agent，实现任务分解、路由和并行处理。
• MCP 诊断：内置 Streamable HTTP 传输诊断工具，确保部署合规性。
• 本地模型：自动配置 llama.cpp 或使用通用提供商连接本地模型。

  fast-agent model llamacpp
  

提示：更多详细文档请访问 https://fast-agent.ai 或查看 GitHub 仓库中的 fast-agent-docs 子模块。