Skip to content

docs(i18n): sync API server discovery surfaces #33283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
r266-tech wants to merge 1 commit into
base: main
Choose a base branch
from
+59 −2
Open

docs(i18n): sync API server discovery surfaces #33283

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion website/docs/user-guide/features/api-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,12 @@ Returns a machine-readable description of the API server's stable surface for ex
"run_submission": true,
"run_status": true,
"run_events_sse": true,
"run_stop": true
"run_stop": true,
"skills_api": true,
"session_resources": true,
"session_chat": true,
"session_chat_streaming": true,
"session_fork": true
}
}
```
Expand Down
54 changes: 53 additions & 1 deletion ...h-Hans/docusaurus-plugin-content-docs/current/user-guide/features/api-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,12 @@ OpenAI Responses API 格式。通过 `previous_response_id` 支持服务端对
"run_submission": true,
"run_status": true,
"run_events_sse": true,
"run_stop": true
"run_stop": true,
"skills_api": true,
"session_resources": true,
"session_chat": true,
"session_chat_streaming": true,
"session_fork": true
}
}
```
Expand Down Expand Up @@ -313,6 +318,53 @@ run 会保持 `stopping` 并继续被跟踪，直到 executor 支持的工作退

立即触发任务运行，不受计划限制。

## 会话 API（通过 REST 控制会话）

外部 UI 无需启动 dashboard，即可通过 REST 管理 Hermes session。所有端点均由 `API_SERVER_KEY` 保护，并位于 `/api/sessions/*` 下。

| 方法 | 路径 | 说明 |
|--------|------|-------------|
| `GET` | `/api/sessions` | 列出 session（分页参数：`limit`、`offset`、`source`、`include_children`） |
| `POST` | `/api/sessions` | 创建空 session |
| `GET` | `/api/sessions/{id}` | 读取 session 元数据 |
| `PATCH` | `/api/sessions/{id}` | 更新标题或 `end_reason` |
| `DELETE` | `/api/sessions/{id}` | 删除 session |
| `GET` | `/api/sessions/{id}/messages` | 读取 session 的消息历史 |
| `POST` | `/api/sessions/{id}/fork` | 通过 `SessionDB` 系谱分支 session（与 CLI `/branch` 语义一致） |
| `POST` | `/api/sessions/{id}/chat` | 运行一次同步 agent 轮次 |
| `POST` | `/api/sessions/{id}/chat/stream` | 单轮对话的 SSE 包装，会发出 `assistant.delta`、`tool.started`、`tool.completed`、`run.completed` 事件 |

`/v1/capabilities` 通过 `session_*` feature flags 与 `endpoints.session_*` 条目公布完整接口，使外部 UI 能检测支持情况并安全回退。`chat` 和 `chat/stream` 载荷支持内联图像（具备多模态感知的路径）。

```bash
# 分支 session 并运行一轮对话
curl -X POST http://localhost:8642/api/sessions/$ID/fork \
-H "Authorization: Bearer $API_SERVER_KEY" \
-d '{"title": "explore alt path"}'

# 通过 SSE 流式传输一轮对话
curl -N -X POST http://localhost:8642/api/sessions/$ID/chat/stream \
-H "Authorization: Bearer $API_SERVER_KEY" \
-d '{"input": "what files changed in the last hour?"}'
```

## 技能与工具集发现

`GET /v1/skills` 和 `GET /v1/toolsets` 使外部客户端能通过 REST 确定性地枚举 agent 的能力，而无需询问模型。两个端点均为只读，并由 `API_SERVER_KEY` 保护。

```bash
curl http://localhost:8642/v1/skills \
-H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "github-pr-workflow", "description": "...", "category": "..."}, ...]

curl http://localhost:8642/v1/toolsets \
-H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "core", "label": "...", "description": "...", "enabled": true,
# "configured": true, "tools": ["read_file", "write_file", ...]}, ...]
```

`/v1/skills` 返回 skills hub 内部使用的同一份元数据。`/v1/toolsets` 返回为 `api_server` 平台解析后的 toolset，以及每个 toolset 展开后的具体 `tools` 列表。两者都通过 `/v1/capabilities` 中的 `endpoints.*` 公布。

## 系统 Prompt 处理

当前端发送 `system` 消息（Chat Completions）或 `instructions` 字段（Responses API）时，hermes-agent 会将其**叠加在**核心系统 prompt 之上。你的 agent 保留所有工具、记忆和技能——前端的系统 prompt 只是添加额外指令。
Expand Down
Loading