fast-agent — 这是什么 · 全景 · 阅读地图
30 秒导读:
fast-agent(PyPI 包名fast-agent-mcp)是一个 MCP 原生、CLI 优先的声明式 agent 框架。 你用一个装饰器声明「一个 agent = 指令 + 模型 + 几个 MCP server」,框架就把模型、工具、对话循环 全接好,让你把精力放在组合 Prompt 和 MCP Server 上,而不是写胶水代码。
本章只做概览:讲清它是什么、给谁用、最小怎么跑起来,画一张顶层结构图,给一张部件职责表, 最后给一份 6 章阅读地图。深入代码留给后面各章。
1. 这是什么(零基础也能懂)
一句话定义: fast-agent 让你用几行声明,把「一个 LLM」和「若干 MCP server(工具/资源/提示词的标准供应商)」
组合成一个能对话、能调工具、能编排成工作流的 agent。
先解释两个词:
- MCP(Model Context Protocol,模型上下文协议)——一个开放协议,让「工具、资源、提示词」以标准方式 提供给 LLM。你连上一个 MCP server,它暴露的工具就自动变成 agent 能调用的能力。
- 声明式(declarative)——你描述「我要一个什么样的 agent」(指令是什么、用哪个模型、连哪些 server), 而不是手写「先建 client、再建 LLM、再手动串工具循环」那一大坨过程代码。
解决什么问题 / 给谁用:
假设你想让一个模型「能读文件、能查网页、能调你自己写的 Python 函数」,还想随手换模型试效果、把几个 agent
串成流水线。裸写要处理:选 provider、建连接、把 MCP 工具翻译成模型认识的格式、驱 动「模型说要调工具→真去调→
把结果喂回去」的循环、管历史、管取消……fast-agent 把这些样板全包了。 它面向的是:
- 想用最少样板把「模型 + MCP server」拼成 agent / 工作流的人;
- 想把 agent 当编码助手、开发工具箱、评测或工作流平台用的人(README「Start Here」定位)。
它能做什么(功能一览):
| 能力 | 说明 |
|---|---|
| 声明式 agent | 一个 @fast.agent(...) 装饰器登记一个 agent |
| MCP 全特性 | 工具、资源、提示词,外加 Sampling、Elicitation、Roots、MCP-UI 等端到端特性 |
| 多 provider | 原生 Anthropic / OpenAI / Google,另有 Azure、Bedrock、Deepseek、OpenRouter、xAI、Groq、本地模型等 |
| 工作流模式 | chain / parallel / router / orchestrator / evaluator-optimizer / maker / agents-as-tools 共七种(详见第 6 章) |
| CLI 优先 | fast-agent go、--pack、quickstart、scaffold 等命令,配 prompt_toolkit 交互终端 |
| 结构化输出 | Structured Outputs、PDF、Vision;Passthrough / Playback 假 LLM 便于测试 |
用起来什么样(最小真实示例): 这是 README 里的 sizer.py——一个「给个物体、只回答它多大」的 agent。
注意样板极少:建 app、贴装饰器、fast.run() 里拿到 agent、interactive() 进交互。
import asyncio
from fast_agent import FastAgent
# 建应用(名字随便起,用于日志/展示)
fast = FastAgent("Agent Example")
# 声明一个 agent:只给它一句指令,模型/循环框架都帮你接好
@fast.agent(
instruction="Given an object, respond only with an estimate of its size."
)
async def main():
async with fast.run() as agent: # 进入运行时,拿到可调用的 agent
await agent.interactive() # 起一个交互式聊天
if __name__ == "__main__":
asyncio.run(main())
跑法:uv run sizer.py,换模型加 --model sonnet。也可以完全不写文件,直接用 CLI:
uvx fast-agent-mcp@latest -x # 装完直接进交互 shell
fast-agent go # 起一个交互会话
fast-agent go --url https://hf.co/mcp # 连一个远程 MCP server
fast-agent go --pack analyst --model haiku # 用打包好的「卡片包」+ 指定模型启动
fast-agent quickstart workflow # 生成「building effective agents」示例
fast-agent scaffold # 生成示例 agent 和配置文件
一句话直觉/类比: 把它当成 agent 界的「声明式配置 + 自动接线板」——你只声明「要什么」
(@fast.agent),它负责「怎么接」(选模型、连 server、跑工具循环)。模型是大脑、MCP server 是手脚、
fast-agent 是把两者接起来并让它们循环对话的主板。
2. 顶层全景(它大概怎么转)
怎么读这张图
从上到下是四层:你在最上面写声明,声明被「工厂」造成真正的 agent 对象(中间的类栈),
每次你 await agent("..."),请求落到底部的 ToolRunner 工具循环,循环再向两侧伸手——
左手是 LLM provider 抽象(真去调模型),右手是 MCP 集成(真去调工具)。
你写的代码 / CLI
┌───────────────────────────────────────────────────────────┐
│ ① 声明式前端 │
│ FastAgent 应用 + @fast.agent / @chain / @parallel … │
│ (core/fastagent.py · core/direct_decorators.py) │
└───────────────────────────┬───────────────────────────────┘
│ fast.run() 触发「工厂」造对象
▼
┌───────────────────────────────────────────────────────────┐
│ ② Agent 类栈(继承链,能力逐层叠加) │
│ LlmDecorator → LlmAgent → ToolAgent → McpAgent → Smart │
│ (agents/*.py) │
└───────────────────────────┬───────────────────────────────┘
│ await agent("…") → generate → 一次 turn
▼
┌───────────────────────────────────────────────────────────┐
│ ③ 工具循环引擎 ToolRunner │
│ 反复:调模型 → 若要用工具则执行 → 回填 → 再调,直到收尾 │
│ (agents/tool_runner.py) │
└──────────────┬─────────────────────────────┬──────────────┘
│ 调模型 │ 调工具
▼ ▼
┌──── ────────────────────┐ ┌──────────────────────────────┐
│ ④ LLM provider 抽象 │ │ ⑤ MCP 集成 │
│ 模型字符串 → 工厂 → │ │ MCPAggregator 把多个 server │
│ 统一 LLM 基类 → 各家 │ │ 的工具聚合成一张工具表 │
│ (llm/model_factory.py) │ │ (mcp/mcp_aggregator.py) │
└────────────────────────┘ └──────────────────────────────┘
部件一句话职责
| 部件 | 干什么 | 在哪个文件(符号) |
|---|---|---|
FastAgent 应用 | 声明式前端的入口,持有配置、登记表,run() 启动运行时 | core/fastagent.py:153 FastAgent |
| 装饰器 | @fast.agent 等把函数登记为 agent / 工作流(不立刻造对象) | core/direct_decorators.py:376 DecoratorMixin |
| 工厂 | run() 时把登记信息造成真正的 agent 实例,并接上模型 | core/direct_factory.py:687 _create_basic_agent |
| Agent 类栈 | 从纯 LLM 到智能编码 agent 的继承链,逐层叠加能力 | agents/llm_decorator.py:167,agents/tool_agent.py:50 等 |
ToolRunner | 驱动一次 turn 的工具循环:调模型 → 执行工具 → 回填 → 收尾 | agents/tool_runner.py:131 ToolRunner |
ModelFactory | 把「模型字符串」解析成 provider + 参数,产出对应 LLM 类 | llm/model_factory.py:746 ModelFactory |
MCPAggregator | 连接多个 MCP server,把它们的工具/资源/提示词聚合成一张表 | mcp/mcp_aggregator.py:302 MCPAggregator |
AgentHarness | 更高级的「宿主/会话」运行时(持久化、多会话) | core/harness.py:481 AgentHarness |
主线走一遍(一次 await agent("the moon") 的数据流)
不进代码,先看大盘。一次调用大致这样流动:
- 入口归一化。
await agent("the moon")命中LlmDecorator.__call__,它转给send→generate, 把字符串等各种输入统一成一份消息列表(agents/llm_decorator.py:508__call__→526send→540generate)。 - 进入一次 turn。
generate交给generate_impl;带工具能力的ToolAgent在这里新建一个ToolRunner并until_done()(agents/tool_agent.py:402处runner = ToolRunner(...))。 - 工具循环。
ToolRunner反复迭代(agents/tool_runner.py:188__anext__):调一次模型 → 若模型说 「要用工具」(stop_reason == TOOL_USE)就去执行、把结果回填 → 再调模型 → …… 直到模型给出终态回复。 - 两侧伸手。 「调模型」经 provider 抽象落到具体家(由模型字符串决定,见第 4 章);「执行工具」经
MCPAggregator落到某个真实 MCP server(见第 5 章)。 - 收尾返回。 循环结束(
agents/tool_runner.py:287until_done)吐出最后一条助手消息;send取其文本 作为字符串返回给你。
一句话:装饰器只登记、
run()才造对象、ToolRunner才是那个「反复调模型+调工具」的心脏。
3. 部件职责表(去哪个文件找什么)
下面把「顶层部件」摊平成一张更完整的导航表,方便你按职责直接跳章、跳文件。
| 主题 | 文件 | 关键符号 |
|---|---|---|
| 应用入口 / 生命周期 | src/fast_agent/core/fastagent.py | FastAgent |
fast.run() 上下文 | src/fast_agent/core/run_runtime.py | run(:267,yield ... wrapper) |
| 装饰器(agent / 工作流) | src/fast_agent/core/direct_decorators.py | DecoratorMixin.agent(:434)、chain(:848)、parallel(:889)、router(:789)、orchestrator(:684)、evaluator_optimizer(:931)、iterative_planner(:740) |
| 工厂(造实例、接模型) | src/fast_agent/core/direct_factory.py | get_model_factory(:598)、_create_basic_agent(:687) |
| 包导出面(懒加载) | src/fast_agent/__init__.py | _LAZY_EXPORTS(:5) |
| 纯 LLM / 友好接口层 | src/fast_agent/agents/llm_decorator.py | LlmDecorator(:167) |
| 加上记忆 / 参数 | src/fast_agent/agents/llm_agent.py | LlmAgent(:109) |
| 加上工具循环 | src/fast_agent/agents/tool_agent.py | ToolAgent(:50) |
| 加上 MCP / shell 能力 | src/fast_agent/agents/mcp_agent.py | McpAgent(:178,ABC) |
| 智能编码 agent | src/fast_agent/agents/smart_agent.py | SmartAgent(:1870) |
| 工具循环引擎 | src/fast_agent/agents/tool_runner.py | ToolRunner(:131)、__anext__(:188)、until_done(:287) |
| 模型字符串 → 类 | src/fast_agent/llm/model_factory.py | ModelFactory(:746)、parse_model_spec(:897)、create_factory(:1024) |
| provider 枚举 | src/fast_agent/llm/provider_types.py | Provider(:8) |
| 统一 LLM 基类 | src/fast_agent/llm/fastagent_llm.py | FastAgentLLM |
| MCP 工具聚合 | src/fast_agent/mcp/mcp_aggregator.py | MCPAggregator(:302)、call_tool(:2326)、load_servers(:640) |
| MCP 连接管理 | src/fast_agent/mcp/mcp_connection_manager.py | MCPConnectionManager |
| server 注册表 | src/fast_agent/mcp_server_registry.py | ServerRegistry |
| 高级宿主 / 会话 | src/fast_agent/core/harness.py、core/harness_app.py | AgentHarness(:481)、HarnessApp |
| CLI 命令表 | src/fast_agent/cli/main.py | go / quickstart / scaffold / check / serve 等映射 |
锚点提示:
pyproject.toml记name = "fast-agent-mcp"、version = "0.8.0",核心依赖是mcp==1.27.2、fastmcp==3.4.2、anthropic、openai、google-genai——「MCP 原生 + 多 provider」 从依赖表就能看出来。
4. 阅读地图(6 章顺序与选章建议)
本子库共 7 个文件(含本章)。推荐顺序是「前端 → 类栈 → 循环 → 两侧抽象 → 工作流」,由浅入深:
| 顺序 | 章节 | 讲什么 | 什么时候读 |
|---|---|---|---|
| 0 | index.md(本章) | 这是什么 · 全景 · 阅读地图 | 先读,建立大盘 |
| 1 | 01-declarative-frontend.md | 声明式前端:FastAgent、装饰器、工厂 | 想知道「一行装饰器怎么变成一个活 agent」 |
| 2 | 02-agent-class-stack.md | Agent 类栈:LlmDecorator→LlmAgent→ToolAgent→McpAgent→Smart | 想搞清各层能力边界、该继承哪一层 |
| 3 | 03-tool-loop-engine.md | 工具循环引擎:ToolRunner 如何驱动一次 turn | 想理解「调模型↔调工具」的核心循环 |
| 4 | 04-llm-provider-abstraction.md | LLM 抽象:模型字符串、统一基类、多 provider | 想知道 --model "gpt-5?reasoning=low" 怎么解析、怎么换家 |
| 5 | 05-mcp-integration.md | MCP 集成:聚合工具、连接管理、端到端 MCP 特性 | 想理解工具从哪来、Sampling/Elicitation 怎么接 |
| 6 | 06-workflow-patterns.md | 工作流模式:chain/parallel/router/orchestrator… | 想把多个 agent 组合成流水线 |
选章建议:
- 只想跑起来 / 写第一个 agent → 读本章 + 第 1 章即可。
- 想扩展框架、写自定义 agent 类 → 第 2、3 章(类栈 + 循环)是核心。
- 卡在「模型选不对 / 换 provider」 → 直接第 4 章。
- 卡在「工具没连上 / MCP 特性怎么用」 → 直接第 5 章。
- 要做多 agent 编排 → 第 6 章,回头需要底层时再翻第 3 章。
5. 边界与本章不覆盖的
- 本章只做概览,所有「怎么实现」的细节都在后续章节;这里给的行号是跳转锚点,不是完整走读。
- 具体每个装饰器的参数、每种工作流的语义、provider 的差异、MCP 各特性(Sampling / Elicitation / Roots / MCP-UI / OAuth)等,分别落在第 1、4、5、6 章。
AgentHarness/harness_app这套「更高级的宿主/会话/持久化」运行时,本子库以FastAgent主线为主讲, harness 仅在需要时点到(它是 CLI 交互 shell、多会话等场景的底座)。