跳到主要内容

对话 (Chat)

对话 API 让你的程序像网页端一样和已发布的 Agent 聊天：发一条消息会创建（或延续）一个对话，并把它路由给 Agent；回复通过 SSE 流式返回，直到本轮结束。 它走的是用户端应用使用的同一套 conversations 协议。

创建客户端​

OpenhexClient 是有状态的高层封装：把连接和默认 Agent 配好一次，后面就能反复对话。

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

const client = new OpenhexClient({
  agentId: '你的-agent-id', // 新对话默认路由到的 Agent
  // apiKey 省略时从 OPENHEX_API_KEY 读取
});

发一条消息，拿到完整一轮​

sendMessage 发送消息并等到本轮结束，返回一个聚合好的 AgentTurn：

const turn = await client.sendMessage('总结一下最新的客服工单');

turn.text;            // 拼接好的回复文本
turn.toolCalls;       // Agent 这一轮调用过的工具
turn.conversationId;  // 复用它来继续这轮对话
turn.records;         // 本轮观察到的全部原始记录

多轮对话​

Conversation 句柄会记住对话 id，后续消息自动延续上下文：

const convo = client.conversation();
await convo.send('记住我最喜欢的颜色是青色。');
const reply = await convo.send('我刚说我喜欢什么颜色？'); // → “青色”

也可以传入已有的 conversationId 来接续一段历史对话：

const convo = client.conversation({ conversationId: '已有的对话 id' });

流式输出​

逐条消费本轮记录，配合事件辅助函数提取文本：

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;
}

常用辅助函数：

函数作用
extractText(record)从一条记录里取出助手文本
extractToolCalls(record)取出这条记录里的工具调用
isTurnComplete(record)是否为本轮的终止 result 事件
isInterrupt(record)这条记录是否表示对话被打断

底层协议​

当你需要完全掌控时，client.chat 把每个接口 1:1 暴露出来：

// POST /conversations/send —— 用 targetAgentIds 新建，或用 conversationId 接续
const { conversationId, userEventId } = await client.chat.send({
  message: 'hello',
  targetAgentIds: [agentId],
});

// GET /conversations/:id/stream —— 可断线重连的 SSE 流。
// 从某条记录的 id 续传，或从 userEventId 续传以精确捕获“这条消息的回复”。
for await (const record of client.chat.stream(conversationId, { lastEventId: userEventId })) {
  console.log(record.sender, record.raw.type);
  if (record.raw.type === 'result') break;
}

await client.chat.interrupt(conversationId);             // 打断正在进行的一轮
const { entries } = await client.chat.messages(conversationId); // 拉取完整历史

每条流式记录的结构为 { id, seq, sender, event, timestamp, sessionId, raw }，其中 raw 携带 Agent 运行时事件（{ type: 'assistant', message: { content: […] } }、{ type: 'result' } 等）——和应用里聊天界面消费的内容完全一致。

训练模式​

如果你是 Agent 的所有者，可以用训练模式对话——此时 Agent 运行在「创造 / 训练」态，会从你的反馈中学习：

const training = client.training('你的-agent-id'); // 省略则用客户端配置的 agentId
const result = await training.send('以后回复请更简洁。');

下一步​