---
author: OOMOL
author_url: https://oomol.com/ja/about/
title: ProjectConnector で end-user accounts を接続する
description: TypeScript backend で ProjectConnector を使い、SaaS users の accounts
  を接続して、その users に代わって actions を実行します。
lang: ja
canonical_url: https://oomol.com/ja/docs/project-connector/
markdown_url: https://oomol.com/ja/docs/project-connector.md
---

# 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 を作成します。

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

[Connector for SaaS ガイド](/ja/docs/connector-saas/)では、Console の設定と対応する REST requests を説明しています。

## インストールと初期化

```sh
npm install @oomol-lab/connector
```

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

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

## OAuth authorization request を作成する

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

```ts
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 になるまで待ちます。

```ts
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 として実行する

```ts
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 のオプションで選択します。

```ts
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` はそのユーザーのアカウントです。どちらもモデルの引数から取得しません。

```ts
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](/ja/docs/connector-sdk/)を参照してください。