ProjectConnector로 최종 사용자 계정 연결하기

제품의 모든 사용자가 각자의 제공자 계정을 연결해야 할 때 ProjectConnector을 사용하세요. 백엔드는 externalUserId로 각 사용자를 식별하고, 인증 링크를 생성하며, 연결된 계정 ID를 저장하고, 해당 사용자를 위해 작업을 실행합니다.

이 경로는 oo_proj_… 형태의 프로젝트 API 키를 사용합니다. Connector에서 사용하는 개인 api_… 키와는 별개입니다.

자체 Agent 연결하기

ProjectConnector는 연결 서비스 호출을 제공합니다. OOMOL은 외부 계정 인증, 자격 증명 저장, token 갱신 및 작업 실행을 처리합니다. 제품에서는 사용자 로그인 인증, 계정 연결 정보 및 Agent 도구 handler를 구현합니다.

Agent가 백엔드에서 실행되면 도구 handler가 ProjectConnector를 직접 호출할 수 있습니다. 사용자 기기에서 실행되면 인증된 제품 백엔드로 도구 요청을 보내세요. Project API key는 항상 해당 백엔드에 보관합니다.

호스팅 개인/팀 MCP 설정은 OOMOL 사용자 및 팀 연결용입니다. SaaS 최종 사용자 계정에는 ProjectConnector 또는 SaaS HTTP API를 사용하세요. MCP가 필요한 클라이언트에는 제품 사용자를 인증하는 MCP 어댑터를 백엔드에 구현해야 합니다.

프로젝트 준비하기

런타임 흐름을 작성하기 전에 OOMOL Console에서 다음 리소스를 생성하세요:

Connector 프로젝트.
사용자가 연결할 수 있는 각 서비스에 대한 제공자 구성.
백엔드 시크릿 관리자에 저장된 프로젝트 API 키.

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 키 및 사용자 지정 자격 증명 제공자의 경우 connect.apiKey 또는 connect.customCredential를 사용하세요. 이 메서드들은 자격 증명을 검증하고 연결된 계정을 동기적으로 반환합니다.

한 사용자를 위해 실행하기

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

connectedAccountId이 있으면 전달하세요. 특정 계정 하나를 선택하고 최신 활성 계정에 의존하지 않도록 합니다. 제품에서 안정적인 별칭을 사용하는 경우에는 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 도구로 연결하기

다음은 특정 프레임워크에 종속되지 않는 도구 정의입니다. 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 도구로 자동 등록하지는 않습니다.

제품 경계를 명확히 유지하기

제품은 자체 사용자를 인증하고 사용자가 사용할 수 있는 제공자와 작업을 제어합니다. 프로젝트 API 키는 백엔드에 보관하고, 일관된 externalUserId을 전달하며, 반환된 계정 선택자를 해당 제품 사용자 옆에 저장하세요.

인증 요청 및 연결된 계정 수명 주기 필드, 정확한 작업 유형, 오류, 재시도, 대기 옵션, 그리고 전체 ProjectConnector API는 TypeScript SDK 레퍼런스를 참조하세요.

SaaS Proxy로 공급자 API 호출하기.