ProjectConnector で end-user accounts を接続する

product のすべての user が自分の provider account を接続する必要がある場合は、ProjectConnector を使用します。backend は各 user を externalUserId で識別し、authorization links を作成し、connected account IDs を保存して、その user の actions を実行します。

この方法では、oo_proj_… 形式の project API key を使います。Connector が使用する personal api_… key とは別のものです。

自分の Agent に接続する

ProjectConnector は接続サービスへの呼び出しを提供します。OOMOL が外部サービスの認可、認証情報の保管、token 更新、操作の実行を処理します。製品側ではユーザー認証、アカウントの紐付け、Agent のツール handler を実装します。

Agent がバックエンドで動く場合、ツール handler から ProjectConnector を直接呼び出せます。ユーザーの端末で動く場合は、製品の認証済みバックエンドへツールリクエストを送信します。Project API key は常にバックエンドに保管します。

ホスト型の個人・チーム用 MCP 設定は OOMOL のユーザーとチームの接続用です。SaaS ユーザーのアカウントには ProjectConnector または SaaS HTTP API を使用します。MCP が必要なクライアントには、製品ユーザーを認証する MCP アダプターをバックエンドに用意します。

project を準備する

runtime flow を実装する前に、OOMOL Console で次の resources を作成します。

Connector project。
users が接続できる service ごとの provider config。
backend secret manager に保存する project API key。

Connector for SaaS ガイドでは、Console の設定と対応する REST requests を説明しています。

インストールと初期化

npm install @oomol-lab/connector

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

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

OAuth authorization request を作成する

自分の user database にある安定した ID を externalUserId として使用します。

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

redirectUserTo(request.authorizationUrl);

user が認証した後、request が final state になるまで待ちます。

const connected = await project.waitForConnection(request);

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

project.connect.oauth は、user の操作を待つ authorization request を返します。認証が成功した後にだけ、waitForConnection が request result 内の connectedAccountId を返します。

API-key provider と custom-credential provider には、connect.apiKey または connect.customCredential を使用します。これらの method は credential を検証し、connected account を同期的に返します。

1 人の user として実行する

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

取得済みの場合は connectedAccountId を渡してください。特定の account を選択でき、最新の active account に依存せずに済みます。product が安定した aliases を使用する場合は、connectionName も利用できます。

同じ request または job に複数の操作が含まれる場合は、forUser で user を一度 bind します。

Slack の例では、このユーザーに「work」という名前の接続が必要です。バックエンドに保存した該当 Slack アカウントの接続名を使ってください。forUser が固定するのはユーザーだけです。アカウントは execute のオプションで選択します。

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

操作を Agent のツールにする

以下はフレームワークに依存しないツール記述です。schema と handler を利用する Agent フレームワークに登録してください。作成前にリクエストを認証し、ユーザーの操作権限を確認して、データベースからそのユーザーの 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 ツールとして自動登録することはありません。

product boundaries を明確に保つ

product は自分の users を認証し、利用できる providers と actions を管理します。project API key は backend に保管し、一貫した externalUserId を渡し、返された account selector を対応する product user と一緒に保存してください。

authorization-request と connected-account の lifecycle fields、action ごとの precise types、errors、retries、waiting options、完全な ProjectConnector API については、TypeScript SDK referenceを参照してください。