cohesivity
ブログ
エージェントネイティブなバックエンド

公開日: 更新日

AragとShouryamaan

AIコーディングエージェントがデータベース、認証、ストレージ、ホスティングをプロビジョニングする方法

Markdownで読む

AIコーディングエージェントは、一つのプロジェクトテナントを作成し、必要な各サービスの最新契約を読み、リソースを一つずつプロビジョニングし、返されたエンドポイントを検証することで、Cohesivityのバックエンドを用意できます。エージェントは既存の.cohesivityファイルを再利用し、Cohesivityの両方の認証情報をブラウザーコードへ含めないようにします。

この記事では、すべてのリソースbodyを固定して掲載するのではなく、その手順を扱います。エージェントがタスクを実行するときは、offeringページが信頼できる情報源です。

アプリケーションの要件から始める

アプリケーションに必要な状態と外部への効果を列挙します。

  • リレーショナルデータにはpostgresが必要な場合がある。
  • Googleログインにはsocial-loginが必要な場合がある。
  • アップロードにはobject-storageが必要な場合がある。
  • 公開サーバーにはrailway-hostingまたはcloudflare-workersが必要な場合がある。
  • 非同期メールにはinboxが必要な場合がある。
  • リアルタイムのfan-outにはrealtimeが必要な場合がある。

アプリケーションにAI機能があるというだけで、ベクトルデータベースをプロビジョニングしてはいけません。Postgresとベクトルデータベースのガイドでは、セマンティック検索に別ストアが必要となる条件を説明しています。

プロジェクトをbootstrapまたは再利用する

まず、有効な.cohesivityファイルがあるか確認します。存在する場合は、そのテナントを再利用します。別のテナントを作ると、関連リソースが分散してクリーンアップが難しくなります。

プロジェクトがなければ、まずbootstrapの内容をプレビューします。

npx @cohesivity/init --dry-run

続いて一時プロジェクトを作成します。

npx @cohesivity/init

このコマンドは、管理キー、アプリケーションキー、テナントID、ライフサイクル、ランタイムプロファイル、失効期限を含むプロジェクトコンテキストを書き込みます。初期テナントは72時間有効で、登録は不要です。後からclaimする操作は、人間による別の同意手順です。

各サービスの最新offering契約を読む

プロビジョニング前に、最新のPostgres offering契約など、対象リソースの現在のページを取得します。Cohesivityへ直接HTTPリクエストを送る場合は、デフォルト以外のUser-Agentが必要です。

curl -sS -A "MyCodingAgent/1.0" \
  https://cohesivity.ai/offerings/postgres

必須body、固定リージョン、現在の上限、認証方式、破壊的操作、検証フィールドを確認します。すべてのリソースについて繰り返してください。エージェントが操作可能なバックエンドのガイドでは、状態確認とクリーンアップも契約に含まれる理由を説明しています。

最初にデータベースをプロビジョニングする

現在のPostgres契約では、次のような管理プレーンのリクエストを使います。

curl -sS -A "MyCodingAgent/1.0" -X POST \
  https://cohesivity.ai/api/resources/postgres \
  -H "Authorization: Bearer <coh_management_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: provision-postgres-v1" \
  -d '{}'

Postgresは単一リージョン（シンガポール）で稼働します。リクエストのregionフィールドは受け付けられますが無視されます。レスポンスが準備完了を示し、文書化されたエンドポイントを返した時点で、リソースは利用可能です。リクエストが200を返しただけで、準備完了と推測してはいけません。

サーバー側のアプリケーションコードからは、一つのSQL文またはatomic batchをPostgresへ送れます。PostgreSQLでは$1プレースホルダーを使います。

curl -sS -A "MyAppServer/1.0" -X POST \
  "https://cohesivity.ai/edge/postgres?key=<coh_application_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-signups-schema-v1" \
  -d '{"query":"CREATE TABLE IF NOT EXISTS signups (id BIGSERIAL PRIMARY KEY, email TEXT UNIQUE NOT NULL)"}'

query stringに認証情報を置く方法は、文書化されたfallbackです。サーバーはアプリケーションキーを短期edge session tokenへ交換し、代わりにbearer authを使うこともできます。どちらの認証情報もクライアント側JavaScriptに含めてはいけません。

すべてのコールバックURLを指定して認証を追加する

ソーシャルログインをプロビジョニングすると、コールバックURLの一覧全体が置き換わります。開発用と本番用のURLを同じリクエストに含めます。

curl -sS -A "MyCodingAgent/1.0" -X POST \
  https://cohesivity.ai/api/resources/social-login \
  -H "Authorization: Bearer <coh_management_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: provision-social-login-v1" \
  -d '{"callback_urls":["http://localhost:3000/auth/done","https://example.cohesivity.app/auth/done"]}'

ホスティングフローが返した実際のデプロイホスト名を使います。後から一つのURLだけを指定して一覧を置き換えると、省略したコールバックは削除されます。

ストレージとホスティングをそれぞれの契約からプロビジョニングする

オブジェクトストレージのプロファイル、アップロード動作、ホスティングのファイル形式、環境変数、ドメイン、準備完了の確認には、それぞれ個別のofferingページがあります。使う直前に取得してください。Cohesivityの現在の主なホスティング経路ではRailwayのホスティングAPIを使ってファイルをアップロードし、Railway CLI、GitHub連携、テナントが所有するRailwayの認証情報は必要ありません。

一つのサービスをプロビジョニングして検証してから、次へ進みます。一括リクエストで節約できる時間はわずかで、どの契約が失敗したのか特定しにくくなります。

ライフサイクル全体を検証する

セットアップ後は、次を確認します。

  1. 管理プレーンからリソースの状態を照会する。
  2. サーバー側からアプリケーション呼び出しを一つ実行する。
  3. 同じ冪等性キーで書き込みを一つ繰り返し、効果が一つだけであることを確認する。
  4. ブラウザーのasset、ログ、バージョン管理にcoh_*の値がないことを確認する。
  5. テナントの失効期限とclaimの境界を記録する。
  6. 各使い捨てリソースの削除方法を文書化する。

以下のプロンプトは、コーディングエージェントに最小限のリソース一式を求め、何かを作成する前に停止させます。