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

curl http://localhost:3000/v1/agents/my-agent

如启用鉴权：

curl -H "x-api-key: your-runtime-api-key" \
     http://localhost:3000/v1/agents/my-agent

​

响应（200）

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

最小配置的响应：

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

带 Skill 扫描结果的响应：

{
  "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（已脱敏）的响应：

{
  "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 等内部字段：

{
  "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 是否可调用：

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

​

响应（404）

agentId 不存在时：

{ "error": "Agent not found" }

​

AgentDetail 字段

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

必返回字段：

字段	类型	说明
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 保留）

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

​

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/* 请求都要携带：

x-api-key: your-runtime-api-key

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

​

相关

• 配置：agents.yaml 的字段全集