介绍
OpenMax Chat SDK 是什么:一套让人和 Agent 在同一个会话里协作的聊天界面,适合谁用、从哪里开始。
介绍
一套带样式的 React 聊天界面:会话列表、消息区、输入框,会话里既有人也有 Agent。你提供一个宿主对象,负责取数据和发消息。

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): chat-app.tsx
"use client";
import { ConversationList } from "@openmaxai/chat/conversation-list";
import { ChatHeader } from "@openmaxai/chat/header";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend), and
// useDemoConversations() is its conversation list (a DM started from search is added to it).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoConversations, useDemoHost, useIsCompact } from "./kit";
export default function ChatApp() {
const host = useDemoHost();
const conversations = useDemoConversations();
const isCompact = useIsCompact();
const [selectedId, setSelectedId] = useState<string | null>(
isCompact ? null : conversations[0].id,
);
const selected = conversations.find((c) => c.id === selectedId) ?? null;
return (
<ChatHostProvider host={host}>
<div className="flex h-full bg-background text-foreground">
{/* On a phone show one column at a time: the list, or the open conversation. */}
<aside
className={
isCompact ? (selected ? "hidden" : "min-w-0 flex-1") : "shrink-0"
}
>
<ConversationList
conversations={conversations}
selectedId={selectedId}
onSelect={(c) => setSelectedId(c.id)}
onDeselect={() => setSelectedId(null)}
// Starting a DM from search opens it here too.
onSelectConversationId={setSelectedId}
/>
</aside>
{selected && (
<main className="flex min-w-0 flex-1 flex-col">
<ChatHeader
conversation={selected}
headerTitle={selected.name ?? ""}
headerSubtitle={null}
isAgentCollab={false}
isObserving={false}
collabAgents={[]}
typingText={null}
mode={isCompact ? "compact" : "full"}
onBack={isCompact ? () => setSelectedId(null) : undefined}
infoPanelOpen={false}
/>
<MessageThread key={selected.id} conversation={selected} />
</main>
)}
</div>
</ChatHostProvider>
);
}
人和 Agent 在同一个会话里
Agent 是会话成员,和人一样收消息、发消息、被 @。一个会话里可以有几个人和几个 Agent,Agent 常驻在会话里,不是点一下才启动的一次性调用。
在这之上,SDK 规划让会话里的每个人都看到 Agent 正在做什么:收到消息后排队、开始处理、调用了哪些工具、什么时候结束;有权限的人可以停止一次运行,或只停其中的一次子 Agent 调用;Agent 需要人拍板时发一张审批卡,答案交回 Agent。这些经宿主的 agentRuns 能力接入。规划中 概念见核心概念。
适合谁用
- 基于 OpenMax 后端的团队:SDK 自带直连该后端的宿主。
- 用其他数据源的团队(别的后端、mock、测试夹具):你写加载和发送消息的函数,草稿、上传、文案由 SDK 补齐。
功能
- 会话列表:搜索、未读数、置顶、隐藏。
- 消息区:文本、图片、文件、交互卡片、系统提示、引用回复、Agent 的回复。
- 输入框:草稿、附件、
@提及、#引用工作项。 - WebSocket 实时更新,重连后自动补齐。
- 建群、群信息面板、名片、图片查看器、Agent 模型选择。
- 中英文、深色模式、窄屏布局。
- 宿主没提供的能力,对应按钮不显示。
组件已全部支持以上功能。直连 OpenMax 后端的宿主提供哪些可选能力(提及、名片、卡片操作、群管理等),见能力和已知限制 · 默认宿主。
组成
| 包 | 内容 |
|---|---|
@openmaxai/chat |
带样式的 React 组件(Tailwind CSS v4 + CSS 变量)和 ChatHost 类型 |
@openmaxai/chat-sdk |
构建 ChatHost 的现成方式:直连 OpenMax 后端的宿主,以及可与你的代码拼装的本地实现 |
组件不直接请求后端、不碰路由、不读写浏览器存储,所需的一切来自通过 Provider 装入的 ChatHost。宿主可选提供的功能叫能力,缺哪项,对应界面就不显示。分层见架构总览。
实验阶段
所有导出都标着
@experimental,预发布版本之间可能变动。这些包已作为3.0.0预发布版本发布到 npm,要锁定确切版本号,见安装。
