Agent SDK 概览
@openhex/agent-sdk 是 OpenHex 的官方 TypeScript SDK——它把你在 app.openhex.tech 里和 Agent 对话、管理工作区成员与积分的同一套能力，封装成一个可以直接 import 的库。 用它，你能在自己的后端、脚本或产品里以编程方式调用 OpenHex，而不必手写 HTTP 请求。
SDK 走的是和网页端、移动端完全相同的协议，所以通过 SDK 发起的对话，与在应用里发起的对话别无二致。
这个 SDK 能做什么
| 能力 | 说明 | 状态 |
|---|---|---|
| 对话 (Chat) | 向已发布的 Agent 发消息、流式接收回复、维持多轮上下文 | ✅ 可用 |
| 工作区 (Workspaces) | 作为服务商 (SP) 开通成员、发放积分、签发会话、读取用量报表 | ✅ 可用 |
本地 Agent 循环 (query()) | 在你自己的进程里跑一个带工具的 Agent 循环 | 🚧 脚手架（运行时后续版本提供） |
本页及后续示例只覆盖已可用的两块能力。
query()目前是占位实现，调用会抛NotImplementedError。
安装
npm install @openhex/agent-sdk
# 或
pnpm add @openhex/agent-sdk
SDK 是纯 ESM 包，要求 Node.js ≥ 20。zod 是 peer 依赖，由你的项目自带（避免跨包 instanceof 失效）。
鉴权 (Authentication)
SDK 用一个 Bearer 令牌鉴权。你传入哪种令牌，就决定了能调用哪些接口：
| 令牌 | 形如 | 用途 |
|---|---|---|
| 用户 API Key / JWT | mysta_… | 以某个用户身份对话、训练 Agent |
| 工作区 API Key | sk_ws_… | 服务商后端管理工作区（成员、会话、积分） |
| 工作区所有者 JWT | （登录态 JWT） | 工作区管理后台操作（报表、API Key 管理） |
令牌可以显式传给客户端，也可以放进环境变量 OPENHEX_API_KEY 让 SDK 自动读取：
export OPENHEX_API_KEY=mysta_... # 或 sk_ws_...
import { OpenhexClient } from '@openhex/agent-sdk';
// 显式传入
const client = new OpenhexClient({ apiKey: 'mysta_...' });
// 或省略 apiKey，自动读取 OPENHEX_API_KEY
const client2 = new OpenhexClient();
默认连接生产环境 https://api.openhex.tech；自托管或联调时用 baseUrl 覆盖：
const client = new OpenhexClient({
baseUrl: 'https://api.staging.openhex.tech',
});
30 秒上手
import { OpenhexClient } from '@openhex/agent-sdk';
const client = new OpenhexClient({ agentId: '你的-agent-id' }); // apiKey 来自环境变量
const turn = await client.sendMessage('帮我总结一下最新的客服工单');
console.log(turn.text); // Agent 的回复文本
console.log(turn.toolCalls); // 它调用过的工具
console.log(turn.conversationId); // 继续这轮对话时复用它
下一步
- 快速开始 — 从安装到第一次对话与第一次工作区调用
- 对话 (Chat) — 多轮对话、流式输出与底层协议
- 工作区 (Workspaces) — 服务商集成：成员、会话、积分与报表
- API 参考 — 客户端配置、错误类型与导出一览