API 参考

本页汇总 @openhex/agent-sdk 的客户端配置、方法一览与错误类型，作为速查。 每个端点字段级的 REST 参考见 Workspace API。

OpenhexClient

整个 SDK 的入口。一次配好连接与默认 Agent，之后复用。

import { OpenhexClient } from '@openhex/agent-sdk';

const client = new OpenhexClient({ apiKey: 'mysta_...', agentId: '...' });

配置项

字段	类型	说明
apiKey	string	API Key 或 JWT。省略时回退到环境变量 OPENHEX_API_KEY
baseUrl	string	平台 API 地址，默认 https://api.openhex.tech
agentId	string	新对话默认路由到的已发布 Agent id
loginType	string	X-Login-Type 请求头（与网页 / 移动端一致），仅 JWT 鉴权相关
actAs	string	通过 X-Act-As 模拟某个服务账号（调用方须拥有它）
timeoutMs	number	非流式请求的超时，默认 30000
fetch	typeof fetch	覆盖全局 fetch（测试 / 自定义运行时）

方法一览

对话

方法	说明
sendMessage(message, opts?)	发消息并等到本轮结束，返回 AgentTurn
runTurn(message, opts?)	发消息并流式产出本轮记录
conversation(opts?)	返回记住对话 id 的有状态 Conversation
training(agentId?)	以所有者身份进入训练模式对话
chat	底层 AgentChatClient，与 conversations 协议 1:1

工作区

方法	说明
workspaces	底层 WorkspaceClient（所有方法以 slug 为参）
workspace(slug)	返回绑定 slug 的 Workspace 句柄

WorkspaceClient / Workspace 上的方法：whoami、provisionMember、listMembers、suspendMember、grantCredits、mintSession、ledger、insights、memberLedger、listApiKeys、issueApiKey、revokeApiKey、sendSmsCode、verifySmsCode。各方法用法见 工作区 (Workspaces)。

错误类型

所有错误都继承自 OpenhexSdkError，可按需 catch：

类型	抛出时机
OpenhexSdkError	所有 SDK 错误的基类
AuthenticationError	选项与环境变量里都找不到 API Key
ApiError	平台返回非 2xx（带 status 与 body）
AbortError	一轮运行在产出结果前被中止
NotImplementedError	调用了尚为脚手架的入口（如 query()）

import { ApiError } from '@openhex/agent-sdk';

try {
  await client.workspaces.provisionMember('acme', { sp_user_ref: 'user-42' });
} catch (err) {
  if (err instanceof ApiError) {
    console.error(err.status, err.message); // 例如 403 "slug mismatch"
  } else {
    throw err;
  }
}

取消请求

所有方法都接受 signal，可用 AbortController 取消：

const ac = new AbortController();
const p = client.sendMessage('一个很长的任务', { signal: ac.signal });
ac.abort(); // 中止

导出一览

包根导出主要符号；自定义工具的辅助函数在子路径 @openhex/agent-sdk/tools：

import {
  OpenhexClient,                              // 高层客户端
  AgentChatClient, Conversation,              // 对话
  WorkspaceClient, Workspace,                 // 工作区
  extractText, extractToolCalls,              // 事件辅助
  isTurnComplete, isInterrupt,
  OpenhexSdkError, ApiError, AuthenticationError, AbortError, // 错误
} from '@openhex/agent-sdk';

import { tool, createSdkMcpServer } from '@openhex/agent-sdk/tools'; // 自定义工具（配合脚手架 query()）

请求 / 响应的 TypeScript 类型（如 AgentTurn、WorkspaceMember、ProvisionMemberResponse 等）也都从包根导出，便于在你自己的代码里复用。

下一步

• 快速开始 — 从安装到第一次调用
• 对话 (Chat) — 多轮对话与流式输出
• 工作区 (Workspaces) — 成员、会话、积分与报表