使用 ProjectConnector 连接终端用户账号

当产品里的每个用户都要连接自己的 provider 账号时，使用 ProjectConnector。你的后端通过 externalUserId 标识用户，创建授权链接，保存 connected account ID，再代该用户执行 action。

这条路径使用形如 oo_proj_… 的 project API key，与 Connector 使用的个人 api_… key 相互独立。

接入自己的 Agent

ProjectConnector 已封装连接服务的调用。OOMOL 处理第三方账号授权、凭据保存、token 刷新和操作执行。你的产品负责用户登录鉴权、账号绑定和 Agent 工具 handler。

Agent 在后端运行时，工具 handler 可以直接调用 ProjectConnector。Agent 在用户设备运行时，将工具请求发到产品自己的鉴权后端。Project API key 始终保存在该后端。

托管的个人/团队 MCP 配置使用 OOMOL 用户和团队连接。SaaS 终端用户账号通过 ProjectConnector 或 SaaS HTTP 接口调用。客户端要求 MCP 时，需要在你的后端提供面向产品用户、带鉴权的 MCP 适配层。

准备 project

编写运行期流程前，先在 OOMOL Console 创建：

一个 Connector project。
用户可以连接的每个 service 对应的 provider config。
一个保存在后端密钥管理系统中的 project API key。

Connector for SaaS 使用指南包含 Console 配置步骤与对应的 REST 请求。

安装并初始化

npm install @oomol-lab/connector

import { ProjectConnector } from "@oomol-lab/connector";

const project = new ProjectConnector({
  apiKey: process.env.OOMOL_PROJECT_API_KEY!,
});

创建 OAuth 授权请求

使用业务数据库中的稳定用户 ID 作为 externalUserId：

const request = await project.connect.oauth("user_42", {
  service: "gmail",
  connectionName: "work",
  returnUri: "https://app.example.com/connected",
});

redirectUserTo(request.authorizationUrl);

用户完成授权后，等待请求进入最终状态：

const connected = await project.waitForConnection(request);

if (connected.status === "connected") {
  saveConnectedAccountId(connected.connectedAccountId);
}

project.connect.oauth 返回的是等待用户完成的授权请求。授权成功后，waitForConnection 才会在请求结果中返回 connectedAccountId。

对于 API key 和自定义凭据类型的 provider，使用 connect.apiKey 或 connect.customCredential。这两个方法会同步验证凭据并返回 connected account。

代一个用户执行 action

const result = await project.execute(
  "user_42",
  "gmail.search_threads",
  { query: "is:unread" },
  { connectedAccountId: "ca-1" },
);

已经保存 connectedAccountId 时，优先显式传入。它会选择一个确定的账号，避免依赖“最新 active 账号”。如果产品使用稳定 alias，也可以传 connectionName。

同一个请求或任务需要执行多次操作时，可以通过 forUser 绑定一次用户：

Slack 示例要求该用户已有名为“work”的连接。请使用后端为该 Slack 账号保存的连接名称。forUser 只绑定用户；账号选择器应传入 execute 的选项。

const user = project.forUser("user_42");
await user.execute(
  "slack.post_message",
  { channel: "#general", text: "shipped" },
  { connectionName: "work" },
);

将操作接入 Agent 工具

下面是与框架无关的工具描述，展示需要注册到 Agent 框架的 schema 和 handler。创建前，先鉴权请求、确认用户可以执行该操作，再从数据库读取该用户的 Gmail 账号绑定。currentUser.id 是后端确定的 external user ID；storedAccount.connectedAccountId 属于该用户。这两个值都不由模型参数指定。

const searchMailTool = {
  name: "search_mail",
  description: "Search the current user's Gmail threads.",
  inputSchema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
    additionalProperties: false,
  },
  execute: async (input: { query: string }) =>
    project.forUser(currentUser.id).execute(
      "gmail.search_threads",
      input,
      { connectedAccountId: storedAccount.connectedAccountId },
    ),
};

调用 handler 前，按 schema 校验工具参数。模型只提供搜索条件。先开放产品需要的操作，再按用户已连接的服务筛选；SDK 不会自动把所有 provider 操作注册为 Agent 工具。

明确产品边界

你的产品负责鉴权自己的用户，并控制用户可以使用哪些 providers 与 actions。Project API key 只保存在后端；始终传入一致的 externalUserId，并把返回的账号选择器保存到对应业务用户下。

TypeScript SDK 参考包含授权请求与 connected account 的生命周期字段、精确 action 类型、错误、重试、等待选项和完整 ProjectConnector API。