API 参考

本页列出 @openhex-ai/agent-sdk 对话部分的全部公开方法、事件辅助函数与导出。 工作区相关的方法见工作区方法参考，React 组件的属性见 React 组件。

所有方法最后一个参数都接受 { signal?: AbortSignal }，下文不再重复。所有 HTTP 路由都在 /api/v2 之下。

包的入口

入口	内容
`@openhex-ai/agent-sdk`	客户端、事件辅助函数、错误类型、全部 TypeScript 类型
`@openhex-ai/agent-sdk/react`	`ChatWidget`、`ChatBox`、`useOpenhexChat` 及卡片组件

OpenhexClient

const client = new OpenhexClient(config?: OpenhexClientConfig);

配置

字段	类型	默认值	说明
`apiKey`	`string`	`OPENHEX_API_KEY`	个人 API Key、工作区 API Key 或会话令牌，见鉴权
`baseUrl`	`string`	`https://api.openhex.tech`	平台 API 地址
`agentId`	`string`	—	新对话默认路由到的 Agent；`training()` 的默认 Agent。获取方式见获取 Agent ID；SDK 不读 `OPENHEX_AGENT_ID`，需显式传入
`timeoutMs`	`number`	`30000`	非流式请求超时
`mcpTokens`	`Record<string,string>` \| `() => …`	—	每次发送都带上的会话级 MCP 凭据，见接入外部工具
`fetch`	`typeof fetch`	全局 `fetch`	自定义 fetch
`loginType`	`string`	—	附加 `X-Login-Type` 请求头（仅登录态 JWT 相关）
`actAs`	`string`	—	附加 `X-Act-As` 请求头，以自己拥有的服务账号身份调用

属性与方法

成员	说明
`sendMessage(message, opts?)` → `Promise<AgentTurn>`	发送并等待本轮结束
`runTurn(message, opts?)` → `AsyncGenerator<ChatStreamRecord>`	发送并流式产出本轮记录
`conversation(opts?)` → `Conversation`	记住对话 id 的句柄
`training(agentId?)` → `TrainingChat`	训练模式，见训练模式
`workspace(slug)` → `Workspace`	绑定 slug 的工作区句柄，见工作区方法参考
`chat`	`AgentChatClient`，协议原语
`files`	`FilesClient`，上传与读取文件
`payments`	`PaymentsClient`，查询收款订单
`workspaces`	`WorkspaceClient`，以 slug 为参数的工作区方法

sendMessage / runTurn 的选项：

选项	说明
`conversationId`	延续这段对话；不传则新建或续上最近的对话
`targetAgentIds`	新对话路由到的 Agent，默认 `[config.agentId]`
`parts`	附件部件，见附件
`mcpTokens`	本轮的 MCP 凭据，优先于客户端配置
`idleTimeoutMs`	连续多久无事件判定超时，默认 `180000`
`signal`	取消等待

conversation() 的选项：conversationId、targetAgentIds、mcpTokens。

AgentTurn

字段	类型	说明
`conversationId`	`string`	对话 id
`text`	`string`	本轮回复文本
`toolCalls`	`{ id?, name, input }[]`	本轮工具调用
`records`	`ChatStreamRecord[]`	本轮全部记录
`result`	`ChatRawEvent?`	本轮结束事件
`sessionId`	`string \| null`	会话 id
`lastEventId`	`string?`	最后一条记录的游标

Conversation

成员	说明
`id`	对话 id，第一次发送后才有值
`send(message, opts?)` → `Promise<AgentTurn>`	发送并等待本轮结束
`stream(message, opts?)` → `AsyncGenerator<ChatStreamRecord>`	发送并流式产出本轮记录
`interrupt()` → `Promise<InterruptResult>`	打断正在进行的一轮
`submitConnectorSetup(setup, values, { notify? })` → `Promise<AgentTurn \| undefined>`	保存用户凭据；默认随后自动发一条消息让 Agent 重试

send / stream 的选项除上表外，还可以带 SendRequest 的字段（如 parts、metadata、senderName）。

AgentChatClient（`client.chat`）

方法	HTTP	说明
`send(req)` → `SendResult`	`POST /conversations/send`	发送消息，立即返回
`stream(conversationId, opts?)`	`GET /conversations/{id}/stream`	长连接记录流，断线自动重连
`resumeTurn(conversationId, { lastEventId, idleTimeoutMs? })`	同上	从游标读到本轮结束
`runTurn(req, opts?)` / `sendMessage(req, opts?)`	同上	用完整 `SendRequest` 发送的高层方法
`conversation(opts?)`	—	创建 `Conversation`
`messages(conversationId)` → `{ entries }`	`GET /conversations/{id}/messages`	整段对话历史
`history(conversationId, { before, turns?, maxEntries?, includeThinking? })` → `{ entries, hasMore }`	`GET /conversations/{id}/history`	游标之前的历史分页
`interrupt(conversationId)` → `InterruptResult`	`POST /conversations/{id}/interrupt`	打断正在进行的一轮
`messageAudio(agentId, conversationId, messageId, opts?)` → `MessageAudioResult`	`POST /agents/{agentId}/messages/{messageId}/audio[/stream]`	朗读回复，见语音回复
`submitConnectorCredentials(connectorTypeId, credentials)`	`PUT /profile/credentials/{connectorTypeId}`	把 BYOK 凭据存到调用者自己的账户

SendRequest

字段	类型	说明
`message`	`string`	消息文本
`conversationId`	`string?`	延续这段对话
`targetAgentIds`	`string[]?`	新对话的 Agent：1 个直接路由；多个由协调者分派
`newConversation`	`boolean?`	不带 `conversationId` 时强制新开对话，而不是续上最近的一段
`parts`	`MessagePart[]?`	附件：`{ type: 'image_url', image_url: { url } }` / `{ type: 'file', file: { filename, file_url } }` / `{ type: 'text', text }`
`mcpTokens`	`Record<string,string>?`	会话级 MCP 凭据
`metadata`	`object?`	附带给 Agent 的元数据（例如卡片的回答）
`toolAction`	`boolean?`	标记为卡片动作，送达 Agent 但不作为普通消息显示
`senderName` / `senderAvatar`	`string?`	标注发送者

SendResult

{ conversationId, userMessage?, userEventId?, results: [{ agentId, msgId, streamId }] }。userEventId 是这条消息在事件流中的游标，从它之后读就是这条消息的回复。

ChatStreamRecord

字段	说明
`id`	游标，作为 `lastEventId` 续传
`seq` / `timestamp` / `sessionId`	序号、时间、会话
`sender`	`user` / `assistant` / `agent` / `system`
`event`	`message` / `agent_status` / `attachment` / …
`raw`	运行时事件，常见 `type`：`user`、`assistant`、`result`、`agent_status`、`attachment`、`payment_gate`、`payment_gate_resolution`

FilesClient（`client.files`）

方法	HTTP	说明
`upload(file, opts?)` → `UploadedFile`	`POST /files/upload`	上传，返回 `{ url, filename, size, mimeType, provider, nasPath?, agentPath? }`
`uploadPart(file, opts?)` → `MessagePart`	同上	上传并返回可发送的部件；`opts.as` 强制类型
`toPart(uploaded, as?)` → `MessagePart`	—	把上传结果转成部件
`readConversationFile(conversationId, path)` → `{ content, encoding, mimeType }`	`GET /conversations/{id}/files/read`	读取对话工作区里的文件
`downloadConversationFile(conversationId, path)` → `Blob`	`GET /conversations/{id}/files/download`	下载对话工作区里的文件

file 可以是 Blob / File，或 { data, filename, contentType? }。上传选项：agentId、chatGroupId、filename、contentType。

PaymentsClient（`client.payments`）

方法	HTTP	说明
`status(orderId)` → `{ status, amountCny? }`	`GET /payments/{orderId}/status`	订单状态：`pending` / `paid` / `expired` / `canceled`

TrainingChat（`client.training()`）

方法	HTTP	说明
`send(message)` → `{ ok, msgId? }`	`POST /agents/{id}/dev/send`	发送训练消息
`runTurn(message, opts?)`	发送后读 `GET /agents/{id}/messages/stream`	流式产出这一轮
`stream({ lastEventId?, turns?, reconnect? })`	`GET /agents/{id}/messages/stream`	训练对话记录流
`messages({ before? })` → `{ entries, hasMore? }`	`GET /agents/{id}/messages/history`	训练对话历史
`interrupt()`	`POST /agents/{id}/dev/interrupt`	打断

事件辅助函数

都接收一条 ChatStreamRecord：

函数	返回	说明
`extractText(record)`	`string`	回复文本（历史里的用户消息也能取到）
`extractToolCalls(record)`	`{ id?, name, input }[]`	工具调用
`isTurnComplete(record)`	`boolean`	是否本轮结束
`isInterrupt(record)`	`boolean`	是否表示被打断
`isAgentRecord(record)`	`boolean`	是否来自 Agent
`extractImages(record)`	`string[]`	Agent 生成的图片 URL
`extractFileAttachment(record)`	`FileAttachment \| null`	Agent 产出的文件：`{ name, workspacePath, mimeType?, size?, … }`
`extractDelegations(record)` / `isDelegationTool(name)`	`Delegation[]` / `boolean`	委派，见子 Agent 与委派
`extractPaymentGate(record)` / `isPaymentGate(record)`	`PaymentGatePayload \| null` / `boolean`	收款卡片
`extractPaymentResolution(record)`	`{ orderId, status } \| null`	付款结果
`extractInfoCollect(record)` / `isInfoCollect(record)`	`InfoCollectPayload \| null` / `boolean`	信息收集卡片
`infoCollectSubmitMetadata(values)` / `infoCollectSkipMetadata()`	`object`	回应信息收集卡片时的 `metadata`
`extractConnectorSetup(record)` / `isConnectorSetup(record)`	`ConnectorSetupRequest[]` / `boolean`	连接器配置卡片

语音

导出	说明
`MessageAudioCache(capacity = 10)`	按最近使用淘汰的音频缓存：`get` / `set` / `clear` / `size`
`downloadMessageAudio(http, agentId, conversationId, messageId, opts?)`	`chat.messageAudio` 的底层函数

错误

OpenhexSdkError（基类）、ApiError（status、body）、AuthenticationError、AbortError、NotImplementedError。见错误处理。

React 导出

导出	说明
`ChatWidget` / `ChatBox` / `useOpenhexChat`	见 React 组件
`InfoCollectCard` / `DEFAULT_INFO_COLLECT_LABELS`	信息收集卡片
`PaymentGateCard` / `DEFAULT_PAYMENT_LABELS`	收款卡片
`PLATFORM_TOKENS` / `tokenStyle(tokens)`	主题预设与把变量设在任意元素上的辅助函数
`useInjectStyles(enabled)` / `CHAT_CSS`	注入内置样式表 / 样式表文本
`Markdown`	组件内部使用的 Markdown 渲染

预留入口

query()、HttpTransport、tool() / createSdkMcpServer()（@openhex-ai/agent-sdk/tools）、hookMatcher() 以及 OpenhexClient.listSessions / getSession / deleteSession 是为本地 Agent 循环预留的接口，当前调用会抛出 NotImplementedError。

下一步

工作区方法参考 — 工作区接口的鉴权与错误码
React 组件 — 组件属性与 Hook 返回值
版本记录 — 各版本的变化

包的入口​

OpenhexClient​

配置​

属性与方法​

AgentTurn​

Conversation​

AgentChatClient（client.chat）​

SendRequest​

SendResult​

ChatStreamRecord​

FilesClient（client.files）​

PaymentsClient（client.payments）​

TrainingChat（client.training()）​

事件辅助函数​

语音​

错误​

React 导出​

预留入口​

下一步​