將你的 AI 代理程式連接到第三方 API

本指南將帶你一步步實現讓 AI 代理程式能以使用者身分存取第三方 API（例如 Google Calendar、GitHub 等）。透過 Logto 的社交連接器 (Social connectors) 與 Secret Vault，你可以安全地儲存與管理存取權杖 (Access tokens)，讓代理程式自動執行任務，而無需反覆要求使用者重新驗證 (Authentication)。

你將學會：

設定支援第三方權杖儲存的社交連接器 (Social connectors)。
在初次登入時請求最小權限。
根據需求逐步請求額外權限。
取得並使用已儲存的權杖來存取第三方 API。

為什麼你的 AI 代理程式需要第三方 API 存取權

AI 代理程式越來越常用於自動化需要與外部服務互動的任務。例如：

📅 行事曆管理：AI 代理程式可自動排定會議、加入事件或調整 Google Calendar 上的行程。
📧 郵件自動化：透過 Gmail API 發送追蹤郵件、整理收件匣或撰寫回覆。
💻 程式碼管理：建立 GitHub 問題單、審查 Pull Request 或管理儲存庫。
📁 檔案管理：在 Google Drive 或 Dropbox 上上傳、整理或分享檔案。

要執行這些任務，你的 AI 代理程式需要安全地存取使用者授權的第三方 API，這意味著必須正確且安全地處理 OAuth 權杖。

運作方式說明

以下是流程的快速概覽：

使用者請求任務：使用者要求 AI 代理程式執行需要第三方 API 存取的任務（如新增行事曆事件）。
授權提示：代理程式偵測到需要第三方存取權，提示使用者授權。
權杖儲存：使用者授權後，Logto 會將存取權杖與重新整理權杖 (Refresh tokens) 安全儲存於 Secret Vault。
執行任務：代理程式取得已儲存的權杖並呼叫第三方 API 完成任務。

一旦授權，使用者可多次執行任務而無需重複授權。Logto 會安全儲存權杖並於需要時自動重新整理，讓 AI 代理程式持續互動體驗順暢無縫。

先決條件

開始前，請確保你已具備：

一個 Logto Cloud（或自架 Logto v1.31+）租戶
一個具備 API 存取權的第三方服務帳號（如 Google Cloud Console）
已整合 Logto SDK 的 AI 代理程式應用（使用者可登入你的 AI 代理程式）

若要讓 AI 代理程式存取第三方 API，你需要設定一個啟用權杖儲存的社交連接器。這讓 Logto 能在使用者與 AI 代理互動授權第三方服務時，儲存並管理存取權杖。

以 Google 為例：

前往 Console > Connectors > Social connectors。
點擊 新增社交連接器 (Add social connector) 並選擇 Google。
依照 Google 連接器設定指南設定 OAuth 用戶端憑證。
在連接器設定中：
- 啟用 為持久 API 存取儲存權杖 (Store tokens for persistent API access)，將權杖儲存到 Secret Vault。
- 設定 Prompts 包含 consent，確保使用者看到權限請求。
- 啟用 離線存取 (Offline access)，以取得長效 API 存取所需的重新整理權杖 (Refresh tokens)。
儲存設定。

資訊:

你不需要將此連接器加入登入體驗。該連接器僅於 AI 代理程式需要存取第三方 API 時按需授權，不用於使用者登入。

請求授權並存取第三方 API

當 AI 代理程式需要存取第三方 API（如 Google Calendar）時，應先檢查使用者是否已授權。若尚未授權，則提示使用者進行授權。

啟用 Account API:

繼續前，請於 Console > Sign-in experience > Account center 啟用 Account API。詳見如何啟用 Account API。

步驟 1：檢查是否已授權

首先，嘗試取得已儲存的存取權杖，判斷使用者是否已授權：

async function getGoogleAccessToken(userAccessToken: string) {
  const response = await fetch(
    'https://[tenant-id].logto.app/my-account/identities/google/access-token',
    {
      headers: {
        Authorization: `Bearer ${userAccessToken}`,
      },
    }
  );

  return response.json();
}

步驟 2：如有需要請求授權

若無權杖、權杖已過期，或需擴展權杖的權限範圍 (Scope)，請使用 Logto 的 Social Verification API 啟動授權流程：

async function requestGoogleAuthorization(userAccessToken: string, scopes: string) {
  // 產生隨機 state 以防 CSRF 攻擊
  const state = crypto.randomUUID();
  sessionStorage.setItem('oauth_state', state);

  // 啟動社交驗證
  const response = await fetch('https://[tenant-id].logto.app/api/verification/social', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${userAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      connectorId: '<google_connector_id>',
      state,
      redirectUri: 'https://your-ai-agent.com/callback',
      scope: scopes,
    }),
  });

  const { verificationRecordId, authorizationUri } = await response.json();

  // 儲存 verificationRecordId 以便後續使用
  sessionStorage.setItem('verificationRecordId', verificationRecordId);

  // 導向 Google 進行授權
  window.location.href = authorizationUri;
}

步驟 3：處理授權回呼

使用者授權後，Google 會導回你的應用。完成驗證並儲存權杖：

async function handleAuthorizationCallback(
  userAccessToken: string,
  callbackParams: URLSearchParams
) {
  const verificationRecordId = sessionStorage.getItem('verificationRecordId');
  const storedState = sessionStorage.getItem('oauth_state');
  const code = callbackParams.get('code');
  const state = callbackParams.get('state');

  // 驗證 state 以防 CSRF 攻擊
  if (state !== storedState) {
    throw new Error('Invalid state parameter');
  }

  // 驗證授權
  await fetch('https://[tenant-id].logto.app/api/verification/social/verify', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${userAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      verificationRecordId,
      connectorData: {
        code,
        state,
        redirectUri: 'https://your-ai-agent.com/callback',
      },
    }),
  });

  // 將權杖儲存到 Logto 的 Secret Vault
  await fetch('https://[tenant-id].logto.app/my-account/identities/google/access-token', {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${userAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      verificationRecordId,
    }),
  });

  // 清理暫存
  sessionStorage.removeItem('verificationRecordId');
  sessionStorage.removeItem('oauth_state');
}

步驟 4：呼叫第三方 API

現在你的 AI 代理程式可以取得權杖並呼叫 API：

async function addCalendarEvent(userAccessToken: string, eventDetails: EventDetails) {
  // 取得已儲存的 Google 存取權杖
  const tokenData = await getGoogleAccessToken(userAccessToken);

  if (!tokenData) {
    // 使用者尚未授權，請求 calendar 權限
    await requestGoogleAuthorization(
      userAccessToken,
      'https://www.googleapis.com/auth/calendar.events'
    );
    return; // 導向後續繼續
  }

  // 呼叫 Google Calendar API
  const response = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${tokenData.accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(eventDetails),
  });

  return response.json();
}

Logto 會自動處理權杖重新整理。如果存取權杖已過期但有重新整理權杖 (Refresh token)，Logto 會在你呼叫取得端點時自動換取新權杖。

請求額外權限

隨著 AI 代理程式承擔更多任務，你可能需要請求額外權限。例如，使用者最初僅授權唯讀行事曆存取，現在想建立事件，則需寫入權限。

為什麼要逐步授權？

更佳的使用者體驗：使用者在理解需求情境下更願意授權。
更高的轉換率：初始權限請求越少，阻力越小。
建立信任：只請求所需權限的應用更易獲得信任。

範例：從唯讀升級為可寫入存取

async function createCalendarEvent(userAccessToken: string, eventDetails: EventDetails) {
  const tokenData = await getGoogleAccessToken(userAccessToken);

  if (!tokenData) {
    // 尚未授權，直接請求 calendar 寫入權限
    await requestGoogleAuthorization(userAccessToken, 'https://www.googleapis.com/auth/calendar');
    return;
  }

  // 嘗試建立事件
  const response = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${tokenData.accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(eventDetails),
  });

  if (response.status === 403) {
    // 權限不足，請求額外權限範圍 (Scope)
    await requestGoogleAuthorization(
      userAccessToken,
      'https://www.googleapis.com/auth/calendar' // 完整行事曆存取
    );
    return;
  }

  return response.json();
}

提示:

請求額外權限範圍 (Scopes) 時，使用者會看到僅有新權限的授權頁面，既有權限會被保留。

管理權杖狀態

Logto Console 可檢視每位使用者的權杖狀態：

前往 Console > User management。
點擊使用者以檢視詳細資料。
捲動至 連線 (Connections) 區塊，查看所有已連結的社交帳號。
每個連線會顯示權杖狀態：
- 啟用 (Active)：存取權杖有效且可用。
- 已過期 (Expired)：存取權杖已過期。若有重新整理權杖，下一次取得時會自動刷新。
- 未啟用 (Inactive)：此連線未儲存任何權杖。

安全性最佳實踐

開發可存取第三方 API 的 AI 代理程式時，請注意以下安全建議：

請求最小權限範圍 (Scopes)：僅請求代理程式實際需要的權限。
採用逐步授權：根據情境請求額外權限，不要一次請求全部。
妥善處理權杖過期：隨時處理權杖可能過期或被撤銷的情況。
保護使用者存取權杖：使用者的 Logto 存取權杖是取得第三方權杖的關鍵，務必妥善保護。
稽核 API 存取紀錄：記錄 AI 代理程式存取第三方 API 的行為，便於除錯與合規。

第三方權杖儲存社交連接器 (Social connectors) 社交登入 (Social sign-in) Account API

為什麼你的 AI 代理程式需要第三方 API 存取權​

運作方式說明​

先決條件​

設定支援權杖儲存的社交連接器​

請求授權並存取第三方 API​

步驟 1：檢查是否已授權​

步驟 2：如有需要請求授權​

步驟 3：處理授權回呼​

步驟 4：呼叫第三方 API​

請求額外權限​

為什麼要逐步授權？​

範例：從唯讀升級為可寫入存取​

管理權杖狀態​

安全性最佳實踐​

相關資源​