跳到主要内容

Agent SDK 概览

@openhex-ai/agent-sdk 是 OpenHex 官方的 TypeScript SDK：用它在你自己的后端、网站、小程序里和 OpenHex Agent 对话，并以服务商身份管理自己的用户。 它和 app.openhex.tech 网页端走的是同一套协议，通过 SDK 发起的对话和在应用里发起的没有区别。

npm install @openhex-ai/agent-sdk

SDK 由两部分组成​

对话 (Agent Chat)工作区 API (Workspace API)
做什么发消息、流式接收回复、附件、对话内卡片、语音、训练开通成员、签发会话令牌、发放积分、读取 Agent
谁来调用后端脚本，或拿着会话令牌的浏览器 / 小程序只在你的后端
入口client.sendMessage()、client.chat、@openhex-ai/agent-sdk/reactclient.workspace(slug)
凭据个人 API Key 或会话令牌工作区 API Key
从这里开始对话 (Chat)工作区 API 概览

大多数把 Agent 接进自己产品的集成两部分都会用到：后端用工作区 API 为用户签发会话令牌，前端用对话能力（通常是 React 组件）拿着令牌聊天。

我想……​

目标看这里
用脚本调用自己的 Agent快速开始
给网站加一个客服气泡示例：网站客服组件
把 Agent 接进微信小程序示例：微信小程序
在自己的界面里嵌入聊天React 组件
让用户用我自己的账号体系和 Agent 对话工作区 API 概览 → 会话令牌
给用户发积分积分
在对话里收款、收集联系方式支付宝收款、信息收集卡片
让 Agent 用每个用户自己的凭据调用外部系统接入外部工具 (MCP)
自动化训练自己的 Agent训练模式

能力一览​

能力说明
对话发消息、流式接收、多轮上下文、历史、打断
附件随消息发送图片 / 文件；读取 Agent 生成的图片和产出的文档
语音回复把 Agent 的回复朗读出来，流式播放并缓存
训练模式以所有者身份和 Agent 对话，让它根据反馈调整
子 Agent 与委派看到这一轮交给了哪个子 Agent
信息收集卡片对话内收集访客的联系信息
支付宝收款对话内展示收款卡片并感知付款结果
接入外部工具给 Agent 挂 MCP 服务，按用户注入凭据
React 组件<ChatWidget>、<ChatBox>、useOpenhexChat()
工作区 API成员、会话令牌、积分、Agent 读取

包里还导出了 query()、tool() 等用于「在本地进程里运行 Agent 循环」的接口，它们目前是预留入口，调用会抛出 NotImplementedError，本文档不涉及。

运行环境​

  • Node.js 18+（需要全局 fetch）或任意现代浏览器。纯 ESM 包。
  • React 组件需要 React 18+，react / react-dom 为 peer 依赖。
  • 自带 TypeScript 类型，所有请求 / 响应类型都从包根导出。
  • 默认连接 https://api.openhex.tech。

30 秒上手​

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

const client = new OpenhexClient({
  apiKey: process.env.OPENHEX_API_KEY, // 个人 API Key：设置 → API Key
  agentId: process.env.OPENHEX_AGENT_ID, // Agent ID：见「鉴权 · Agent ID」
});

const turn = await client.sendMessage('你好，你能帮我做什么？');
console.log(turn.text);

下一步​