@dbx-工具/团队

在 AppKit 或 Mastra 后端添加一个 Microsoft Teams 机器人端点, 或者转出 模式响应为预览或频道帖子的可调取卡。 浏览器安全 纸牌计划 @dbx-tools/ 共享团队和反应渲染器 adaptivecards JavaScript 渲染器) 生活于 @dbx-tools/ui-teams (英语)。 。 。 .

快开始

登记小组的终点,并向一名代理人提供卡片工具:

import { createApp, server } from "@databricks/appkit";
import { agents, mastra } from "@dbx-tools/appkit-mastra";
import { teams } from "@dbx-tools/teams";

const support = agents.createAgent({
  instructions: "Return Teams cards for deployment summaries.",
  async tools(plugins) {
    return { ...(await plugins.teams.toolkit()) };
  },
});

await createApp({ plugins: [server(), teams(), mastra({ agents: { support } })] });

登记还补充:

• 解析配置的 AppKit 插件注册,记录有效的卡 版本和webhook状态在启动时,并挂载了卡-建/卡-站路由.
• 两个代理浮出水面: AppKit teams.createCard 工具与独立的 Mastra create_teams_card 工厂,两个都拿走小 CardSpec 词汇. 每个插件实例保持其卡配置,webhook,以及执行器的分离.
• 编辑一个 CardSpec (标题、字幕、文本、, 关键/价值事实,将动作链接到有效的可调适卡1.5文档中.
• 可选地张贴到 Teams 即将到来的 Webhook 中, 包裹在附件中 包含重试执行政策 .
• POST /api/teams/messages - 微软团队发送信息端点: URL 您粘贴到 Azure 瓶注册中, 以便团队频道可以聊天 你的探员 它验证了Bot Service JWT(签名、发行人和 与你的机器人的应用代号相当 立即承认并交付 该代理卡在Bot Framework Connector API上。 这是 团队形状的模拟 Mastra 插件如何在路径中曝光 MCP - the 协议是接口.
• POST /api/teams/activity - 同一回合,与答复同步运行 反应机构的活动。 不需要机器人注册,所以这就是 本地客户端,测试,或任何非团队的呼叫器使用. 对话 id 地图 在代理的内存线上,所以重复转动继续一个对话.
• POST /api/teams/card 运行浏览器 dev 页面帖以获取活卡 预览,和 POST /api/teams/post 推出一张卡片到网路上.

配置团队交付

import { createApp, server } from "@databricks/appkit";
import { teams } from "@dbx-tools/teams";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const support = agents.createAgent({
  instructions: "Summarize results as Teams cards when asked.",
  async tools(plugins) {
    return { ...(await plugins.teams.toolkit()) };
  },
});

await createApp({
  plugins: [
    server(),
    teams({ webhookUrl: process.env.TEAMS_WEBHOOK_URL }),
    mastra({ agents: support, storage: true }),
  ],
});

plugin.teams() 解析对实例拥有的运行时间的配置,记录 有效的卡片版本, 以及是否连接了网页, 并挂载构建 / 员额路线 /api/teams应用整合剂应消耗其原生物 如上所示,保留自有插件的 AppKit 执行链. 这个 teams.createCard 工具可以自动继承,因为建卡没有 副作用.

交汇牌

curl -X POST http://localhost:8000/api/teams/activity \
  -H 'content-type: application/json' \
  -d '{
        "activity": {
          "type": "message",
          "text": "did the deploy land?",
          "from": { "id": "user-1", "name": "Reggie" },
          "conversation": { "id": "conv-1" }
        }
      }'

答复是 { "activities": [...] },每项活动 attachments[].contentType === "application/vnd.microsoft.card.adaptive" 带有 编辑适应卡 content - 一个团队的客户端.

转出两圈:

1. 答问. 经纪人通常会回答问题 - 工具可用,没有 structuredOutput中,没有卡片.
2. 形式. 一秒钟 structuredOutput 将重构的答案传递到 CardSpec,由构建者编译.

回答首先保留了普通工具的使用. 第二次通行证更改介绍 而不改变答案。 特工们留下来 create_teams_card 反之则 方向:在聊天端点上以散文方式回答,选择附加卡. 当代理在第一次通过时, 规格获胜 格式传出被跳过.

因为这个计划是迅速注入的,而不是强制提供商的(Databricks) 服务模式拒绝 response_format 并行 tools,格式通过是 最好的,所以答案被分层回收: 解析的光谱,一个全 适应卡文档重新读入 spec 词汇表( 多么能用的模型) 通常在要求“适应卡”时返回,有效载荷 Mastra 已拒绝 jSON嵌入了流言,然后流言本身。 格式化 错过成本结构,永远不要回答.

主机嵌入标记( E)[data:<id>], (中文(简体) ), [chart:<id>])从答案中剥去: 聊天UI将那些交换成一个已渲染的表格或图表,但卡片没有这样的插槽, 所以一个标记会变成文字 [data:01f1...] 数字属于哪里。 这个 回答密码则询问代理商本身的值.

代理由兄弟会 Mastra 插件按注册名称解决 (单位:千美元)agentPlugin默认值 mastra),因此,这个包保持了叶子加成并带走 不依赖 @dbx-tools/appkit-mastra。通过 agentId 在身体中选择一个 特定特工 少管闲事 未挂载的代理插件答覆 503, 一个未知 agentId 请回答404.

同样的搜索会获取插件的 createRequestContext(),用于构建 每回转 Mastra RequestContext 转弯通过两通 需要这样 与聊天对等: 用户范围的工具读取 AppKit 用户的上下文, 所以 没有它 ask_genie 在聊天时回答“数据源无法到达” 路线用真实的数字回答。 一个没有工厂服务的供应商 转动时没有用户范围的工具.

不及时的活动 - a typing 指标,a conversationUpdate 当有人加入时, 一个空消息 - 回答 { "activities": [] } 而不是说 错误, 这符合标准的机器人行为 .

@dbx-tools/ui-teams (英语)是因为 TeamsChat 是匹配的客户端.

直接建出一张牌

import { builder } from "@dbx-tools/teams";

const { card } = builder.buildCardResult({
  title: "Deployment succeeded",
  subtitle: "prod • 2m ago",
  facts: [{ title: "Version", value: "1.4.2" }],
  actions: [{ title: "View run", url: "https://example.com/runs/42" }],
});
// `card` is a full Adaptive Card document; render it with @dbx-tools/ui-teams
// or post it with the plugin's `postCard` export.

对于独立的 Mastra 工具,直接提供配置或共享明确 跨工厂运行时间 :

import { runtime, tool } from "@dbx-tools/teams";

const teamsRuntime = runtime.createTeamsRuntime({ cardVersion: "1.5" });
const createTeamsCard = tool.teamsCardTool({ runtime: teamsRuntime });

明确传递运行时间或提供执行器给 createTeamsRuntime。 。 。 .

使用 AppKit

AppKit 没有“团队”或“适应卡”表面,所以当一个 特工应该发出团队卡。 政策层限制卡片形状: 模型使用一个安全的小词汇(CardSpec)而不是原始适应性 Card JSON, 构建者保证一个有计划有效的适应性卡 1.5文档,以及 张贴在明确配置的接通的网页上。 这个包 遵循相同的添加形状 @dbx-tools/电子邮件。 。 。 .

建卡是只读的变换,不需要审批. 张贴 改为 /api/teams/post 是一种外在的副作用,但它没有被曝光为一种 代理工具 。 显示该路线拥有呼叫者授权的应用程序 以及任何批准步骤。 团队对话使用的工具 代理审批政策.

配置

每个字段优先:明确的插件配置胜出,然后匹配 环境变量.

• cardVersion 编号 : TEAMS_CARD_VERSION - 适应卡方案 建造目标。 默认为 1.5 (团队支持的内容).
• webhookUrl 编号 : TEAMS_WEBHOOK_URL - 可选的团队来取网页 URL。 何时 未设置, 发布已禁用, 插件只为 UI 构建卡片 调制。 一个不是绝对 HTTPS URL 的值失败了配置解析 .
• agentPlugin 编号 : TEAMS_AGENT_PLUGIN - 兄弟姐妹插件的注册名称 他的探员会回答话题 默认为 mastra。设定当 Mastra 插件挂载在一个 config.name 超过.
• appId 编号 : TEAMS_APP_ID (别名) MICROSOFT_APP_ID- Entra应用程序(客户端) 从你的Azure瓶注册。 要求于 POST /messages 接受 观众必须携带入境证.
• appPassword 编号 : TEAMS_APP_PASSWORD (别名) MICROSOFT_APP_PASSWORD) - 客户端 用于获取出界的连接符.
• appTenantId 编号 : TEAMS_APP_TENANT_ID (别名) MICROSOFT_APP_TENANT_ID- 设置 只有一个租户的机器人 留作多租户.
• allowUnauthenticated 编号 : TEAMS_ALLOW_UNAUTHENTICATED - 服务 /messages 在 HTTP 回复中回答而不是通过 连接器 API. 仅供地方发展之用,除非 NODE_ENV 实值 development因此,一个生产建筑不能被一个 环境变量。 见"连接一个真正的Teams频道".

这个 MICROSOFT_APP_* 别名是 Bot 框架 SDK 和 Azure 的名称 传送门已经使用,所以一个已有的bot的环境没有变化地下降.

连接真实的团队频道

1. 创建一个 阿苏尔瓶 资源及说明 微软App ID创建 客户的秘密.
2. 设定其 消息端点 到应用程序主机+ /api/teams/messages。 。 。 .
3. 启用 微软团队 机器人频道.
4. 给应用程序 TEAMS_APP_ID 财务报告和审定财务报表 TEAMS_APP_PASSWORD (单位:千美元) TEAMS_APP_TENANT_ID 登记单租户.
5. 在 Teams 中安装 Teams 中的 bot , 并使用 Teams 的 app 显示引用同一应用程序 身份证明,并传达它。 代理在"适应卡"中回答.

每个入境请求的终点是:

• 验证 JWT 反 Bot 框架 JWKS, 需要信任 发行人和听众人数等于 appId观众检查是 事项:为另一个机器人签发的Bot Services由 同样的钥匙,所以没有它 谁有自己的机器人可以驱动你的经纪人.
• 将回复的目的地绑到符上. serviceUrl 抵达 请求身体,而答复 携带你的机器人的证书, 所以它只是荣誉 当它与已核实的代号相符时 serviceurl 索赔.
• 答复 200 在运行代理之前. 瓶子服务时间流出 a 未经承认的活动在几秒钟内再试一次,而卡片需要更长的时间 因此,同步回复将产生重复的卡片。 输入 指示符显示代理工作期间,卡片通过 准备时连接器 API .

用于未注册的地方发展 allowUnauthenticated: true (与 NODE_ENV=development和 /messages hTTP 回复中的答案, 即时充值演示如何制作活卡.

路线

在插件基础路径下挂载 /api/teams数字 :

• POST /messages - 工作队传递终点信息(见上文)。 躯体是赤裸的瓶子 框架活动. 401 在一个不能证实的符号上, 503 否时 appId编号 :appPassword 已配置, 400 无效活动或 serviceUrl 与符号不符 答复 200 以一空相为体. 答复通过连接器API到达.
• POST /activity - 运行一个对话转弯。 身体为 { activity, agentId?, model? }。答复是 { activities },每个 携带可适应卡附件. 400 无效的活动, 404 一个 不详 agentId, (中文(简体) ), 503 当没有代理插件注册时.
• POST /card - 汇编 CardSpec 请求正文进入可适应卡 文档。 dev 显示页帖在此预览卡片直播.
• POST /post - 编译然后推出 CardSpec 到已配置的团队 即将来临的网游。 回返 400 当身体无效时,当没有时,错误 已配置了 webhook .

模块

• plugin - 说吧 teams (插件厂)和 TeamsPlugin。 。 。 .
• tool - 说吧 teamsCardTool 财务报告和审定财务报表 CREATE_CARD_DESCRIPTION。 。 。 .
• builder - 说吧 buildAdaptiveCard 编号 : buildCardResult (纯) CardSpec - > 卡片 页:1.
• conversation - 说吧 runCardTurn (一项活动,卡片活动退出), resolveCardAgent, (中文(简体) ), promptOf, (中文(简体) ), toReplyActivity, (中文(简体) ), CARD_TURN_INSTRUCTIONS, (中文(简体) ), 编辑 CardAgentLike 编号 : AgentProviderLike 形状.
• auth - 说吧 verifyBotToken (输入Bot Service JWT验证), connectorToken (外部客户证书), isAllowedServiceUrl, (中文(简体) ), 财务报告和审定财务报表 resetTeamsAuth。 。 。 .
• connector - 说吧 sendActivity 编号 : sendTyping,瓶子框架连接器 API 答复通过电话.
• messaging - 说吧 deliverTurn (当时的承认)和 resolveServiceUrl。 。 。 .
• runtime - 说吧 createTeamsRuntime, (中文(简体) ), buildCardWithRuntime, (中文(简体) ), postCardWithRuntime独立 buildCard 编号 : postCard。 。 。 .
• config - 说吧 resolveTeamsConfig, (中文(简体) ), TEAMS_CONFIG_SCHEMA,内存名称 常数,以及 TeamsPluginConfig 编号 : ResolvedTeamsConfig 类型.
• defaults - 拦截器执行设置和命名盖.