@agent-assistant/core

@agent-assistant/core 是代理助理SDK的根组成包。 它定义了助理合同,创造了运行时间,向能力处理器发送了正常的入境信息,并通过注入的适配器发送出出行事件.

包是TypeScript-first,没有云假设,也不执行会话,表面,内存,路由,或产品逻辑. 这些关切将留在后面的一揽子方案中,并通过此处界定的抽象合同加以整合.

它拥有什么

• AssistantDefinition 助理身份、能力、钩子、运行时间限制和特征
• createAssistant() 以注入出入境适配器构建运行时间
• AssistantRuntime 生命周期方法: start(), (中文(简体) ), stop(), (中文(简体) ), dispatch(), (中文(简体) ), emit(), (中文(简体) ), register(), (中文(简体) ), get(),以及 status()
• 用钩子支持发送能力、超时处理和货币限制
• 外出目标 surfaceId 或通过抽象会话子系统扇出会话
• 储存、冻结和曝光 TraitsProvider 在运行时间定义上(储存和曝光——从不解释)

它不拥有的东西

• 中继传输、HTTP服务器、套接字或表面正常化
• 届会创建或届会生命周期规则
• 内存持续或检索
• 模式路线、政策执行或协调逻辑
• 特定产品的提示、工作流程或适配器

安装

npm install

从软件包目录 :

cd packages/core
npm install
npm test
npm run build

公共 API

import {
  AssistantDefinitionError,
  OutboundEventError,
  createAssistant,
  type AssistantDefinition,
  type InboundMessage,
  type OutboundEvent,
} from "@agent-assistant/core";

createAssistant(definition, adapters)

创建一个 AssistantRuntime 从一个有效的助手定义和两个注入适配器:

• inbound.onMessage(handler) 财务报告和审定财务报表 inbound.offMessage(handler) 将正常的输入信息连接到核心
• outbound.send(event) 发送有针对性的出境信息
• outbound.fanout(event, surfaceIds) 可选, 可用时用于会话扇出

运行时间创建于 created 状态。 打电话 start() 在发送消息之前.

运行时行为

生命周期

• start() 启动时为同位素
• stop() 停止后为同位素
• 无法重新启动已停止的运行时间
• status() 返回准备状态、启动时间、已登记的子系统、已登记的能力和飞行中处理器的计算

调度

• dispatch(message) 运行发送前 onMessage 钩子定义时
• 返回时 false 从 onMessage 不引用能力而丢弃信件
• 缺失的能力不会从 dispatch();它们通过报告 onError
• 能力故障和超时报告 onError
• 货币受下列因素的限制: constraints.maxConcurrentHandlers 和 FIFO 顺序的额外发送队列

释放

• emit({ surfaceId, text }) 执行目标发送
• emit({ sessionId, text }) 解决已注册的 sessions 子系统与粉丝出 attachedSurfaces
• emit() 掷出 OutboundEventError 当两个 surfaceId 也没有 sessionId 当前

Core保存会议摘要。 运行时间期望在字符串密钥下注册的子系统 sessions 用于:

runtime.register("sessions", {
  async getSession(sessionId: string) {
    return {
      attachedSurfaces: ["surface-a", "surface-b"],
    };
  },
});

或:

runtime.register("sessions", {
  async get(sessionId: string) {
    return {
      attachedSurfaces: ["surface-a", "surface-b"],
    };
  },
});

示例

import { createAssistant, type InboundMessage } from "@agent-assistant/core";

const runtime = createAssistant(
  {
    id: "assistant-1",
    name: "Example Assistant",
    capabilities: {
      reply: async (message: InboundMessage, context) => {
        context.log.info("handling inbound message");
        await context.runtime.emit({
          surfaceId: message.surfaceId,
          text: `Echo: ${message.text}`,
        });
      },
    },
  },
  {
    inbound: {
      onMessage(handler) {
        void handler;
      },
      offMessage(handler) {
        void handler;
      },
    },
    outbound: {
      async send(event) {
        console.log("send", event);
      },
    },
  },
);

await runtime.start();

特质

AssistantDefinition 接受可选选项 traits 类型字段 TraitsProvider 从 @agent-assistant/traits核心储存和在装配过程中冻结供应商。 它不读取、不分出或不解释任何特性值.

import { createTraitsProvider } from "@agent-assistant/traits";
import { createAssistant } from "@agent-assistant/core";

const runtime = createAssistant(
  {
    id: "sage-assistant",
    name: "Sage",
    traits: createTraitsProvider(
      { voice: "concise", formality: "professional", proactivity: "medium", riskPosture: "moderate" },
      { preferMarkdown: true, preferredResponseLength: 800 },
    ),
    capabilities: {
      reply: async (message, context) => {
        // Capability handlers access traits as read-only data
        const voice = context.runtime.definition.traits?.traits.voice;
        const preferMarkdown = context.runtime.definition.traits?.surfaceFormatting?.preferMarkdown;
        // Surface formatting decisions live here — not in core
        void voice; void preferMarkdown;
      },
    },
  },
  adapters,
);

traits 是可选的。 现有没有特征的定义不作修改.

@agent-assistant/traits 是同级依赖。 不使用特质的消费者不需要安装.

发展

• npm test 运行WF-1、WF-2、WF-4和WF-5核心工作流程的孤立Vitest套件
• npm run build 发射 dist/ 声明和 Java 脚本通过 tsc

核心( P)