将 Beeuni 用作产品的智能体后端

使用 Beeuni API 或 TypeScript SDK，从应用程序创建智能体会话。产品负责界面及其用户；Beeuni 负责运行智能体工具并返回消息和文件。

设想一个比较供应商的采购工具。用户选择产品和获准的供应商；智能体访问供应商公开的目录页面，从已连接的文档服务读取价目表，并生成比较表。应用程序负责登录和审核，而 Beeuni 会话负责收集资料并进行比较。

定义界面要提交的任务

列出输入内容、允许执行的操作、输出格式和失败情况。对于目录示例，提供获准访问的供应商页面、已连接目录文档的引用，以及要比较的字段。要求每种产品占一行，并列出报价和币种，以及来源引用。缺少的尺寸应标记为未知。任务不得下单。

• 应用程序职责：验证用户身份，决定谁可以访问每项任务，验证输入，并展示结果。
• 项目配置：选择完成此类工作所需的智能体、模型、技能和已授权工具。
• 会话工作：提交请求、跟踪进度，并检查返回的消息和输出文件。

向会话提供所需来源的访问权限

使用任务所需的浏览器和连接器工具配置项目。对于私有文档服务，连接一个帐户，并授予智能体访问相关连接器的权限。请求中的链接本身不会授予访问权限。所选帐户和允许访问的来源应与提交任务的客户保持一致；连接器指南说明了帐户访问权限。

随后，智能体便可通过这些工具读取所选文档、访问公开的产品页面，并编写脚本来核对产品代码和包装规格。要求它在结果中保存读取的值、来源位置和读取时间。如果目录无法读取，或页面要求再次登录，应将这一问题反馈给界面，而不是编造价格。

将凭据保留在服务器上

SDK 指南介绍了如何安装 @beeuni/sdk、创建客户端并验证请求。将 API 密钥保存在服务器上，不要放进浏览器代码。

决定每位客户可以访问哪些 Beeuni 项目。必要时将客户的文件和已连接帐户彼此隔离，并在服务器上检查访问权限后再转发请求。身份验证指南介绍了可用的登录方式。

显示进度并处理重新连接

SDK 支持创建会话、等待就绪并发送请求。完整示例介绍了如何接收事件和读取回复。使用这些事件展示实际进度。“正在打开供应商页面”“正在比较产品”和“结果已就绪”都应对应可观察到的工作或状态。

在应用程序中为每次比较创建一条任务记录。保存所选来源的引用、请求的列、Beeuni 项目和会话 ID，并在输出位置可用时保存该位置。这条记录可将审核页面关联到已在进行的工作。

Application task record — illustrative fields, not an SDK payload
app_task_id
approved_source_references
requested_columns
beeuni_project_id
beeuni_session_id
output_reference
review_status

假设用户选择了三个供应商目录，随后刷新页面。刷新后的界面会查找应用程序任务及其现有的 Beeuni 会话。它读取已保存的进度，并继续跟踪该任务。每次加载页面都创建新会话会导致任务重复。

服务器在收到请求已提交的确认之前，连接也可能中断。这种结果是不确定的，并不能证明请求没有生效。再次发送请求前，先检查会话。如果仍无法确定请求是否已被接受，应向用户说明这种不确定性，而不是自动启动另一次比较。

在应用程序中检查结果

对于目录比较，应检查必需的列、文件是否可读、来源引用，以及无法匹配的产品。包装规格不同是常见的陷阱：一盒十二件的价格不能直接与单件价格比较。保留报价金额和计价单位；只有在来源支持换算时，才添加标准化价格。

审核页面应允许用户打开某项价格的来源，并查看尚未解决的匹配问题。文件可能已经就绪，但仍有部分行需要审核；应在应用程序中将这两种状态分开。

让用户能够修正结果，同时保留上下文

假设两家供应商用不同名称销售同一把椅子。智能体将它们作为不同产品处理，而审核人员发现了两者之间的对应关系。有效的修正应包含这两个来源行及预期关系：“将这两项视为同一产品进行比较，但分别保留报价中的表面处理和包装规格。”只发送“重试”会让智能体猜测问题出在哪里。

将修正记录在相应任务旁边，并保留先前的输出。新结果可能修正了产品匹配，却改变了另一行。展示修订后的比较结果及其上一版本，方便审核人员同时检查。确定下载按钮提供哪个修订版本，并记录哪个版本获得了批准。

审批可能会将比较结果发布到内部采购页面。向供应商发送订单则是另一项操作，需要单独的权限和确认。在授予智能体采购工具的访问权限之前，应在应用程序中明确这条界限。完成电子表格不应自动触发下单。

确定单个请求可以启动多少工作

设置实际可行的提交上限，例如目录数量和单次请求允许的工作量。比较三份简短价目表与核对整套产品档案截然不同。开始前显示已接受的范围，让用户可以缩小请求范围或选择后台任务。

如有可用信息，应从平台读取用量和费用信息，而不是根据消息长度计算最终账单。如果产品需要严格的支出上限或取消保证，应确认集成如何执行这些要求。仅有倒计时或“停止”按钮，并不能证明工作和费用已经停止。

使用可手动核验的案例测试集成

准备一小组目录，并为每份目录确定预期解释：格式清晰的价目表、无法读取的扫描件、两种币种、相互冲突的包装规格，以及没有明确匹配项的产品。每次更改模型、指令或项目配置时都使用这组目录。比较生成的行和来源引用，也要检查智能体留下了哪些未解决的问题。

还要在任务运行时离开页面，之后再返回，并在结果出现后提交修正。检查下载的是哪个输出，以及另一位已登录用户是否能访问该任务。即使目录解读正确，应用程序也可能显示了错误的修订版本，或将结果暴露给错误的帐户。应将智能体结果及其周边界面一起测试。