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

SquidにAPIを接続して、データベースに書き込む荷造りリストを作成するエージェントを構築する

作成する内容

提供した郵便番号と旅行日程に基づいて、休暇用の持ち物リストを作成するフルスタックアプリ。
アプリは外部APIを使用して予測天気をチェックし、その天気に基づいて荷造りすべきアイテムのリストを作成し、これらのアイテムをデータベースに書き込みます。

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

AI Abilities	Internal Connectors	External Connectors	Backend Functions
AI Functions	Built-in Database	HTTP API	Executables, Triggers

このアプリケーションは WeatherAPI.com との連携により、指定された場所と日付の天気予報を取得し、その情報を AI agent に渡して、Squidの built-in database へ推奨される持ち物を書き込む AI function を使用します。

この機能は Real-time Product Search API を使用して、Google Shoppingで購入可能な推奨アイテムへのリンクを提供することで拡張されています。これにより、Squidを使った複数のサービスとの簡単な統合とAI機能の活用方法を紹介しています。

App preview

学べること

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

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

Environment setup

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との接続

SquidにAPIを接続するには、多くの場合、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)

![Select show schema](/img/ai_vacation_2.png)

2. Base 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** をオンにして新しいsecretを作成してください。Secretの値として、WeatherAPI.comのAPIキーを貼り付けます。Secretが保存され選択されていることを確認し、右上の **Save Schema** ボタンをクリックしてスキーマを保存してください。

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

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

もし、AIエージェントによって推奨されたアイテムを所有していない場合、アプリはGoogle Shoppingへのリンクを提供し、簡単に必要なものを購入できるようにします。これは、[RapidAPI](https://rapidapi.com)で提供されているProduct Search 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 タブに移動し、product-search コネクタのスキーマにアクセスします。これは先ほどの weather コネクタと同様です。
search エンドポイントをクリックします。
Injections エリアの + をクリックして新しいinjectionを追加します。
Field name を X-RapidAPI-Key、Location を header に設定します。Secret をオンにして新しいsecretを作成してください。Secretの値として、RapidAPIのAPIキーを貼り付け、secretが保存され選択されていることを確認してから、新しいinjectionを保存してください。

AIエージェントの追加

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

Agent ID: planner
Description: This is an agent for Squid AI's vacation planner tutorial

Create をクリックしてエージェントを作成します。
Instructions フィールドに、以下の指示をエージェントに追加してください:

You are designed to create a list of items to pack for a trip based on the provided weather forecast and date, where the date is a string. You should create 3-5 items.

これらの指示は、AIエージェントがどのような動作をするかを示しています。

Squidアプリケーションの確認

フロントエンドとバックエンドの両方が起動している状態で、ウェブブラウザから http://localhost:5173/ にアクセスしてください。以下の手順でSquidアプリケーションの機能を確認できます:

休暇先の郵便番号を入力してください。例: 90210。
次に、今後14〜90日の範囲内で休暇の開始日と終了日を入力します。デモンストレーションのため、このアプリでは休暇日数を5日間に制限しています。これにより、アプリが発行するAPIコールの数を制限できます。
Submit をクリックし、推奨される荷造りアイテムが表示されるのを確認してください！

次のステップ

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

SquidにAPIを接続して、データベースに書き込む荷造りリストを作成するエージェントを構築する​

作成する内容​

学べること​

Environment setup​

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

WeatherAPI.comとの接続​

AIエージェントの追加​

Squidアプリケーションの確認​

次のステップ​