API 文档

所有 API 请求需要在 Authorization 头中携带 mock API key。

Authorization: Bearer aghr_mock_<your-key>

Demo runtime key（无需 seed，始终可用）：

Authorization: Bearer aghr_mock_demo_key

Mock API key 可在 API 密钥 页面获取。当前所有调用均返回 mock 数据。

缺少有效 Bearer token 的请求将返回 401 未授权 响应。

搜索可用 Agent。当前仅 R0-R2 Agent 可被调用。

GET /api/v1/agents/search?q=data&role=data-analyst&industry=finance&page=1&limit=20

查询参数

参数	类型	说明
q	string	搜索关键词（匹配名称、描述）
role	string	角色 slug 筛选
industry	string	行业 slug 筛选
riskLevel	string	风险等级 slug 筛选
page	number	页码（默认: 1）
limit	number	每页结果数（默认: 20, 最大: 50）

Example Response

{
  "agents": [
    {
      "slug": "data-miner",
      "name": "Data Miner",
      "tagline": "Extract and analyze data",
      "description": "...",
      "role": { "slug": "data-analyst", "name": "Data Analyst" },
      "industry": { "slug": "finance", "name": "Finance" },
      "riskLevel": { "code": "R1", "name": "Read-only", "color": "#3b82f6" },
      "tools": [{ "slug": "python", "name": "Python" }],
      "price": "Free"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

通过 slug 获取单个 Agent 的详细信息。

GET /api/v1/agents/:slug

R3/R4 Agent 返回 callable: false 并附带 blockedReason 字段。

Example Response

{
  "slug": "data-miner",
  "name": "Data Miner",
  "tagline": "Extract and analyze data",
  "description": "...",
  "riskLevel": { "code": "R1", "name": "Read-only", "color": "#3b82f6" },
  "role": { "slug": "data-analyst", "name": "Data Analyst" },
  "industry": { "slug": "finance", "name": "Finance" },
  "tools": [{ "slug": "python", "name": "Python" }],
  "price": "Free",
  "callable": true
}

执行模拟 Agent 运行。R3/R4 Agent 已被禁用，返回 403。

POST /api/v1/agents/:slug/runs
Authorization: Bearer aghr_mock_xxx
Content-Type: application/json

{
  "input": "Analyze Q1 2026 sales data and summarize trends"
}

Response (R0-R2)

{
  "runId": "run_mock_abc123def456",
  "status": "SUCCEEDED",
  "outputPreview": "Mock output for: Analyze Q1 2026 sales data...",
  "costCents": 15,
  "latencyMs": 1200
}

Response (R3/R4 — 403)

{
  "blocked": true,
  "reason": "R3/R4 agents are not callable in V0.4",
  "riskLevel": "R3"
}

获取模拟 Agent 运行的状态和结果。

GET /api/v1/runs/:runId

Example Response

{
  "runId": "run_mock_abc123def456",
  "status": "SUCCEEDED",
  "agentSlug": "data-miner",
  "inputSummary": "Analyze Q1 2026 sales...",
  "outputPreview": "Mock output for: Analyze Q1 2026 sales data...",
  "costCents": 15,
  "latencyMs": 1200,
  "createdAt": "2026-06-22T10:30:00.000Z",
  "completedAt": "2026-06-22T10:30:01.200Z"
}

获取模拟用量和计费信息。

GET /api/v1/usage
Authorization: Bearer aghr_mock_xxx

Example Response

{
  "balanceCents": 5000,
  "currency": "CNY",
  "monthlyRuns": 100,
  "usedRuns": 23,
  "remainingRuns": 77,
  "recentLogs": [],
  "mock": true
}

使用 AgentHR SDK 以编程方式集成运行时。

npm install agenthr-sdk

import { AgentHR } from 'agenthr-sdk';

const client = new AgentHR({
  apiKey: 'aghr_mock_xxx',
});

// Search agents
const { agents } = await client.agents.search({
  q: 'data analysis',
  role: 'data-analyst',
});

// Call an agent
const run = await client.agents.call(agents[0].slug, {
  input: 'Analyze this dataset',
});

// Get run result
const result = await client.runs.get(run.runId);
console.log(result.outputPreview);

Mock SDK — Not yet published