@ agentium/ 运输

HTTP和WebSocket运输层用于将Agentium剂作为API部署.

安装

npm install @agentium/transport

快速启动

import express from "express";
import { Agent, openai } from "@agentium/core";
import { createAgentRouter } from "@agentium/transport";

const app = express();
app.use(express.json());

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
});

app.use("/api", createAgentRouter({ security: { mode: "local" }, agents: { assistant: agent } }));
app.listen(3000);

特征

• 自动发现 - 从全球阅读 Registry 应请求时间; 服务器启动后创建的代理立即可用
• 快速路由器 ——REST API 有流支持和列表终点(GET /agents, (中文(简体) ), /teams, (中文(简体) ), /workflows, (中文(简体) ), /tools(中文(简体) )
• 袜子。 IO 网关 ——与动态代理/团队进行实时WebSocket通信查询并发现工具
• A2A 服务器 ——代理对代理协议支持
• CORS 限制费率( R) - 内置安全中间软件
• 斯瓦格语Name — 自动生成的 API 文档
• 文件上传 ——多段形式数据支持

文档

完整文件时间 参考文献. agentium.in

社区

加入对话 解析器。 。 。 .

许可证

麻省理工学院

经认证的 HTTP 主机

createAgentRouter 现在,每当 配置了JWT或RBAC. 范围检查本身并不设立会场、检查站或批准 所有权。 在路由器创建过程中, 认证配置缺少任意一钩 .

app.use("/api", createAgentRouter({
  agents: { assistant: agent },
  registry: false,
  jwt: { secret: process.env.JWT_SECRET! },
  rbac: {},
  security: {
    mode: "authenticated",
    resolveIdentity: (claims) => {
      const verified = claims as { sub?: string; tenant?: string };
      return verified.sub
        ? { userId: verified.sub, tenantId: verified.tenant }
        : null;
    },
    authorizeResource: async ({ identity, operation, resource }) => {
      // Application-owned implementation; use authoritative records and default-deny.
      // session:create must atomically bind this new ID before resolving true.
      return ownership.authorizeAndBind({ identity, operation, resource });
    },
  },
}));

这个 ownership 以上服务是应用程序依赖,而不是提供的内存存储. 它必须回来 false 用于未知或未移动的无主记录。 不推断所有权 或持有身份证。 全球存储会话ID 根据您的申请政策, 检查预定的演员和租户. 对于新的处决,路由器生成UUID并等待 session:create 坚持下去 其所有者绑定; 失败会阻止代理/团队/工作流程执行 。 提供的会话标识 需求 session:use 并且不能含蓄地声称已开庭或未开庭。 选中的 身份证明被退回 X-Agentium-Session-Id,包括流量请求.

主机认证中间软件在 middleware 运行于 JWT/ RBAC 之前,并可能含有 req.user 从证书上,它验证自己. resolveIdentity 只接收已核实的值. 认证对象 userId编号 :tenantId 如果提供,值必须与已解析的身份相匹配; 执行和校正处理器使用解析值。 多部分运行请求已执行 身份和所有权检查 分析他们的地盘,然后执行特工. 不要将未核实的请求复制到 req.user。 。 。 .

资源授权人接受这些业务:

不向仅需要每个项目的用户提供收款/管理员/调度管理业务 或限制目标访问; 使用专用主机端点,直到这些API提供更窄的 合同。 范围检查成功,包括 admin:*,绝不绕过资源授权. 这种钩子不会将基础存储器迁移到一个多租户的图案上.

非洲区域局现在明确涵盖核准、惩戒、检查站/回滚、时间表、衡量标准、, 工具列表、发现和嵌入式管理路径。 未知路径返回 403,包括 管理员,直到注册于 rbac.defaultScopes。明确的空范围数组意味着 "任何经认证的身份". rbac.agentScopes 在快速路由参数为 人口众多。 可选 rbac.publicRoutes,例如 ["GET /agents"]* 故意公开许可 清单或文件。 资源控制路线仍然需要核实身份/所有权. Swagger 路径需要明确的公共路径或 defaultScopes 启用 RBAC 时输入.

现在每个路由器都需要一个明确的 security 选项。 对于可信任的本地应用程序, 使用 security: { mode: "local" }。用于主机,选择 mode: "authenticated" 和提供两者 身份和资源授权钩。 选择未知模式失败 在发现前,中间软件设置,或可选的依赖性加载。 本地模式无法合并 与 JWT/RBAC; 配置从不默默地下调认证。 文本"苏克特". IO网关有以下明确合同. 独立的管理员路由器和A2A服务器保留自己的部署授权.

Team和Workflow HTTP路由在调用运行时间前执行会话所有权. 他们的内部代理人代表团现在执行租户/用户/经营家族、取消和执行政策。 自定义工作流程调用仍为可信任的主机代码;路由授权不 sandbox .

文本网关安全和连接所有权

createAgentGateway 还要求 security: { mode: "local" } 用于可信赖的本地用途. authMiddleware 需要认证模式; 它不能默默选择本地网关。 为主机Socket. IO, 中间软件验证证书并存储信任状态 socket.data。中间软件必须呼叫 next;同步抛出并返回承诺拒绝以通用错误拒绝访问. 进入等待任何返回的承诺 和解,重复 next 电话不能承认两次。 网关重新解析身份, 并给每次运行、 取消、 发现或工具查询的主机授权人打电话 :

createAgentGateway({
  io,
  registry: false,
  agents: { assistant: agent },
  authMiddleware: verifySocketCredentials, // host function populating socket.data
  security: {
    mode: "authenticated",
    resolveIdentity: (verifiedState) => identityFromVerifiedState(verifiedState),
    authorizeResource: ({ identity, operation, resource }) =>
      authorizeSocketResource(identity, operation, resource),
  },
  maxConcurrentRuns: 4,
  maxOutputBytes: 256 * 1024,
  textStream: { maxFrameBytes: 256 * 1024, maxBufferedBytes: 256 * 1024, writeTimeoutMs: 10_000 },
});

authorizeResource 必须准确返回 true 允许资源. execute 检查指定代理人、团队或工作流程. session:create 在返回之前,必须将服务器生成的不透明会话ID与已核实的演员/租户进行解剖绑定; session:use 必须拒绝身份不明、无所有或其他租户的身份证。 持有身份证没有授权 发现电话 discover 对于每个命名的代理、团队、工作流程或工具,并省略拒绝的条目. run:cancel 在网关检查后应用,该运行属于此套接字及其当前已核实的字符。 不得从客户房间或客户身份申请中获取此保单.

经认证运行的有效载荷拒绝 userId, (中文(简体) ), tenantId, (中文(简体) ), runId, (中文(简体) ), room 财务报告和审定财务报表 apiKey。手握键不以认证模式传输给提供者。 证书来自主机配置的运行时间/提供对象. 客户端 sessionId 仅是一个所有权检查的参考。 本地模式保留每个运行的 API 密钥; 生成新会话而不是使用 socket ID .

现有 agent.run, (中文(简体) ), team.run, (中文(简体) ), agent.chunk, (中文(简体) ), agent.tool.call, (中文(简体) ), agent.tool.done, (中文(简体) ), agent.done 财务报告和审定财务报表 agent.error 姓名不变. workflow.run 可用于通过 serve 或登记册。 每一个被允许的处决都收到一个生成 runId; 运行的事件包括 runId 在所有权约束之后, sessionId添加剂 agent.started 活动在运行时间工作开始前提供两个ID。 同时期客户端必须关联事件 runId发送 run.cancel 与 { runId };其确认为 cancellation_requested,而且只有在运行时间/清除器结算后才会出错终端.

普通文本 HTTP 和 socket 运行是连接拥有的 。 断接会中止它们的信号,启动传动器回放,并会防止延迟结果. Agent/Team SSE使用一个共享的写入器,等待节点排出后再拉出下块,将单个被编码的帧和队列的字节(默认情况下每个字节为256个KiB)相接,并应用了10秒排出期限. 套接字输出为串接每个连接,有相同的可配置边框和引擎. IO运输准备;最终收集的Agent文本有自己的字节盖. 缓慢或超大小的输出会取消生产;如果一个有界限的终端无法交付,连接就会关闭. 配置套接字 。 IO 服务器 maxHttpBufferSize,HTTP机身限制和部署连接/时间限制分别.

取消是合作的:任意主机回调不能被强制杀死,断开不会取消效果. 清理承诺得到遵守;没有公布最终成功,而自有工作尚未解决。 长期的任务观察者保留了他们单独的终身。 记忆 SSEEventLog 仅提供进程-局部重放,而不持续执行;多行字符串被编码为单独的SSE数据行并事件名称拒绝行注入.

多段上传已绑定的文件数/ 大小外加文本字段数/ 大小( M)maxFields: 32, (中文(简体) ), maxFieldSize: 64 KiB 默认值)。 即使在只使用本地固定装置时,也需要选择的补丁的Multer同位素;运输限制不会修复一个已安装的易碎剖器。 被中止和畸形的上传测试使用小的局部请求并坚持完成,限制和释放文件缓冲.

语音网关识别迁移

语音网关现在保留待连接,取消断开的设置,并绑定队列输出. Auth 中间软件在 socket.data.auth; 启用认证时, 客户端用户/ 会话/ 密钥覆盖被忽略 。 客户必须承认 voice.audio 序列号通过 voice.playback.ack,清晰重播 voice.clear发送 voice.playback.complete 只有在一代人玩过之后 默认为每帧256个KiB,1个MIB待产出,以及10秒确认期限. 缺少确认会终止会议,而不是增加缓冲。 见 语音指南 用于活动合同、格式谈判和回放确认的历史.

A2A 1.0和遗产移徙

安装可选选项 @a2a-js/sdk 对等点(用1.3.0测试). createA2AV1Server 使用A2A1.0 JSON-RPC和 /.well-known/agent-card.json· ; A2AV1Client 由核心导出。 年长者 createA2AServer 编号 : A2ARemoteAgent 仍可执行。 使用 createA2AServer 用于其服务器导出; 冗余服务器别名已删除。 客户也有明确的 A2ALegacyRemoteAgent 名称。 在迁移时分别挂起遗留的终点 .

import { createA2AV1Server } from "@agentium/transport";

await createA2AV1Server(app, {
  agents: { assistant },
  url: "https://agents.example/rpc",
  audience: "agentium-service",
  authenticate: async (request, audience) => {
    // Host verifier validates signature, issuer, expiry and this audience.
    const claims = await verifyAccessToken(request.headers.authorization, audience);
    return claims ? { tenantId: claims.tenantId, userId: claims.subject } : null;
  },
  maxTasks: 10_000,
  maxHistoryMessages: 128,
});

核实租户和演员自己的任务。 房客无法改变这种身份。 文字,结构化的JSON和PNG/JPEG/WebP生字节或HTTP(S)图像引用被接受. 内置图像 URL 应当使用原始字节部分; 本地路径和其他 URL 方案被拒绝 。 主办方仍负责其模型适配器中的远程媒体访问政策. 结构化的Agent结果成为了被打字的文物. completionState 将特定域结果映射到输入必需或认证必需的中断.

取消等待自有 Agent 工作在报告被取消前解决; 延迟成功无法覆盖它 。 不合作的召回可能会延迟承认. 接收任务前和在后置商店中执行能力,每个身份/会议都有固定的历史和一位活跃的作家。 耗尽拒绝新的工作;保留是程序本地的,在重新启动时重新设置,没有持久的收回要求.

客户端将具有证书的发现/请求限制在被配置的源头,拒绝重定向,并在共享发现的同时支持每个调用中止. 协议合规性测试不需要付费供应商。 遗留客户端在提早退出时推广取消并关闭 SSE 读取器; 遗留的流媒体服务器中止关于断开、 绑定出局缓冲和上限进程本地任务的工作 maxTasks。失败的代理输出仍然失败 。 遗留认证和任务所有者隔离仍然是主机中间软件的责任;使用1.0适配器进行内置可验证的所有权.

持久任务控制和事件重放

createDurableTaskRouter({supervisor, records, authenticate, authorize, wake}) 为已经确认的持久任务提供服务。 在应用程序拥有的前缀下挂载. 主管和记录事务部门必须共享 JournaledDurableTaskStore 举个例子 东道主认证用品租户/代理商身份,授权对每项申请重新核实现有赠款。 这些路径返回404,用于无法访问的任务,并保持输入,动作参数,内部故障文本和blob密钥的私密性.

• GET /:taskId 返回任务ID、状态、修订和更新时间戳.
• POST /:taskId/cancel 持续取消,然后引用主机唤醒回击。 它的202份答复报告了目前的状况和 deliveryPending 如果交货失败。 通过恢复主机重新唤醒;只有在对账/结算后才确认取消.
• GET /:taskId/events 返回一个带边框的 SSE 重放批次并关闭。 重新连接 Last-Event-ID;错误的光标返回400个,保留/未来-曲线间隙返回409个有保留界限. 重新连接时再次检查验证和政策 。 事件数据是针对自有角色的;在附加之前应用任何需要的内容编辑.

路由器是Agentium Control API,与被命名的A2A/MCP电线适配器相分离. 它并不声称,一个现有的进程本地协议服务器在挂起时会成为重新启动的安全性.

持久 A2A 和 MCP 任务桥梁

createDurableA2AV1Server 财务报告和审定财务报表 createDurableMCPTaskHandler 是选入适配器 而不是同一个耐用主管。 他们不使用普通的 A2A 服务器的处理本地任务存储 。 安装可选对等器 @a2a-js/sdk (测试时间: 1.3.0 (单位:千美元))和(或) @modelcontextprotocol/server (测试时间: 2.3.0 (单位:千美元)) (中文(简体) ). 构造动态加载只包含所选的 SDK;导入包不会连接到数据库或协议服务器.

两个适配器都需要一个 DurableProtocolHost数字 : supervisor, (中文(简体) ), admit, (中文(简体) ), authorize,以及 wake. 认证进一步核实明确受众的证明和回报 {tenantId, actorId}。每个任务查询都检查现场和当前主机政策. authorize 接收 read, (中文(简体) ), cancel, (中文(简体) ), input,或 wake; 缺失回调失败构建 。 礼宾元数据从来不提供身份、政策修订、赠款、清单或驾驶员登记.

import { DurableActionLedger } from "@agentium/core";
import {
  createDurableA2AV1Server,
  createDurableMCPTaskHandler,
  type DurableProtocolHost,
} from "@agentium/transport";

const host: DurableProtocolHost = {
  supervisor,
  async admit(identity, payload) {
    // Application service: validate current policy, select registered driver,
    // bind identity/manifest/input/budget/grant refs, and persist atomically.
    // For retries, deduplicate A2A messageId and any application idempotency key.
    return admission.persist(identity, payload);
  },
  authorize: (identity, task, operation) => policy.authorize(identity, task, operation),
  wake: (key) => durableQueue.wake(key),
  async respond(identity, task, response) {
    // Your human-consent service must reject automated/model-originated approval.
    await consent.verify(identity, task, response);
    await DurableActionLedger.decide(supervisor.store,
      { tenantId: identity.tenantId, taskId: task.id },
      { ...response, actorId: identity.actorId });
  },
  // Only public text/JSON leaves the host. Resolve artifact references with
  // DurableRunRecords and the same verified identity before projecting output.
  output: (identity, task) => publicResults.read(identity, task),
};

app.use(await createDurableA2AV1Server({
  ...host,
  name: "assistant",
  url: "https://agents.example/rpc",
  audience: "agentium-service",
  authenticate: (request, audience) => auth.verify(request.headers.authorization, audience),
}));

const mcp = await createDurableMCPTaskHandler({
  ...host,
  name: "assistant",
  audience: "agentium-service",
  authenticate: (request, audience) => auth.verify(request.headers.get("authorization"), audience),
  tools: [{ name: "research", inputSchema: {
    type: "object", properties: { query: { type: "string" } },
    required: ["query"], additionalProperties: false,
  } }],
});
// Mount mcp.fetch(request) using your runtime's web-standard Request/Response adapter.
// On shutdown: await mcp.close().

admission, (中文(简体) ), policy, (中文(简体) ), consent, (中文(简体) ), auth, (中文(简体) ), publicResults,以及 durableQueue 以上为主机服务,而非隐含的Agentium Globals. 在返回之前,必须坚持不懈 {tenantId, taskId}桥梁在回复和单独授权催眠前验证记录的所有人。 失败的队列交付不会抹去被认可的任务,批准决定,或取消意图;主机必须重试交付. 对于蒙戈支持的部署,使用耐用商店的多数/CAS适配器,而不是通用的 StorageDriver. 内幕商店保留其不可延长的能力旗.

A2A 支持 1.0 JSON-RPC(JSON-RPC) SendMessage, (中文(简体) ), GetTask,以及 CancelTask 包括文本/JSON输入和预测文本/JSON文物。 卡片广告 streaming: false 财务报告和审定财务报表 pushNotifications: false; 流出,订阅,任务上市,扩展卡,和推出配置被拒绝. 新的上下文ID来自录取. 现有任务输入为 JSON 的一部分 {approvalId, preparedHash, approved};它必须与未完成的持久批准相符。 默认屏蔽 SendMessage 等待终端状态/中断状态. configuration.returnImmediately: true 立即返回已承认的任务; 默认的 30秒等限会引发包含任务ID的协议错误, 将任务通过 GetTask。 。 。 . CancelTask 仅在主管确认后报告被取消; 暂停报告被取消是一个错误 GetTask 仍在与 metadata.cancellationRequested 直到确认.

MCP 支持 2026-07-28 (中文(简体) ) HTTP 框架和 io.modelcontextprotocol/tasks 扩展。SDK官方处理发现/工具列表和计划验证;此适配器执行 tools/call, (中文(简体) ), tasks/get, (中文(简体) ), tasks/update,以及 tasks/cancel。每个现代请求都必须有经过验证的协议信封,匹配协议/方法/名称头,以及任务能力。 缺少能力,不支持修改,不支持的方法,或者无效的论证在录取前被拒绝. 投票得到支持;任务通知/订阅,任务列表,遗留任务形状,以及遗留的HTTP会话没有. 已命名的普通/后继适配器保持不变.

人类待定决定地图 input_required 拥有稳定的批准身份证和准备的文摘。 MCP 输入回复使用 {[approvalId]: {action: "accept", content: {approved, preparedHash}}}; 拒绝/取消批准。 已回答或未知的密钥被忽略 respond 必须明确安装。 批准/拒绝投入,等待工人的皮卡返回。 MCP的取消承认其持续意图 resultType: "complete";投票仍在进行,直到取消。 完成的预测可能设定 isError: true 对于一个域/工具出错,而剩余的协议已完成。 内部执行失败只暴露出通用协议错误;存储的失败文本保持了隐私.

请求和预计任务有效载荷受限于64 KiB并有深度/节点限制. A2A消息最多接受32个部分;MCP最多曝光128个不同工具. 文件,原始介质,任意的文物URL,内部输入/动作参数,和blob密钥都从未自动被序列化. 较大的结果需要主机拥有的检索API. 东道方用品申请费率/货币限额和任务保留;MCP返回 ttlMs: null 因为这座桥没有过期 持久 SSE 事件重放由 createDurableTaskRouter,与这些投票协议终点分开.

对于MCP客户端恢复, MCPV2ToolProvider.exportTaskReference(handle, ctx) 为主机拥有的存储生成无证书的引用。 客户端重新启动后, resumeTask(reference, ctx) 验证提供者/端点和租户/用户/会话身份,根据当前证书获取远程任务,并返回新运行的本地新控件。 HTTP的任务和明确的租户/用户身份是必需的。 不将引用或批准控制披露为普通的模型工具.

本地的HTTP固定装置行使实际被绑定的SDK,所有权,谈判,批准摘要装订,取消,预计的文物,以及与现有适配器相容. 选入 AGENTIUM_DURABLE_MONGO_TEST=1 sixture创建了随机隔离的数据库,关闭了原来的商店,在新商店客户端之上再创建协议服务器,并验证批准/完成/取消读取. 这些是针对已实施方法的范围互操作性检查,而不是全面的协议认证、外部部署批准,或完全立即执行的保证.