使用 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 API 呼叫。客戶端要求 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。

透過 SaaS Proxy 呼叫供應商 API.