-
Notifications
You must be signed in to change notification settings - Fork 0
API Reference
Mickl edited this page Jul 10, 2026
·
2 revisions
完整的 REST API 参考，所有端点均基于 /api/v1。
http://localhost:3000/api/v1
Content-Type: application/json- 所有 POST/PATCH 请求体使用 JSON
成功响应：
{ "id": "xxx", "name": "example" }列表响应：
{ "projects": [...], "total": 10, "limit": 50, "offset": 0 }错误响应：
{ "error": "Validation failed", "details": {...} }| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
查询项目列表。
| 参数 | 类型 | 说明 |
|---|---|---|
search |
string | 按名称搜索（模糊匹配） |
limit |
number | 返回数量（默认 50，最大 100） |
offset |
number | 偏移量（默认 0） |
curl "http://localhost:3000/api/v1/projects?limit=10"创建新项目。
curl -X POST http://localhost:3000/api/v1/projects \
-H "Content-Type: application/json" \
-d '{"name":"客服 Agent","slug":"customer-service","description":"处理客户咨询"}'查询测试套件列表。
| 参数 | 类型 | 说明 |
|---|---|---|
projectId |
string | 必填，项目 ID |
curl "http://localhost:3000/api/v1/suites?projectId=<project-id>"创建测试套件。
curl -X POST http://localhost:3000/api/v1/suites \
-H "Content-Type: application/json" \
-d '{"projectId":"<project-id>","name":"退款测试套件"}'获取、更新或删除测试套件。
curl "http://localhost:3000/api/v1/suites/<suite-id>"
curl -X PATCH "http://localhost:3000/api/v1/suites/<suite-id>" \
-H "Content-Type: application/json" -d '{"name":"新名称"}'
curl -X DELETE "http://localhost:3000/api/v1/suites/<suite-id>"查询或创建测试用例。
创建请求体：
{
"name": "退款查询",
"description": "测试退款查询功能",
"agentConfig": {
"provider": "openai",
"model": "gpt-4o",
"temperature": 0.7,
"maxTokens": 4096,
"systemPrompt": "你是一个客服 Agent"
},
"input": {
"messages": [{"role": "user", "content": "如何退款？"}]
},
"tags": ["退款", "P0"],
"assertions": [
{"type": "tool_called", "params": {"tool": "search_docs"}},
{"type": "contains", "params": {"substring": "30天"}},
{"type": "tokens_lt", "params": {"threshold": 4096}}
],
"evaluators": [
{"type": "RULE_BASED", "config": {"rules": [{"type": "contains", "params": {"substring": "退款"}}]}},
{"type": "LLM_JUDGE", "config": {"provider": "openai", "model": "gpt-4o", "dimensions": ["correctness", "completeness"]}}
]
}获取、更新或删除测试用例。
管理测试用例下的断言。
curl -X POST "http://localhost:3000/api/v1/cases/<case-id>/assertions" \
-H "Content-Type: application/json" \
-d '{"type":"latency_lt","params":{"threshold":5000}}'管理测试用例下的评估器。
curl -X POST "http://localhost:3000/api/v1/cases/<case-id>/evaluators" \
-H "Content-Type: application/json" \
-d '{"type":"LLM_JUDGE","config":{"provider":"openai","model":"gpt-4o","dimensions":["correctness"]}}'查询 Run 列表。
| 参数 | 类型 | 说明 |
|---|---|---|
projectId |
string | 项目 ID |
status |
string | 状态过滤（PASSED/FAILED/ERROR） |
search |
string | 按名称搜索 |
limit |
number | 返回数量（默认 50） |
offset |
number | 偏移量 |
orderBy |
string | 排序字段（createdAt/duration） |
orderDir |
string | 排序方向（asc/desc） |
创建 Run。
curl -X POST http://localhost:3000/api/v1/runs \
-H "Content-Type: application/json" \
-d '{
"projectId":"<project-id>",
"testCaseId":"<case-id>",
"name":"GPT-4o 基线",
"config":{
"agent":{"provider":"openai","model":"gpt-4o","temperature":0.7,"maxTokens":4096,"systemPrompt":"你是客服"},
"input":{"messages":[{"role":"user","content":"退款流程"}]},
"options":{"timeout":30000,"maxSteps":10,"retries":1,"concurrency":1,"seed":42}
},
"tags":["baseline","gpt-4o"]
}'获取、更新或删除 Run。
评估一个 Run。
curl -X POST "http://localhost:3000/api/v1/runs/<run-id>/evaluate" \
-H "Content-Type: application/json" \
-d '{
"rules":[
{"type":"contains","params":{"substring":"退款"}},
{"type":"tokens_lt","params":{"threshold":4096}},
{"type":"latency_lt","params":{"threshold":10000}}
],
"dimensions":["correctness"],
"expected":"用户可以在30天内退款",
"force":true
}'回放一个 Run。
curl -X POST "http://localhost:3000/api/v1/runs/<run-id>/replay" \
-H "Content-Type: application/json" \
-d '{"mode":"cross_model","model":"claude-sonnet-5","batchCount":5}'对比两个 Run。
curl -X POST http://localhost:3000/api/v1/compare \
-H "Content-Type: application/json" \
-d '{"runAId":"<run-a-id>","runBId":"<run-b-id>"}'查询或创建快照。
curl -X POST "http://localhost:3000/api/v1/projects/<project-id>/snapshots" \
-H "Content-Type: application/json" \
-d '{
"name":"基线快照",
"type":"MANUAL",
"runId":"<run-id>",
"data":{...}
}'获取、恢复或删除快照。POST 会从快照创建新 Run。
查询或创建实验。
curl -X POST "http://localhost:3000/api/v1/projects/<project-id>/experiments" \
-H "Content-Type: application/json" \
-d '{
"name":"Prompt A vs B",
"variantA":{"systemPrompt":"你是一个乐于助人的客服"},
"variantB":{"systemPrompt":"你是一个专业的客服，语气正式"},
"runsPerVariant":10
}'获取、执行或删除实验。POST 会创建实验所需的 Run。
获取覆盖率报告。
curl "http://localhost:3000/api/v1/projects/<project-id>/coverage"数据集管理 API，v0.3.0 新增独立的数据集端点、导入/导出/验证/切分/版本管理。
查询数据集列表。
| 参数 | 类型 | 说明 |
|---|---|---|
projectId |
string | 项目 ID |
search |
string | 按名称搜索 |
format |
string | 格式过滤（csv/json/jsonl） |
limit |
number | 返回数量（默认 50） |
offset |
number | 偏移量 |
curl "http://localhost:3000/api/v1/datasets?projectId=<project-id>"创建数据集。
curl -X POST http://localhost:3000/api/v1/datasets \
-H "Content-Type: application/json" \
-d '{"name":"客服对话数据集","projectId":"<project-id>","format":"jsonl","description":"客户服务场景测试数据"}'获取数据集详情。
curl "http://localhost:3000/api/v1/datasets/<dataset-id>"响应包含完整的 schema、items 列表和元数据。
更新数据集信息。
curl -X PUT "http://localhost:3000/api/v1/datasets/<dataset-id>" \
-H "Content-Type: application/json" \
-d '{"name":"客服对话数据集 v2","description":"更新后的描述"}'删除数据集。
curl -X DELETE "http://localhost:3000/api/v1/datasets/<dataset-id>"导入数据集。支持 CSV、JSON、JSONL 格式。
# JSONL 导入
curl -X POST http://localhost:3000/api/v1/datasets/import \
-H "Content-Type: application/json" \
-d '{
"name":"客服对话",
"projectId":"<project-id>",
"format":"jsonl",
"data":"{\"messages\":[{\"role\":\"user\",\"content\":\"如何退款？\"}],\"expected\":{\"output\":\"可以在30天内退款\"}}\n...",
"options": {"autoDetectSchema": true, "skipInvalid": false}
}'
# CSV 导入
curl -X POST http://localhost:3000/api/v1/datasets/import \
-H "Content-Type: multipart/form-data" \
-F "file=@./dataset.csv" \
-F "name=客服训练数据" \
-F "projectId=<project-id>" \
-F "format=csv"导出数据集。
curl -X POST "http://localhost:3000/api/v1/datasets/<dataset-id>/export" \
-H "Content-Type: application/json" \
-d '{"format":"jsonl","includeMetadata":true}' \
-o dataset-export.jsonl| 参数 | 说明 |
|---|---|
format |
导出格式：csv、json、jsonl
|
includeMetadata |
是否包含元数据 |
version |
导出指定版本（默认最新） |
验证数据集质量和完整性。
curl -X POST "http://localhost:3000/api/v1/datasets/<dataset-id>/validate" \
-H "Content-Type: application/json" \
-d '{"strict": true}'响应：
{
"valid": true,
"issues": [],
"stats": {
"totalItems": 500,
"validItems": 498,
"invalidItems": 2,
"duplicates": 1,
"missingFields": 0,
"schemaMismatches": 1
},
"quality": {
"completeness": 0.996,
"consistency": 0.998,
"uniqueness": 0.998
}
}切分数据集为 train/test/val。
curl -X POST "http://localhost:3000/api/v1/datasets/<dataset-id>/split" \
-H "Content-Type: application/json" \
-d '{
"splits": {"train": 0.7, "test": 0.2, "val": 0.1},
"stratifyBy": "label",
"seed": 42,
"shuffle": true
}'响应返回三个数据集子集的 ID 和统计信息。
获取数据集的所有版本。
curl "http://localhost:3000/api/v1/datasets/<dataset-id>/versions"创建数据集新版本。
curl -X POST "http://localhost:3000/api/v1/datasets/<dataset-id>/versions" \
-H "Content-Type: application/json" \
-d '{"name":"v2","description":"添加了新场景","changes":"+50 items, updated schema"}'Benchmark 注册表和 Leaderboard API。
搜索和列表 Benchmark。
| 参数 | 类型 | 说明 |
|---|---|---|
search |
string | 按名称搜索 |
tag |
string | 按标签过滤（conversation、tool_use、rag 等） |
category |
string | 类别：conversation、rag、agentic、coding、custom
|
difficulty |
string | 难度：easy、medium、hard、expert
|
limit |
number | 返回数量（默认 50） |
offset |
number | 偏移量 |
orderBy |
string | 排序字段：popularity、name、createdAt
|
curl "http://localhost:3000/api/v1/benchmarks?search=customer&difficulty=medium"获取 Benchmark 详情。
curl "http://localhost:3000/api/v1/benchmarks/customer-service"响应：
{
"slug": "customer-service",
"name": "Customer Service Benchmark",
"version": "2.0.0",
"description": "Evaluate agent performance on customer service scenarios",
"category": "conversation",
"difficulty": "medium",
"tasks": [
{"id": "refund", "name": "Refund Processing", "scenarios": 12},
{"id": "complaint", "name": "Complaint Handling", "scenarios": 8},
{"id": "info", "name": "Information Retrieval", "scenarios": 15}
],
"metrics": ["accuracy", "latency", "cost", "user_satisfaction"],
"totalRuns": 12450,
"providers": ["openai", "anthropic", "gemini", "deepseek"],
"installed": false
}获取 Benchmark 排行榜。
| 参数 | 类型 | 说明 |
|---|---|---|
metric |
string | 按指标排序（默认 accuracy） |
limit |
number | 返回数量（默认 20） |
dateFrom |
string | 起始日期过滤 |
dateTo |
string | 截止日期过滤 |
curl "http://localhost:3000/api/v1/benchmarks/customer-service/leaderboard?metric=accuracy&limit=10"响应：
{
"benchmark": "customer-service",
"metric": "accuracy",
"entries": [
{
"rank": 1,
"model": "claude-sonnet-4-20250514",
"provider": "anthropic",
"score": 0.943,
"runs": 500,
"avgLatency": 2340,
"avgCost": 0.0089,
"submittedAt": "2026-06-15T10:30:00Z"
}
]
}提交结果到排行榜。
curl -X POST "http://localhost:3000/api/v1/benchmarks/customer-service/leaderboard" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <api-key>" \
-d '{
"runId": "<run-id>",
"public": true,
"metadata": {"notes": "DeepSeek v3 baseline run"}
}'生成并下载报告。
| 参数 | 类型 | 说明 |
|---|---|---|
runId |
string | Run ID（单报告） |
projectId |
string | 项目 ID（批量报告） |
format |
string | 格式：json/markdown/html/junit
|
curl "http://localhost:3000/api/v1/reports?runId=<run-id>&format=markdown" -o report.md
curl "http://localhost:3000/api/v1/reports?runId=<run-id>&format=junit" -o report.xml接收 CI/CD Webhook。
curl -X POST http://localhost:3000/api/v1/webhooks \
-H "Content-Type: application/json" \
-H "X-Webhook-Source: github" \
-H "X-Webhook-Secret: <secret>" \
-d '{"action":"opened","pull_request":{"number":42},"repository":{"full_name":"my-org/my-agent"}}'→ 返回文档中心
AgentBench v0.3.0 · GitHub · Report Issue · Changelog
- Core-Concepts
- Replay & Snapshots
- Assertions & Evaluation
- Coverage & Non-Determinism
- Guides
- Testing OpenAI / Anthropic
- CI/CD Integration
- Custom-Providers
- Migration-Guide
- Cookbook
- Prompt Regressions
- Model Migration
- Cost Budgets
- Safety Testing
- A/B Testing