AI导哈

代理运行时测试工具

usb-agents是一个本地MCP可移植性实验室，用于比较不同代理运行时在相同工具、任务、传输、批准、跟踪、工件和回归门控下的行为。

  • by jlov7
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 jlov7/MCP-Interop-BakeOff

使用说明

usb代理

usb代理是一个本地MCP可移植性实验室，用于比较代理运行时的行为与 相同的工具、任务、传输、批准、跟踪、工件和回归门。

首先是OSS：安装CLI，在本地运行确定性套件，打开web控制台，然后使用 在连接真实的供应商凭据之前，CI中的输出。

它的作用

  • 跨运行时适配器和传输适配器运行相同的基准测试套件。
  • 在嵌入式、stdio和HTTP JSON-RPC传输上练习MCP风格的工具。
  • 捕获批准、工具调用、跟踪、延迟、故障和生成的工件。
  • 通过本地FastAPI API提供运行历史记录。
  • 提供Next.js控制台，用于矩阵比较、跟踪检查、审批审查、工件、， 以及并排的伪影差异。
  • 提供确定性的可视化和后端测试，因此UI和协议回归是可见的。

快速入门

uv sync --all-extras
pnpm install

uv run usb-agents doctor
uv run usb-agents run --transport embedded
uv run usb-agents serve

在另一个终端中：

pnpm dev:web

打开 http://127.0.0.1:3000.

核心命令

uv run usb-agents init
uv run usb-agents doctor
uv run usb-agents run --transport embedded
uv run usb-agents run --transport embedded --transport http --transport stdio
uv run usb-agents serve --port 8765
uv run usb-agents report
uv run usb-agents compare
uv run usb-agents conformance
uv run usb-agents sdk-smoke
uv run usb-agents golden-demo

当您需要在run store之外导出CSV/Markdown时，遗留脚本仍然可用：

uv run python scripts/run_matrix.py --transports embedded http stdio --fail-on-alert
uv run python scripts/report.py results.csv
uv run python scripts/trace_summary.py traces

建筑

flowchart LR
  CLI["CLI"] --> RunExecutor["Run executor"]
  API["FastAPI API"] --> RunExecutor
  Web["Next.js console"] --> API
  RunExecutor --> Runtimes["Runtime adapters"]
  Runtimes --> Transports["Transport clients"]
  Transports --> MCP["MCP JSON-RPC server"]
  RunExecutor --> Store["Run store"]
  Store --> API

关键模块：

  • src/usb_agents/run_executor.py：CLI和API三级运行的共享编排。
  • src/usb_agents/run_store.py：运行清单、工件索引和工件解析。
  • src/usb_agents_mcp/server.py：stdio和HTTP JSON-RPC MCP工具界面。
  • src/usb_agents_api/app.py：运行、事件流、工件、套件和适配器的本地API。
  • apps/web：本地产品控制台。

仓库结构

.
├── apps/web/              # Next.js local console and Playwright visual suite
├── docs/                  # Architecture, protocol, security, release, and verification docs
├── examples/              # Small reference fixtures for MCP and adapter authors
├── mcp-server/            # Compatibility wrapper and default approval policy
├── scripts/               # Legacy report/dashboard helpers
├── src/                   # Installable Python packages
├── tasks/                 # Immutable deterministic benchmark fixtures
├── tests/                 # Python protocol, API, runner, security, and metrics tests
├── PRODUCT.md             # Product direction
├── DESIGN.md              # Frontend design system
└── usb-agents.yaml        # Local suite/runtime/transport config

生成的运行、跟踪、屏幕截图、构建输出和本地依赖目录将被忽略。 使用 uv run usb-agents golden-demo 在下面创建一个新的精选演示 .usb-agents/runs/.

运行工件

生成的输出写在 .usb-agents/runs/<timestamp>/:

.usb-agents/runs/<timestamp>/
  run.json
  traces/*.ndjson
  artifacts/*.csv

跟踪的任务固定装置被视为不可变的。基准任务不得写入生成的输出 重新进入 tasks/.

验证

pnpm verify

或单独运行闸门：

uv run ruff check .
uv run mypy .
uv run pytest -q
pnpm lint
pnpm --filter @usb-agents/web build
pnpm verify:visual
pnpm verify:conformance
pnpm verify:release

pnpm verify:visual 使用确定性屏幕截图运行桌面和移动Playwright检查， 几何断言、减少的运动覆盖范围和无溢出检查。

MCP表面

本地服务器支持：

  • initialize
  • tools/list
  • tools/call
  • resources/list
  • resources/read
  • prompts/list
  • prompts/get

手动启动：

uv run python -m mcp_server.server --transport http --host 127.0.0.1 --port 8000
uv run python -m mcp_server.server --transport stdio

外部一致性烟雾：

uv run usb-agents conformance

这将启动本地MCP服务器并运行官方 @modelcontextprotocol/conformance 初始化服务器场景、工具列表、资源列表和提示列表。

运行时适配器

当前的运行时适配器是确定性模拟器支持的接缝：

  • OpenAI代理
  • Microsoft代理框架
  • 情妇特工

这是为了进行本地测试。SDK准备状态是明确的：

uv run usb-agents sdk-smoke
uv run usb-agents sdk-smoke --runtime openai_agents --require

--require 当相关凭据环境变量不存在时失败。

文档

质量标准

在打开pull请求之前，运行：

uv sync --all-extras
uv run ruff check .
uv run mypy .
uv run pytest -q
uv build
pnpm install
pnpm lint
pnpm --filter @usb-agents/web build
pnpm verify:visual
pnpm verify:conformance
uv run usb-agents run --transport embedded

看 贡献.md 维护人员的工作流程和发布期望。

相关 MCP