メインコンテンツまでスキップ

グーグルカレンダー

SquidにGoogle Calendarを接続してカレンダーイベントを読み取りおよび管理する​

Google Calendarコネクタの機能​

Google Calendarコネクタを利用することで、Squid AIエージェントは自然言語を用いてカレンダーイベントの読み取りや管理が可能になります。これらの機能をエージェントに提供することで、ユーザーは自分のスケジュールを確認したり、イベントを作成またはミーティングを更新するようエージェントに依頼できます。

このコネクタは以下の機能をサポートします:

  • 指定された期間内のカレンダーイベントの読み取り
  • 参加者、リマインダー、繰り返し、Google Meetリンクなどのリッチなメタデータを含むイベントの作成および更新
  • 安全なOAuth2認証と自動トークン更新によるマルチユーザーサポート
  • AIを活用した自然言語によるカレンダーデータのクエリ

Google Calendarコネクタの設定​

SquidはOAuth2認証を利用してGoogle Calendarに接続します。Google Cloudプロジェクトを作成し、OAuth2認証情報を設定する必要があります。

Google Cloudプロジェクトの作成​

  1. Google Cloud Console にアクセスします。
  2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
  3. Google Calendar APIを有効化します:
    • APIs & Services > Library に移動します。
    • 「Google Calendar API」を検索します。
    • Enable をクリックします。
  4. OAuth2認証情報を作成します:
    • APIs & Services > Credentials に移動します。
    • Create Credentials > OAuth Client ID をクリックします。
    • 指示に従いOAuth同意画面を設定します。
    • アプリケーションタイプとして Web application を選択します。
    • 承認済みリダイレクトURIを追加します（例: https://your-app.com/oauth/callback）。
    • Client ID および Client Secret をメモしておきます。

SquidアプリケーションにGoogle Calendarコネクタを追加する​

  1. Squid Console の Connectors タブに移動します。

  2. Available Connectors をクリックします。

  3. Google Calendar コネクタを見つけ、Add Connector を選択します。

  4. 次の構成情報を入力します:

    Connector ID: コード内でコネクタを一意に識別する文字列。

    Client ID: Google Cloud Consoleから取得したOAuth2クライアントID。

    Client Secret: Google Cloud Consoleから取得したOAuth2クライアントシークレット。

    Redirect URI: OAuth2リダイレクトURI（Google Cloudで設定したものと一致する必要があります）。

OAuth2認証の仕組み​

Google Calendarコネクタは、安全なユーザー認証のためにOAuth2を使用します。以下は認証フローの概要です:

  1. Authorization: ユーザーをGoogleのOAuth同意画面に誘導し、アプリケーションの承認を行ってもらいます。ユーザーの同意後、認可コードが返されます。
  2. Token Exchange: 認可コードをSquidに保存し、アクセストークンとリフレッシュトークンに交換します。トークンは一意の識別子（例: User ID）を使用してユーザーごとに保存されます。
  3. Automatic Token Management: Squidはトークンを安全に保存し、アクセストークンの有効期限が切れると自動的に更新します。

このコネクタには以下のOAuth2スコープが必要です:

[
  'openid',
  'email',
  'https://www.googleapis.com/auth/calendar.events'
]

これらのスコープを、ユーザー向けのOAuth認可URLを生成する際に使用してください。OAuthフローの実装に関する詳細は、Google OAuth2 Web Server documentation を参照してください。

アプリケーションでのGoogle Calendarコネクタの使用方法​

Google Calendarコネクタを作成したら、StudioまたはSDKのいずれかで使用できます。

No-code Studio​

No-codeソリューションは、Squid Agent Studioを使って作成できます。

  1. Squid Console の Studio タブに移動します。

  2. Create AI Agent をクリックします。

  3. Agent ID と description（例: "calendar-agent" と "This agent helps the user manage their Google Calendar"）を入力します。

  4. Add Abilities をクリックし、SaaS セクションまでスクロールして、先ほど作成した Google Calendar コネクタを選択します。

  5. エージェントがこの接続をどのように使用するか（例: "Call this when a user wants to check their calendar or create events."）の説明を入力します。

  6. Test をクリックし、エージェントに "What meetings do I have next week?" と問いかけてみます。

コードでの基本的な構成要素​

SquidアプリケーションでGoogle Calendarコネクタを使用するには、@squidcloud/google-calendar-client npmパッケージをインストールします。

npm install @squidcloud/google-calendar-client

クライアントのセットアップ​

import { SquidGoogleCalendarClient } from '@squidcloud/google-calendar-client';
import { Squid } from '@squidcloud/client';

const squid = new Squid({
  appId: 'your-app-id',
  region: 'us-east-1.aws',
  environmentId: 'dev',
});

const calendarClient = new SquidGoogleCalendarClient(
  squid,
  'google_calendar' // your connector ID
);

OAuthフローの実装​

ユーザーがOAuth認証を完了し、認可コードを受け取ったら、それをSquidに保存します:

await calendarClient.saveAuthCode(authCode, userId);

この処理により、コードがトークンと交換され、安全に保存されます。ユーザーごとに一度だけ実行すればよく、その後はSquidがすべてのトークン管理を処理します。

カレンダーイベントの読み取り​

// Get events from primary calendar for the next 7 days
const events = await calendarClient.getCalendarEvents({
  identifier: userId,
});

// Get events with custom date range
const events = await calendarClient.getCalendarEvents({
  identifier: userId,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  maxResults: 100,
});

カレンダーイベントの作成​

// Create a simple timed event
const event = await calendarClient.upsertCalendarEvent({
  identifier: userId,
  summary: 'Team Meeting',
  description: 'Weekly team sync',
  start: new Date('2024-01-15T10:00:00'),
  end: new Date('2024-01-15T11:00:00'),
  location: 'Conference Room A',
});
// Create event with attendees and Google Meet
const eventWithMeet = await calendarClient.upsertCalendarEvent({
  identifier: userId,
  summary: 'Product Review',
  start: new Date('2024-01-20T14:00:00'),
  end: new Date('2024-01-20T15:00:00'),
  attendees: [
    { email: 'colleague@company.com', displayName: 'John Doe' },
    { email: 'manager@company.com' },
  ],
  addMeetLink: true,
  reminders: [
    { method: 'email', minutes: 60 },
    { method: 'popup', minutes: 10 },
  ],
});

AI機能の利用​

Google Calendarコネクタは、AIエージェントに接続可能なAI機能を提供します。ユーザー識別子は、エージェントに設定するか、エージェントコンテキストで渡すことができます:

// Configure on the agent (persists across all calls)
const agent = this.squid.ai().agent('calendar_agent');
await agent.upsert({
  options: {
    connectedIntegrations: [
      {
        integrationId: 'google_calendar',
        integrationType: 'google_calendar',
        options: {
          identifier: userId,
        },
      },
    ],
  },
});

const result = await agent.ask('What meetings do I have next week?');

// Or pass in the agent context (per-call override)
const result = await agent.ask('What meetings do I have next week?', {
  functions: ['listCalendarEvents'],
  agentContext: { identifier: userId },
});

おめでとうございます！これで、AIエージェントを通じてGoogle Calendarのイベントを管理できるようになりました！