@agent-assistant/surfaces

@agent-assistant/surfaces 为Agent Ass助理SDK提供助发表层. 它拥有地表注册,入站正常化,出站调度,格式化钩子,多地表扇出. 它不执行运输协议或产品特定的表面逻辑.

责任

• 注册和跟踪 SurfaceConnection 记录
• 暴露出一个符合下列条件的单一登记册: @agent-assistant/core
• 正常的原始入境有效载荷进入结构 InboundMessage 形状核心预期
• 向一地平面发送外出事件, 或者在会话相接的地平面上扇出它们
• 在交付前应用可选的地表格式钩

非目标

• hTTP、 WebSocket、 Slack Events 或桌面 IPC 等运输执行
• 认证、网路验证或供应商SDK关切
• 产品特定格式化公约或UI行为
• 缓冲、重试或下线队列

安装

npm install @agent-assistant/surfaces

核心概念

SurfaceConnection 描述一个已注册的地表,包括其适配器、能力和当前状态.

SurfaceAdapter 通过产品代码或运输软件包实施。 适配器只负责连接状态回调和最终有效载荷的交付.

createSurfaceRegistry() 返回一个作用为:

• 表面登记册
• 核心进入适配器
• 核心外出适配器

这使得产品将一个注册实例接入运行时间和接力传输层.

使用量

import { createAssistant } from '@agent-assistant/core';
import { createSurfaceRegistry } from '@agent-assistant/surfaces';

const surfaces = createSurfaceRegistry();

const runtime = createAssistant(
  {
    id: 'assistant-1',
    name: 'Assistant',
    capabilities: {
      chat: async (message, context) => {
        await context.runtime.emit({
          surfaceId: message.surfaceId,
          text: `echo:${message.text}`,
        });
      },
    },
  },
  {
    inbound: surfaces,
    outbound: surfaces,
  },
);

登记表面

surfaces.register({
  id: 'web-primary',
  type: 'web',
  state: 'registered',
  capabilities: {
    markdown: true,
    richBlocks: false,
    attachments: false,
    streaming: false,
    maxResponseLength: 0,
  },
  adapter: {
    async send(payload) {
      // Deliver payload to your transport layer.
    },
    onConnect(callback) {
      // Store and call when the transport becomes active.
    },
    onDisconnect(callback) {
      // Store and call when the transport becomes inactive.
    },
  },
});

当适配器报告连接或断开事件时,登记册会更新 connection.state 已经就位.

流入流量

中继发源代码将原始事件推入登记册:

surfaces.receiveRaw('web-primary', {
  messageId: 'msg-1',
  userId: 'user-1',
  text: 'hello',
  capability: 'chat',
});

默认常态提取 :

• id 从 messageId 或者说 id,否则生成UUID
• sessionId 从 sessionId 或者说 session.id
• userId 从 userId, (中文(简体) ), user.id,或 user 当它是一个字符串
• workspaceId 从 workspaceId 或者说 workspace.id
• text 从 text, (中文(简体) ), content,或 body
• receivedAt 从 timestamp 或者说 receivedAt,否则当前时间
• capability 从 capability 或者说 type,否则 'chat'

若为 userId 丢失, 信件被丢弃, 错误被记录。 如果文本缺失, 则使用空字符串并记录警告 .

带有非标准接力有效载荷的产品可以将默认正常化逻辑替换为: normalizationHook。 。 。 .

外出交货

目标交付用途 send(event) 和要求 event.surfaceId。 。 。 .

await surfaces.send({
  surfaceId: 'web-primary',
  text: 'Hello from the assistant',
});

如果连接有 formatHook,钩子接收出局事件和地表能力,并可以返回任何地表特定格式结构. 没有钩子,适配器接收 event.text 作为格式化的输出.

适配器失败被包裹 SurfaceDeliveryError。 。 。 .

虚构

当核心将一个会话解决成一组附着的表面ID时,登记册可以向所有它们交付:

const result = await surfaces.fanout(
  {
    sessionId: 'session-1',
    text: 'This reaches every attached surface',
  },
  ['web-primary', 'desktop-1'],
);

幻想行为 :

• 默认同时发送
• 跳过未知的表面
• 默认跳过不活动表面
• 可以在第一次失败时继续收集失败或中止
• 返回 a FanoutResult 具有地表结果的

可配置默认扇出行为 defaultFanoutPolicy。 。 。 .

软件包边界

此套件为TypeScript-first,运行时光,没有云假设. 它不依赖于特定的运输堆栈,在运行时不导入会话逻辑,也不包含中继运输执行.

发展

npm test
npm run build

生平图 插图 缩图