快速开始

几行代码，就能让你的程序和一个 OpenHex Agent 对话。 本页带你从零跑通：安装、配置令牌、发起第一次对话，再做一次工作区调用。

1. 安装

npm install @openhex/agent-sdk

2. 准备令牌与 Agent

在 app.openhex.tech 拿到你的 API Key，并找到要调用的已发布 Agent 的 id（进 Agent 详情页即可看到）。把 key 放进环境变量：

export OPENHEX_API_KEY=mysta_...

3. 第一次对话

新建 chat.ts：

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

const client = new OpenhexClient({ agentId: '你的-agent-id' });

const turn = await client.sendMessage('你好，你能帮我做什么？');
console.log('Agent：', turn.text);
console.log('用到的工具：', turn.toolCalls.map((t) => t.name));

运行（用 tsx 直接跑 TypeScript）：

OPENHEX_API_KEY=mysta_... npx tsx chat.ts

新对话的第一条消息会触发 Agent 的运行环境冷启动，首轮可能要等十几秒才有回复；SDK 默认会等够 180 秒，你无需额外处理。

4. 多轮与流式

conversation() 会记住对话 id，后续消息自动延续上下文：

const convo = client.conversation();
await convo.send('记住我的项目叫 Orbit。');
const reply = await convo.send('我的项目叫什么？'); // → “Orbit”
console.log(reply.text);

想要逐字流式输出，用 runTurn 配合事件辅助函数：

import { extractText, isTurnComplete } from '@openhex/agent-sdk';

for await (const record of client.runTurn('把它们按主题分组')) {
  if (record.sender === 'assistant') process.stdout.write(extractText(record));
  if (isTurnComplete(record)) break;
}

更完整的对话用法见 对话 (Chat)。

5. 一次工作区调用

如果你是服务商 (SP)，持有工作区 API Key（sk_ws_…），可以这样开通一个成员并发放积分：

const sp = new OpenhexClient({ apiKey: 'sk_ws_...' });

// 确认 key 属于哪个工作区
const me = await sp.workspaces.whoami();

// 用 slug 绑定一个工作区句柄，省去每次重复传 slug
const ws = sp.workspace(me.slug);

const member = await ws.provisionMember({ sp_user_ref: 'user-42', display_name: 'Ada' });
await ws.grantCredits(member.member_id, {
  amount: 500,
  idempotency_key: `signup-bonus:${member.member_id}`,
});

工作区的完整能力见 工作区 (Workspaces)。

下一步

• 对话 (Chat) — 多轮对话、流式输出与底层协议
• 工作区 (Workspaces) — 成员、会话、积分与报表
• API 参考 — 客户端配置与错误处理