OpenMax
免费试用

介绍

OpenMax Chat SDK 是什么:一套让人和 Agent 在同一个会话里协作的聊天界面,适合谁用、从哪里开始。

介绍

一套带样式的 React 聊天界面:会话列表、消息区、输入框,会话里既有人也有 Agent。你提供一个宿主对象,负责取数据和发消息。

chat-app demo

演示截图。演示跑在内存里的示例 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,要锁定确切版本号,见安装。

下一步

  • 安装: 依赖、样式、打包器配置和 Provider。
  • 核心概念: 宿主、能力、会话与成员、消息、运行、交互卡片。
  • 快速开始: 不需要后端,五分钟跑起一个聊天。
  • 组件: 在线演示和 props。
  • 接入自有后端: 为你的数据写加载和发送函数,再接上 Agent 事件。