Fast Agent

从这里开始

\[！提示\] 请看https://fast-agent.ai获取最新文档。

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

要启动具有shell支持的交互式会话，请安装 紫外线 然后跑

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 命令，并使用以下命令连接到MCP服务器 /connect.默认值 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-powered交互式终端提示（TUI风格的输入、补全和终端菜单）；响应可以通过富实时流式传输到终端，而不依赖于全屏诅咒UI或外部GUI覆盖。

简单的声明性语法使您可以专注于编写Prompts和MCP服务器 建立有效的代理人.

模型支持是全面的，通过TensorZero为Anthropic、OpenAI和谷歌提供商以及Azure、Ollama、Deepseek和其他数十家公司提供原生支持。结构化输出、PDF和Vision支持易于使用且经过良好测试。Passthrough和Playback LLM可以为您的应用程序快速开发和测试Python粘合代码。

最近的功能包括：

• 代理技能（SKILL.md）
• MCP-UI支持|
• OpenAI应用软件开发工具包（天桥）
• 外壳模式
• 高级MCP传输诊断学
• MCP精英

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

\[！重要\] 文档作为子模块包含在内。克隆时，使用 --recurse-submodules 获取一切： ``bash 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服务器交互变得轻松。你可以阅读更多关于这个项目背后的动机 这里

开始：

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

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 --model . 如果需要，这会将包安装到所选的快速代理环境中，然后 开始 go 通常。 --model 是没有明确说明的卡片的后备方案 模型设置；直接在AgentCard中声明的模型仍然获胜。

其他快速入门示例包括研究员代理（具有Evaluator Optimizer工作流）和数据分析代理（类似于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模型， ?context=1m 仅适用于更早的十四行诗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.yaml 在活动快速代理主页中，或在需要时传递显式配置路径。_

可以使用中定义的MCP服务器链接代理以构建工作流 fast-agent.yaml 文件：

@fast.agent(
    "url_fetcher",
    "Given a URL, provide a complete and comprehensive summary",
    servers=["fetch"], # Name of an MCP Server defined in fast-agent.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 ""

添加 --quiet 切换到禁用进度和消息显示，并仅返回最终响应，这对简单的自动化很有用。

制造者

MAKER（“具有K-voting Error Reduction功能的大规模分解代理过程”）包装一个工作代理并重复采样，直到响应在所有备选方案中达到K-vote边际（“先到后”投票）。这对于简单步骤的长链非常有用，否则罕见的错误会加剧。

• 参考： 零错误解决百万步LLM任务
• 来源：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代理SDK 代理作为工具 功能。

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

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

• 路线：根据用户提示选择合适的专业工具。
• 并行化：在独立的项目上展开，然后聚合。
• 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回退。

• 中每台服务器的最低设置 fast-agent.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概述.

客户端ping按服务器配置（默认：间隔30秒，错过3次ping）：

mcp:
  servers:
    myserver:
      ping_interval_seconds: 30 # optional;  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支持文本和图像
• 谷歌支持文本、图像、PDF和视频（例如。， video/mp4).

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

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

提示

MCP提示支持 apply_prompt(name,arguments)，它总是返回一条助理消息。如果来自MCP服务器的最后一条消息是“用户”消息，则将其发送到LLM进行处理。保留应用于代理上下文的提示，这意味着 use_history=False，代理可以作为微调的响应者。

提示也可以通过使用交互式界面进行交互式应用 /prompt 命令。

采样

采样LLM是按客户端/服务器对配置的。在fast-agent.yaml中指定模型名称，如下所示：

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

机密文件

\[！提示\] 放 fast-agent.secrets.yaml 一起 fast-agent.yaml 在你的活跃快速特工家里。选择一个不同的家 --env 或 FAST_AGENT_HOME.

交互式 shell

文档

文档站点作为子模块包含在 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 建立在 mcp-agent Sarmad Qadri的项目。

贡献

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