> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API

> 列出 Runtime Agent 并读取可用能力。

# Agent API

## 列出 Agent

`GET /v1/agents` 返回当前 Runtime 已注册的 Agent。调用方应使用返回的稳定 ID 构造 run 路径，而不是依赖显示名称。

## 获取 Agent 详情

`GET /v1/agents/:agentId` 返回某个 Agent 的**配置层 + 运行时层**完整信息：模型、工具、MCP server、实际扫描到的 Skill、Subagent、数据集等，用于运维、调试与控制台展示。

| 属性           | 值                                                      |
| ------------ | ------------------------------------------------------ |
| 路径参数         | `agentId`（string，必填）                                   |
| 鉴权           | 受 `ZERONE_AGENT_HTTP_API_KEY` / `auth.apiKey` 保护（若已配置） |
| Content-Type | `application/json`                                     |

```bash theme={null}
curl http://localhost:3000/v1/agents/my-agent
```

如启用鉴权：

```bash theme={null}
curl -H "x-api-key: your-runtime-api-key" \
     http://localhost:3000/v1/agents/my-agent
```

### 响应（200）

返回 `AgentDetail` 对象。未配置的字段（`allowedTools`、`mcpServers`、`subagents` 等）**不会出现在响应里**（不是 `null`）。

最小配置的响应：

```json theme={null}
{
  "id": "min",
  "name": "min",
  "model": "claude-sonnet-4-6",
  "status": "ready",
  "maxTurns": 10,
  "hasSystemPrompt": false
}
```

带 Skill 扫描结果的响应：

```json theme={null}
{
  "id": "assistant",
  "name": "assistant",
  "model": "claude-sonnet-4-6",
  "status": "ready",
  "maxTurns": 50,
  "hasSystemPrompt": true,
  "permissionMode": "auto",
  "allowedTools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "Skill"],
  "settingSources": ["user", "project"],
  "availableSkills": [
    {
      "name": "code-review",
      "description": "Review code changes",
      "source": "user",
      "location": "/home/user/.openagent/skills/code-review/SKILL.md"
    },
    {
      "name": "reflection",
      "description": "Reflect on outputs",
      "source": "project",
      "location": "/workdir/.openagent/skills/reflection/SKILL.md"
    }
  ]
}
```

带 MCP server（已脱敏）的响应：

```json theme={null}
{
  "id": "mcp-agent",
  "name": "MCP Agent",
  "model": "claude-sonnet-4-6",
  "status": "ready",
  "maxTurns": 10,
  "hasSystemPrompt": true,
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "mcp-server-github",
      "args": ["--owner", "myorg"],
      "env": {
        "GITHUB_TOKEN": "***"
      }
    },
    "remote": {
      "transport": "sse",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "***"
      }
    }
  }
}
```

带 Subagent 的响应——Subagent 只返回 `{ description }`，不返回 `prompt`、`tools`、`model` 等内部字段：

```json theme={null}
{
  "id": "coordinator",
  "name": "Coordinator",
  "model": "claude-sonnet-4-6",
  "status": "ready",
  "maxTurns": 10,
  "hasSystemPrompt": true,
  "subagents": {
    "coder": { "description": "Write and edit code" },
    "researcher": { "description": "Research topics on the web" }
  }
}
```

Agent 配置解析失败时（例如 `systemPromptFile` 找不到文件），`status` 为 `"unavailable"`，但响应仍是 `200` + 完整 `AgentDetail`，上游据此判断该 Agent 是否可调用：

```json theme={null}
{
  "id": "broken",
  "name": "broken",
  "model": "claude-sonnet-4-6",
  "status": "unavailable",
  "maxTurns": 10,
  "hasSystemPrompt": false
}
```

### 响应（404）

`agentId` 不存在时：

```json theme={null}
{ "error": "Agent not found" }
```

## AgentDetail 字段

<Note>配置层 vs 运行时层：`settingSources` 是配置（“扫哪里”），`availableSkills` 是运行时（“扫到了什么”）。后者由 Runtime 在启动时根据前者扫描文件系统得出，反映真实可用的 SKILL.md 清单。</Note>

必返回字段：

| 字段                | 类型                           | 说明                                                                             |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------ |
| `id`              | string                       | Agent 标识符（与路径参数一致）                                                             |
| `name`            | string                       | Agent 显示名（未配置 `name` 时回退为 `id`）                                                |
| `model`           | string                       | LLM 模型名                                                                        |
| `status`          | `"ready"` \| `"unavailable"` | Agent 是否可调用                                                                    |
| `maxTurns`        | number                       | Agent 主循环最大轮数（默认 `10`）                                                         |
| `hasSystemPrompt` | boolean                      | 是否配置了系统提示词。`true` = 配置了 `systemPrompt` 或 `systemPromptFile`（不读取文件内容，仅判断字段是否设置） |

可选字段（仅在已配置时出现）：

| 字段                   | 类型                                        | 说明                                                                                                          |
| -------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `permissionMode`     | string                                    | 工具权限模式：`default` / `acceptEdits` / `bypassPermissions` / `plan` / `dontAsk` / `auto`                        |
| `allowedTools`       | string\[]                                 | 工具白名单                                                                                                       |
| `disallowedTools`    | string\[]                                 | 工具黑名单                                                                                                       |
| `availableSkills`    | SkillSummary\[]                           | **运行时层**：启动时扫描文件系统得出的实际可用 Skill 清单，仅在扫到至少 1 个时出现                                                            |
| `settingSources`     | (`"user"` \| `"project"` \| `"local"`)\[] | **配置层**：Skill 扫描来源：`user` → `~/.openagent/skills/`，`project` → `<cwd>/.openagent/skills/`，`local` → 预留（无操作） |
| `extraUserSkillDirs` | string\[]                                 | 额外的 user 级 Skill 目录                                                                                         |
| `mcpServers`         | Record\<string, McpServerSummary>         | MCP server，已脱敏                                                                                              |
| `subagents`          | Record\<string, \{ description: string }> | Subagent，仅含 `description`                                                                                   |
| `datasets`           | Record\<string, string>                   | 数据集 ID 到描述的映射（运行时注入到 system prompt）                                                                         |

## Skill 扫描与 SkillSummary

Skill **完全基于文件系统**，没有白名单配置。Runtime 启动时按以下顺序扫描目录：

1. `settingSources: ["user"]` → `~/.openagent/skills/` + `extraUserSkillDirs`
2. `settingSources: ["project"]` → `<cwd>/.openagent/skills/`

所有扫描到的 SKILL.md 都会暴露给 Agent，没有过滤。同名 Skill 后扫描到的覆盖先扫描到的（project 覆盖 user）。扫描结果缓存在 `availableSkills` 字段，**重启 Runtime 才会刷新**——文件系统变化不会自动反映到详情接口。

`availableSkills` 数组元素（`SkillSummary`）的字段：

| 字段            | 类型                      | 说明                                                                                                 |
| ------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| `name`        | string                  | Skill 名（取自 SKILL.md frontmatter 的 `name` 字段；未填则用所在目录名）                                             |
| `description` | string                  | Skill 描述（取自 SKILL.md frontmatter 的 `description` 字段，必填）                                            |
| `source`      | `"user"` \| `"project"` | 来源层级：`user` = `~/.openagent/skills/` 或 `extraUserSkillDirs`；`project` = `<cwd>/.openagent/skills/` |
| `location`    | string                  | SKILL.md 文件的绝对路径                                                                                   |

## McpServerSummary 与脱敏策略

所有 MCP server 共有字段：

| 字段          | 类型                               | 说明   |
| ----------- | -------------------------------- | ---- |
| `transport` | `"stdio"` \| `"sse"` \| `"http"` | 传输方式 |

stdio 专属（可选）：

| 字段        | 类型                      | 说明                                     |
| --------- | ----------------------- | -------------------------------------- |
| `command` | string                  | 启动命令（如 `npx`、`mcp-server-github`），原样返回 |
| `args`    | string\[]               | 命令行参数，原样返回                             |
| `env`     | Record\<string, string> | 环境变量，**值脱敏**为 `"***"`（key 保留）          |

sse / http 专属（可选）：

| 字段        | 类型                      | 说明                           |
| --------- | ----------------------- | ---------------------------- |
| `url`     | string                  | MCP server URL，原样返回          |
| `headers` | Record\<string, string> | 请求头，**值脱敏**为 `"***"`（key 保留） |

<Warning>接口只对 `env` 和 `headers` 的值强制脱敏。`args` 和 `url` 原样返回，理论上可能携带密钥——`args` 可能含 `--token=xxx` 形式的内联密钥，`url` 可能含 `?token=xxx` 查询参数或 `https://user:pass@host` 内嵌凭证。上游消费方在 UI 或日志展示 MCP server 配置时，对 `args` 和 `url` 也应保持警惕，不要原样落日志或展示给终端用户。</Warning>

## Subagent 返回范围

每个 Subagent 仅返回 `{ "description": string }`——保留让父 Agent 选择子代理的信息。不返回 `prompt`、`tools`、`disallowedTools`、`model`、`mcpServers`、`skills`、`maxTurns`。目前没有查看 Subagent 完整配置的单独端点。

## 兼容性

新的详情响应是旧响应（`{ id, status }`）的严格超集：旧消费者只读 `id` 和 `status` 两个字段，新增字段不影响其行为。`GET /v1/agents`（Agent 列表）形态不变，`POST /v1/agents/:agentId/runs` 行为不变，鉴权机制不变。

## 认证

若启用 API key，所有 `/v1/*` 请求都要携带：

```http theme={null}
x-api-key: your-runtime-api-key
```

`GET /health` 不需要认证，可用于容器探针。

## 相关

* [配置](/zh/runtime/configuration)：`agents.yaml` 的字段全集