Fallback

Fallback

  ______      _ _
 |  ____|    | | |
 | |__  __ _ | | |__   __ _  ___| | __
 |  __|/ _` || | '_ \ / _` |/ __| |/ /
 | |  | (_| || | |_) | (_| | (__|   <
 |_|   \__,_||_|_.__/ \__,_|\___|_|\_\

       find the route forward

Fallback

面向自主 Agent 的轻量付费恢复与决策工具。

当 Agent 陷入困境时，Fallback 可帮助它找到下一个安全步骤，避免浪费大量推理循环。

source_route 我应该去哪里查找？（$0.02）
error_route 为什么失败了？（$0.002）
request_repair 我可以安全地修复请求吗？（$0.005）
stop_search 继续搜索是否值得？（$0.003）

使用 Fallback

按次付费的工具，帮助 AI Agent 查找来源、诊断故障、修复请求，并决定何时停止搜索。Fallback 为自主 Agent 提供轻量、确定性的工具，供自动化陷入困境时使用：查找合适的来源、诊断请求失败、依据现有证据修复请求，以及判断是否值得继续搜索或付费检索。

托管服务

MCP 端点：https://fallback.factrail.online/mcp\ HTTP API 基础地址：https://fallback.factrail.online\ 付款：x402 V2 按次付费。请检查每个实时挑战，以确认网络、资产、金额和收款方。
Agent 技能：skill.md
OpenAPI：openapi.json
网络：Base 主网，规范 USDC
发布版本：v0.1.0-beta.1

工具

• source_route（$0.02）：我应该去哪里查找？ 查找可能具有权威性或机器可读的来源。
• error_route（$0.002）：我的调用为什么失败？ 对失败的请求进行分类，并建议范围有限的下一步操作。
• request_repair（$0.005）：我可以安全地修复请求吗？ 根据调用方提供的证据，提出幅度最小的修改。
• stop_search（$0.003）：继续搜索是否值得？ 根据证据和剩余成本，判断是否值得继续进行范围有限的搜索。

这些工具不能取代 Agent 的推理，而且 stop_search 绝不会证明某事物普遍不存在。

Agent 应在何时使用此工具

当 Agent 知道自己需要什么以及哪个发布方（域名或起始 URL），但不知道如何以机器可读的形式获取数据（例如 API、OpenAPI 规范、批量下载、数据集或信息源）时，使用 source_route。

• 适用场景：“获取 Eurostat 的最新人口数据集”“查找该机构统计数据的 JSON/CSV 路由”，也适用于 Agent 开始逐页浏览之前。
• 不适用场景：一般网络研究、回答事实性问题或核实事实（对于有来源支持的事实，请参阅 FACTRAIL MCP）。

如何解读结果：

• status: routes_found：按顺序尝试各个路由。score 是确定性排序结果，不是概率或置信度。
• status: no_suitable_route_found：在已检查的范围内没有找到合适的路由（参见 checked.direct_probes）。这并不能证明不存在路由。Agent 应另寻他处（其他主机、发布方的开放数据门户），而不是断定“没有 API”。
• 始终阅读 limitations。例如，其中会说明外部搜索是否不可用，或候选项检查是否达到上限。

每次调用的限制：最多 8 个直接 HTTP 请求、总计 12 s、每个响应不超过 1 MiB，且最多 1 次外部搜索请求。不进行 LLM 推理。托管测试版目前仅运行确定性发现（未配置搜索提供方）。

访问方式：托管 MCP https://fallback.factrail.online/mcp（Streamable HTTP），或 HTTP 工具路由；采用 x402 按次付费（每个付款挑战都会声明其支付网络和金额；无需账户或 API 密钥）。如需免费试用，可使用 PAYMENT_MODE=disabled 自托管（参见本地开发）。机器可读摘要：llms.txt。更多详情：将 Fallback 与 Agent 配合使用。

Fallback 已公开发布。请参阅当前发布与分发状态、产品更名影响审计、发现与分发准备情况审计，以及遥测和 30 天 KPI 定义。

何时使用 error_route

当 HTTP、API、MCP 或工具请求失败，且不确定接下来采取什么安全操作时，使用它。它会对提供的证据进行分类，并返回有限的重试建议。如果恢复方式已经明确，或任务需要更深入的领域推理，则不要使用它；它不会执行请求，也不会臆造未记录的修复方法。

要求

• 当前的 Node.js LTS（创建脚手架时为 Node 24；支持的引擎为 Node 22+）
• npm

本地开发

npm install
cp .env.example .env
npm run generate
npm run dev

服务器提供 /、/healthz、/readyz、/catalog.json、/openapi.json、/llms.txt、/llms-full.txt、/skill.md、/.well-known/x402.json、/.well-known/mcp/server-card.json，以及位于 /mcp 的 Streamable HTTP MCP 端点。HTTP 和 MCP 均通过共享的运行时处理程序注册表进行分发。PAYMENT_MODE=disabled 支持本地开发；付费部署必须明确选择 test 或 production，并提供完整的 x402 配置。

验证

npm test
npm run typecheck
npm run lint
npm run benchmark:source-route
npm run benchmark:error-route
npm run verify:catalog
npm run release:check

30 秒上手

将兼容 x402 的 Agent 连接到 https://fallback.factrail.online/mcp，在发生具体故障或做出搜索决策后调用相应工具，并且只批准付款挑战中显示的网络、代币、收款方和金额。HTTP 客户端可以在托管源站上使用 POST /v1/tools/{tool_id}。示例和架构请参阅 skill.md。

架构

src/core/registry.ts 是唯一的规范工具注册表。所有发现入口和分发制品都由它派生。每个工具在 src/tools/ 下都有自己的目录，其中包含契约和处理程序；未来的工具测试和测试夹具应放在与对应契约测试/测试夹具相邻的目录中。HTTP 和 MCP 适配器必须调用同一个工具处理程序。支付中间件和市场集成应保持在工具逻辑之外。

该服务支持按次调用、无需账户或 API 密钥的 x402 V2 付款。服务器只会在 X402_PAY_TO 接收付款；无需提供收款钱包私钥。若缺少或无效的必要网络、收款地址、facilitator URL 或生产 URL，付费启动将失败关闭。请参阅部署和支付设置。

示例

{
  "goal": "Download the latest population dataset",
  "start_url": "https://ec.europa.eu/eurostat/",
  "preferred_formats": ["csv", "json"]
}

使用目标以及 start_url 或 domain 调用 POST /v1/tools/source_route。结果仅限于已检查的范围；未找到结果并不意味着不存在此类路由。无需外部搜索凭据即可直接发现站点。如果已配置 Tavily 或 Brave，且直接发现结果不足，该工具最多可发起一次搜索请求。

请参阅 PRODUCT、ARCHITECTURE、TOOL_ADMISSION、DISTRIBUTION 和 RELEASE。

相关项目：FACTRAIL MCP

Fallback 遵循与同一作者的 FACTRAIL MCP 相同的设计原则：Agent 工具应报告检查了什么，而不仅仅是发现了什么。FACTRAIL 通过返回带有支持级别、未解决字段和收据的证据封套来回答“关于这个事实，哪些内容已得到证实，来源是什么？”（“未知胜过编造”）。Fallback 则回答“我可以从哪里获取这些数据？”（“不存在的证据不等于不存在”）。两者是相互独立的服务，没有代码依赖，你可以单独使用其中任意一个。