@ astralbeam/ sdk (英语)

在您的网络应用程序中嵌入代理聊天边栏或只读的租户目录, 或者用无头核心构建自己的聊天 UI 。 部件用阴影根孤立其风格.

npm install @astralbeam/sdk

快开始

React中的一个组件,一个功能在其它任何地方. 完整的设置,包括所需的符号端点,在 开始。 。 。 .

import { AstralBeamChat } from "@astralbeam/sdk/react"

export function Sidebar() {
  return (
    <aside style={{ height: "100dvh" }}>
      <AstralBeamChat />
    </aside>
  )
}

import { mountAstralBeamChat } from "@astralbeam/sdk/client"

const handle = mountAstralBeamChat(document.getElementById("sidebar")!, {})
// Update with handle.update({ colorScheme: "dark" }), then clean up with handle.unmount().

没有 npm 或 捆绑器, 请从 jsDelivr 从模块脚本中导入相同的条目 。 精确的版本和全文 /dist/client.js 路径,因为加载器导入了相对自身的懒散块. 见 脚本标签。 。 。 .

<div id="sidebar" style="height:100dvh"></div>
<script type="module">
  import { mountAstralBeamChat } from "https://cdn.jsdelivr.net/npm/@astralbeam/[email protected]/dist/client.js"

  mountAstralBeamChat(document.getElementById("sidebar"), {})
</script>

• 聊天横向调整大小并填充其母高. 你们应当高一些min-h-0 宽度.
• 聊天默认使用主机云. 托肯斯来自您的申请。 自我接待,设定 apiUrl 您的部署 /api 基础.
• @astralbeam/sdk/client 没有反应 聊天内容是一个懒散的块,有它自己的捆绑副本.
• 没有运行时间依赖 . react 财务报告和审定财务报表 react-dom 是可选对等器,仅由 @astralbeam/sdk/react。 。 。 .
• 把它挂到路由器上 如果记录稿能活下来的话.

认证

您的服务器在部件可以聊天前必须认证主机会话并刻出聊天符 。 只保留 API 密钥服务器 。 见 认证。 。 。 .

替换 getApplicationSession 下面是您的应用程序认证的会话查询。 返回当前用户及其经核实的客户账户成员身份 session.user 财务报告和审定财务报表 session.tenant。 。 。 .

import { createAstralBeamToken } from "@astralbeam/sdk/server"

const apiKey = process.env.ASTRALBEAM_API_KEY // key_<organizationId>_<id>_abo_<secret>

export async function POST(request: Request) {
  const headers = { "Cache-Control": "no-store" }
  if (!apiKey) return Response.json({ error: "Not configured" }, { status: 503, headers })
  const session = await getApplicationSession(request)
  if (!session) return Response.json({ error: "Unauthenticated" }, { status: 401, headers })
  try {
    const token = await createAstralBeamToken({
      apiKey,
      user: {
        id: session.user.id,
        name: session.user.name,
        metadata: { email: session.user.email },
      },
      tenant: {
        id: session.tenant.id,
        name: session.tenant.name,
        metadata: { plan: session.tenant.plan },
      },
    })
    return Response.json({ token }, { headers })
  } catch {
    return Response.json({ error: "Token could not be issued" }, { status: 500, headers })
  }
}

• 认证一次并获得稳定 user.id 财务报告和审定财务报表 tenant.id 来自该信任会话的值.
• 只保留 API 密钥服务器 。 托肯斯是签名的,而不是加密的,所以他们的诉求必须包含任何秘密.
• 返回时 Cache-Control: no-store 当配置或认证缺失时,则关闭失败.
• 目录访问额外需要签名 user.admin: true,并坚持记录。 跟随 租户目录。 。 。 .
• 租户管理,使用 createAstralBeamOrganizationToken编辑 API 客户端指南 涵盖数据库支持的角色和浏览器集成.

在获得一个符号后, 组件调用 POST /api/v1/me 并在期满前续约。 见 认证和刷新行为。 。 。 .

选项

通过选项作为回放道具或应用子集 handle.update(options)。演示文稿更改保留聊天。 变化 threadId 选择对话,并更改 apiUrl 清除之前部署的状态。 见 配置 用于所有选项、默认、布局和铬槽.

大多数嵌入器都让 <AstralBeamChat {...options} /> 管理会话。 对于外部控制,创建 chat 与 useAstralBeamChat(options) 提供 <AstralBeamChat chat={chat} />。在钩上配置认证和工具,在视图上配置部件和外观。 直接调用动作 chat 读取状态 chat.getState()。 。 。 .

对话会自动被保存,然后从私人开始。 部件搜索保存了对话标题 。 重新打开历史不执行较早的工具调用 。 断接可以中断当前响应.

无头会话暴露出对话的导航,搜索,和相扑. 与 useAstralBeamChat,通过 chat,例如 chat.openThread(threadId)。历史一次加载一页. reset() 启动新聊天并保留保存的聊天.

下载附件 chat.getThreadAttachment({ threadId, fileId })时返回 a Blob组织和参与者租户范围来自您的全权证书。 行政下载也通过 tenantId启用 { preview: true } 作为缩略语的第二个论据。 只有未发送的上传预览可以省略 threadId。 。 。 .

默认, threadId: "auto" 使用会话存储重新装入后恢复此标签的选择, 范围为当前账户, API, 以及 placementKey ?? agentId ?? "default"。在与同一代理进行独立聊天时,使用不同的定位键。 一个新的独立打开的标签开始一个新的聊天. 使用 threadId: "new" 以绕过恢复,或通过已保存的线程 UUID。 部件保存未发送的文本, 并在本地存储、 账户、 API 和对话中上传文件引用 。 重新打开恢复了草稿而不自动发送. 主机拥有侧边栏能见度,可以在会话存储中单独坚持.

工具和部件

一个工具做一些事情:它 execute 运行在您的页面。 一个部件显示一些东西:它的 render 让你的UI进入对话。 双方均宣布 description (单位:千美元) parameters 计划 见 工具和部件。 。 。 .

tools: {
  restart_service: {
    metadata: { title: "Restart a service" },
    description: "Restart one of the host app's services by name",
    parameters: { type: "object", properties: { service: { type: "string" } }, required: ["service"] },
    execute: async ({ service }) => await restartService(String(service)),
  },
},
widgets: {
  systemStatus: {
    description: "Shows the current status of the host app's systems",
    parameters: { type: "object", properties: { degraded: { type: "boolean" } } },
    render: ({ degraded }) => <StatusCard degraded={Boolean(degraded)} />,
  },
}

• 斯克马斯是普通的JSON斯克马或任何 标准Schema 验证符(Zod, Valibot, ArkType).
• 只有标准Schema验证浏览器中的输入. 与平原JSON Schema,将输入视为不信任.
• 从工具返回纯 JSON 值, 无 undefined 字段。 如果无法发送结果,行动可能仍然发生.

MCP 连接

远程工具出现在 MCP 连接 在经过认证的租户部件中。 组织管理员配置可用的MCP服务器. 每个租户用户都会建立自己与服务器的连接. 支持公共端点,静态头和OAuth. 工具结果遵循了对话的能见度和保留规则. 断开连接从 AstralBeam 中删除已保存的连接及其证书 .

无头消费者可以使用 chat.getMcpCatalog(), (中文(简体) ), chat.manageMcpConnection(operation) 财务报告和审定财务报表 chat.authorizeMcpConnection({ mcpServerId, id? })。从用户手势开始 OAuth 打开弹出。 浏览器绑定并补全使用经认证的会话 。 服务器工具标题到达 state.serverToolTitles,独立于主机工具执行.

重用仪表盘的服务器列表和格式 AstralBeamMcpServers 从 /react 或者说 mountAstralBeamMcpServers 从 /client。提供服务器列表和授权的回信。 见 MCP 服务器管理。 。 。 .

文档

入境点

仅可阅读的租户、租户用户和谈话部件来自 /client 财务报告和审定财务报表 /react。见 租户目录 用于设置和嵌入示例.

反应目录 refs 曝光 refresh() 财务报告和审定财务报表 reset(),两个返回 Promise<void>。使用道具进行更新和有条件的渲染以卸载。 香草手柄也暴露出来 update() 财务报告和审定财务报表 unmount()。在退出或身份更改时卸载。 见 生命周期合同 用于认证、缓存、再挂载再利用和动作完成.

没有根导出 .

每个类型Script模块解析模式下的类型解析,包括经典 "moduleResolution": "node"。要求类型脚本 5.0 或稍后,因为声明使用 const 类型参数,无法解析 TypeScript 4.x.

实例

examples/linearity-react 是一个 TanStack Start和shadcn/ui 项目跟踪器,有两个工作空间,局部Storage 坚持性,以及一个名叫Astro的助手. 它展示了经验证的工具、现场发行卡、房客换乘以及托管游乐场的基本Auth门.

examples/todos 嵌入侧边栏和一个租户范围用户在最小的 TanStack Start app 上市. 两者都使用相同的演示符号路由. 该应用程序还显示主机工具大于活的React状态和 a todoCard 部件,没有自带的尾风或阴影/ ui .

examples/todos-rails 是铁路8号的Ruby的同名应用软件. 它通过导入地图从jsDelivr装入SDK,从平版ES模块装入它,薄荷符与 jwt 并给代理工具 通过应用程序的JSON API.

许可证

麻省理工学院