/ 目录 / 演练场 / fast-agent
← 全部服务器 ↗ GitHub
● 社区 evalstate ⚡ 即开即用

fast-agent

作者 evalstate · evalstate/fast-agent

用 @fast.agent() 装饰器在 Python 中编写 MCP 原生 agent——Skills、MCP、ACP、多模型、eval 和追踪全部内置。

fast-agent 是一个对 MCP 和 Skills 有一等支持的固执己见的 agent 框架。为函数加上装饰器，挂载服务器和 skills，选择模型，你就得到了一个带追踪、eval 和可恢复运行的可执行 agent。既可作为独立框架使用，也可作为 MCP 服务器，将你的 agent 暴露为工具供 Claude 调用。

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

fast-agent-mcp.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "fast-agent-mcp",
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "fast-agent-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fast-agent-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add fast-agent-mcp -- uvx fast-agent-mcp

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： fast-agent

用 30 行 Python 构建一个深度调研 agent

👤 需要可复现调研 agent 的开发者 ⏱ ~60 min intermediate

何时使用： 你已在对话中验证了「调研 X」的流程，现在想把它做成可调用的 agent。

前置条件
  • Python 3.11+ 和 uv — 如缺少请先安装 uv；fast-agent 依赖它
  • fast-agent 已安装 — uvx fast-agent-mcp init；进入项目目录
步骤
  1. 生成脚手架
    Use fast-agent. Generate a research agent skeleton with tavily search + fetch + summarize tools.✓ 已复制
    → 带 @fast.agent 装饰器的 agent.py
  2. 挂载 MCP
    Attach the tavily-mcp and filesystem MCP servers in fastagent.config.yaml.✓ 已复制
    → 配置已验证；服务器已连接
  3. 运行并迭代
    Run with: research 'state of small embedding models 2026'. Inspect the trace.✓ 已复制
    → 追踪显示搜索→抓取→摘要链；输出是一份有来源的简报
  4. 添加 eval
    Author a 5-prompt eval; run nightly. Fail if any source citation is missing.✓ 已复制
    → Eval 输出绿色/红色；已设置夜间定时任务

结果： 一个可复现的调研流程，可以交给队友使用。

注意事项
  • 装饰器魔法掩盖了 agent 实际的行为 — 始终查看追踪记录；在宣告 agent 工作正常之前，先理解每一次工具调用
搭配使用： tavily-mcp · filesystem

将你的 fast-agent 暴露为 MCP 服务器

👤 需要跨团队共享 agent 的开发者 ⏱ ~25 min intermediate

何时使用： 你用 fast-agent 构建了一个内部 agent，希望让其他人从 Claude 中调用它。

步骤
  1. 标记 agent 为对外暴露
    Add @fast.agent(expose=True) to the decorator; specify name and description for tool discovery.✓ 已复制
    → Agent 现在同时以 MCP 工具的形式暴露
  2. 作为 MCP 服务器运行
    Run: fast-agent serve --transport stdio.✓ 已复制
    → Stdio MCP 服务器已运行，你的 agent 已列为工具
  3. 添加到客户端
    Add the fast-agent stdio config to my Claude Desktop config.✓ 已复制
    → 工具在 Claude 中可见；调用它会触发你的 agent

结果： 你的自定义 agent 像其他任何 MCP 一样可在团队中复用。

注意事项
  • Agent 依赖只有作者才有的本地文件 — 将配置和资产移入 agent 包中；记录所有必需的环境变量

用 eval 运行器对比两个 prompt 版本

👤 正在为生产环境调优 prompt 的任何人 ⏱ ~45 min intermediate

何时使用： 你在两种 prompt 措辞之间犹豫，想用数据来做决定。

步骤
  1. 编写 eval
    Define an eval with 12 representative inputs and golden outputs.✓ 已复制
    → evals/<name>.yaml
  2. 运行两次
    Run eval against prompt v1, then v2. Compare pass rates + token usage.✓ 已复制
    → 带差值的对比表
  3. 选定并锁定
    Save the winning prompt to prompts/winning.md; tag the eval as the regression baseline.✓ 已复制
    → 基线已锁定；未来 PR 将与其对比

结果： 数据驱动的 prompt 选择 + 回归防护网。

注意事项
  • 12 个输入全是正常路径 — 添加对抗性用例——空输入、格式错误的输入、矛盾的事实

组合

与其他 MCP 搭配，撬动十倍杠杆

fast-agent-mcp + tavily-mcp + filesystem

构建附带网页搜索和文件系统 MCP 的调研 agent

Build a research agent that uses tavily for search, filesystem for note persistence.✓ 已复制
fast-agent-mcp + mcpjam-inspector

发布前用 MCPJam UI 检查你的 fast-agent 服务器

Run fast-agent as MCP server; connect via mcpjam-inspector to verify tool schemas.✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
agent.run messages, agent_name? 端到端驱动一个 agent Model + tool calls
agent.list — 发现已暴露的 agent 0
eval.run eval_name, prompt_version? 提交前/夜间回归检查 Model API per prompt
trace.get run_id 调试某次具体运行 0

成本与限制

运行它的成本

API 配额
取决于你选择的模型提供商配额
每次调用 Token 数
差异极大——取决于 agent 设计
费用
框架免费；向模型提供商付费
提示
开发阶段使用 --model haiku-4.5；生产运行和 eval 时切换到 sonnet

安全

权限、密钥、影响范围

最小权限： Whatever attached MCPs need
凭据存储： fastagent.secrets.yaml（已加入 .gitignore）或环境变量
数据出站： 发往挂载的 MCP 服务器和选定的模型提供商
切勿授予： 不要将生产写入 token 用于开发环境

故障排查

常见错误与修复

Agent 循环运行无法收敛

设置 max_steps；检查追踪记录找到循环位置。通常是工具返回了模糊输出，导致模型无限重试

验证： trace.get(run_id)
Eval 报告 0%，但手动运行正常

检查 golden_output 格式——严格字符串匹配 vs 语义匹配

配置中的 MCP 服务器挂载失败

先单独运行服务器命令；确认 fastagent.secrets.yaml 中存在所需环境变量

首次运行缓慢

uv 在首次调用时拉取依赖；后续有缓存。在 CI 中预热

替代方案

fast-agent 对比其他方案

替代方案何时用它替代权衡
PrefectHQ/fastmcp你想要的是标准 MCP 服务器框架，而非完整的 agent 框架fastmcp 用于构建服务器；fast-agent 用于构建（和编排）消费服务器的 agent
LangGraph你的团队已深度使用 LangChain 生态更通用；MCP 原生支持较弱
mcp-agent (lastmile-ai)你偏好更精简、面向教程的框架覆盖范围更小；电池不包含

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills