データベースと API に AI エージェントを接続する

Squid に API を接続して、パッキングリストを作成するためにデータベースへ書き込むエージェントを構築する

作成するもの

入力した郵便番号と旅行日程に基づいて、バケーション用の持ち物リストを作成するフルスタックアプリ
アプリは外部 API を使用して予測された天気を確認し、その天候に基づいて持ち物リストを作成し、これらの項目をデータベースに書き込みます

このチュートリアルでは、次の機能を使用します:

AI Abilities (AI 能力)	Internal Connectors (内部コネクタ)	External Connectors (外部コネクタ)	Backend Functions (バックエンド機能)
AI Functions	Built-in Database	HTTP API	Executables, Triggers

このアプリケーションは WeatherAPI.com と統合され、指定された場所と日付の天気予報を取得し、その情報を AI agent に渡して AI function を使用し、提案された持ち物項目を Squid の built-in database に書き込みます

この機能は、Real-time Product Search API を使用して拡張され、Google Shopping から購入を提案された商品のリンクを提供します。これにより、Squid を使用して複数のサービスを AI 機能と統合する方法のシンプルさを実証しています。

App preview

学ぶこと

Squid AI を使用して AI エージェントを作成する方法
エージェントに関数を追加する方法

TypeScript の経験が必要です。React の経験は役に立ちますが、必須ではありません。

環境のセットアップ

In the Squid Console, switch to the dev environment.

switch environment

Download the squid-ai-vacation code sample using the following command. Replace the placeholders with the values from your Squid application as shown in the console.

npx @squidcloud/cli init-sample squid-ai-vacation --template squid-ai-vacation --appId YOUR_SQUID_APP_ID --apiKey YOUR_SQUID_API_KEY --environmentId dev --squidDeveloperId YOUR_SQUID_DEVELOPER_ID --region YOUR_REGION

TIP

You can find your environment variables under: 'Application' -> 'Show env vars' as seen below:

switch environment

Open the project in the IDE of your choice.
Start the app locally by running the following command in the project folder:

npm run start

To view the app, navigate to localhost:PORT, where PORT is logged in the terminal. The address will likely be http://localhost:5173.

WeatherAPI.com アカウントの作成

天気予報を取得するために、このアプリケーションは WeatherAPI.com で提供されている API を使用します。この API は無料トライアルを提供しているため、サンプルで料金なしで利用できます。

WeatherAPI.com の無料トライアルにサインアップします。
WeatherAPI.com のダッシュボードで、あなたの WeatherAPI.com API キーを確認してください。 この API キーを必ずメモしておいてください。後のステップで API コネクタを使用する際に必要になります。

WeatherAPI.com との接続

API を Squid に接続するためには、通常 Squid Console に HTTP API コネクタを追加しますが、このチュートリアルでは必須ではありません。詳細は HTTP API connectors のドキュメントをご覧ください。

このアプリケーションでは、cURL コマンドを使用して Weather API コネクタを生成できます。ターミナルウィンドウで、以下のコマンドを実行し、YOUR_SQUID_APP_ID と YOUR_SQUID_API_KEY のプレースホルダーを、あなたの Squid アプリの値に置き換えてください。正しい値は Squid Console のアプリ概要ページの Backend Project セクション、または .env ファイルに記載されています。

このコマンドを実行すると、Squid アプリケーションに weather という新しい API コネクタが追加されます。

curl -X PUT https://console.us-east-1.aws.squid.cloud/openapi/iac/applications/YOUR_SQUID_APP_ID-dev/integrations/weather -H "x-app-api-key: YOUR_SQUID_API_KEY" -H "Content-Type: application/json" -d '{
  "id": "weather",
  "configuration": {
    "discoveryOptions": {}
  },
  "type": "api"
}'

次の cURL コマンドを実行して API スキーマを設定します。YOUR_SQUID_APP_ID と YOUR_SQUID_API_KEY のプレースホルダーを、あなたの Squid アプリの値に置き換えてください。API スキーマを取得することで、API コネクタの利用が簡略化されます。

このコマンドを実行すると、Squid Console で weather コネクタを選択し、... ボタンをクリックして Schema を選ぶことで、スキーマを確認できます。

curl -X PUT https://console.us-east-1.aws.squid.cloud/openapi/iac/applications/YOUR_SQUID_APP_ID-dev/integrations/weather/schema -H "x-app-api-key: YOUR_SQUID_API_KEY" -H "Content-Type: application/json" -d '{
  "type": "api",
  "baseUrl": "https://api.weatherapi.com/v1",
  "endpoints": {
    "realtime-weather": {
      "relativePath": "/current.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        },
        "lang": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": null,
      "tags": null
    },
    "forecast-weather": {
      "relativePath": "/forecast.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        },
        "days": {
          "location": "query",
          "description": null
        },
        "dt": {
          "location": "query",
          "description": null
        },
        "unixdt": {
          "location": "query",
          "description": null
        },
        "hour": {
          "location": "query",
          "description": null
        },
        "lang": {
          "location": "query",
          "description": null
        },
        "alerts": {
          "location": "query",
          "description": null
        },
        "aqi": {
          "location": "query",
          "description": null
        },
        "tp": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": null,
      "tags": null
    },
    "future-weather": {
      "relativePath": "/future.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        },
        "dt": {
          "location": "query",
          "description": null
        },
        "lang": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {
        "location": {
          "location": "body",
          "path": "location",
          "description": null
        },
        "forecast": {
          "location": "body",
          "path": "forecast",
          "description": null
        }
      },
      "injectionSchema": null,
      "tags": null
    },
    "history-weather": {
      "relativePath": "/history.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        },
        "dt": {
          "location": "query",
          "description": null
        },
        "unixdt": {
          "location": "query",
          "description": null
        },
        "end_dt": {
          "location": "query",
          "description": null
        },
        "unixend_dt": {
          "location": "query",
          "description": null
        },
        "hour": {
          "location": "query",
          "description": null
        },
        "lang": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": null,
      "tags": null
    },
    "marine-weather": {
      "relativePath": "/marine.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        },
        "days": {
          "location": "query",
          "description": null
        },
        "dt": {
          "location": "query",
          "description": null
        },
        "unixdt": {
          "location": "query",
          "description": null
        },
        "hour": {
          "location": "query",
          "description": null
        },
        "lang": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": null,
      "tags": null
    },
    "search-autocomplete-weather": {
      "relativePath": "/search.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": null,
      "tags": null
    },
    "ip-lookup": {
      "relativePath": "/ip.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": null,
      "tags": null
    },
    "time-zone": {
      "relativePath": "/timezone.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": null,
      "tags": null
    },
    "astronomy": {
      "relativePath": "/astronomy.json",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        },
        "dt": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {},
      "injectionSchema": {},
      "tags": null
    }
  },
  "injectionSchema": null
}'
  
## Weather API スキーマの表示と更新

WeatherAPI.com のリクエストには API キーが必要です。Squid では、[Squid Secrets](/docs/sdk/client-sdk/secrets) を使用して API キーを安全に保存できます。また、Squid の [injection](/docs/connectors/api/http#injections) 機能を使えば、すべてのリクエストに自動的にキーを含めることができます。API キーを注入することで、キーの安全性を確保し、Squid アプリケーションからの全ての WeatherAPI リクエストを自動的に認証できます。

1. [Squid Console](https://console.squid.cloud) にアクセスし、**weather** コネクタのスキーマに移動します。

![Click on the connector](/img/ai_vacation_1.png)

2. 基本 URL である `https://api.weatherapi.com/v1` をクリックします。

![Click on connector](/img/ai_vacation_3.png)

3. **Injections** エリアで **+** をクリックして、新しい injection を追加します。

![Add injection](/img/ai_vacation_4.png)

4. **Field name** は **key**、**Location** は **query** です。**Secret** をオンにしてから、新しい秘密を作成します。秘密の値として、あなたの WeatherAPI.com API キーを貼り付けてください。秘密が保存され、選択されていることを確認し、右上の **Save Schema** ボタンをクリックしてスキーマを保存してください。

![Save injection](/img/ai_vacation_5.png)

## Real-time Product Search API への接続

もし AI エージェントから提案されたアイテムを所有していない場合、アプリは Google Shopping へのリンクを提供し、必要な商品の購入を容易にします。これは、[RapidAPI](https://rapidapi.com) で利用可能なプロダクトサーチ API を使用して実現しています。

1. [Real-time Product Search API](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-product-search/) にアクセスし、サブスクライブします。WeatherAPI.com API と同様に、API キーが必要です。サインアップ後、**Open playground** をクリックして API キーを確認してください。

![view your API key](/img/ai_vacation_6.png)

2. 以下のコマンドを使用して Squid コネクタを生成します。`YOUR_SQUID_APP_ID` と `YOUR_SQUID_API_KEY` のプレースホルダーを、あなたの Squid アプリの値に置き換えてください:

```bash
curl -X PUT https://console.us-east-1.aws.squid.cloud/openapi/iac/applications/YOUR_SQUID_APP_ID-dev/integrations/product-search -H "x-app-api-key: YOUR_SQUID_API_KEY" -H "Content-Type: application/json" -d '{
  "id": "product-search",
  "configuration": {
    "discoveryOptions": {}
  },
  "type": "api"
}'

以下の cURL コマンドを実行して、API スキーマをコネクタに追加します。YOUR_SQUID_APP_ID と YOUR_SQUID_API_KEY のプレースホルダーを、あなたの Squid アプリの値に置き換えてください:

curl -X PUT https://console.us-east-1.aws.squid.cloud/openapi/iac/applications/YOUR_SQUID_APP_ID-dev/integrations/product-search/schema -H "x-app-api-key: YOUR_SQUID_API_KEY" -H "Content-Type: application/json" -d '{
  "type": "api",
  "baseUrl": "https://real-time-product-search.p.rapidapi.com",
  "endpoints": {
    "search": {
      "relativePath": "search",
      "method": "get",
      "requestSchema": {
        "q": {
          "location": "query",
          "description": null
        },
        "country": {
          "location": "query",
          "description": null
        },
        "language": {
          "location": "query",
          "description": null
        },
        "limit": {
          "location": "query",
          "description": null
        },
        "sort_by": {
          "location": "query",
          "description": null
        }
      },
      "responseSchema": {
        "data": {
          "location": "body",
          "path": "data",
          "description": null
        }
      },
      "injectionSchema": {
        "X-RapidAPI-Host": {
          "value": "real-time-product-search.p.rapidapi.com",
          "type": "regular",
          "location": "header"
        }
      },
      "tags": null
    }
  },
  "injectionSchema": null
}'

Squid Console で Connectors タブをクリックし、weather コネクタと同様に product-search コネクタのスキーマに移動します。
search エンドポイントをクリックします。
Injections エリアで + をクリックして、新しい injection を追加します。
Field name は X-RapidAPI-Key、Location は header です。Secret をオンにしてから、新しい秘密を作成します。秘密の値として、あなたの RapidAPI API キーを貼り付けてください。秘密が保存され、選択されていることを確認し、新しい injection を保存してください。

AI エージェントの追加

Squid Console で Agent Studio タブに移動します。
Create New Agent をクリックしてエージェントを追加します。次の詳細を入力してください:

Agent ID: planner
Description: これは Squid AI の vacation planner チュートリアル用のエージェントです

Create をクリックしてエージェントを作成します。
Instructions フィールドに、以下の指示を入力します:

あなたは、提供された天気予報と日付（この日付は文字列です）に基づいて、旅行のための持ち物リストを作成するよう設計されています。3〜5項目を作成してください。

これらの指示は、AI エージェントにどのような行動を取るかを伝えます。

Squid アプリケーションの探索

フロントエンドとバックエンドの両方が稼働している状態で、Webブラウザで http://localhost:5173/ にアクセスしてください。これで、count ボタンの操作を試し、Squid アプリケーションの機能を探索する準備が整いました:

目的のバケーション先の郵便番号を入力します。例: 90210。
今後14〜90日以内の開始日と終了日のバケーション日程を入力します。デモンストレーションのため、このアプリケーションは5日間のバケーションに制限しています。これにより、アプリが行う API コールの数を制限できます。
Submit をクリックし、提案された持ち物が表示されるのを確認してください！

次のステップ

Squid AI エージェントについてさらに学ぶには、documentation をご覧ください。
Squid のリアルタイムデータ機能についてさらに学ぶには、Client SDK documentation をご覧ください。
独自のデータソースとの統合方法については、database connectors documentation をご覧ください。

Squid に API を接続して、パッキングリストを作成するためにデータベースへ書き込むエージェントを構築する​

作成するもの​

学ぶこと​

環境のセットアップ​

WeatherAPI.com アカウントの作成​

WeatherAPI.com との接続​

AI エージェントの追加​

Squid アプリケーションの探索​

次のステップ​