コーディングエージェントが構造化された契約を通じてリソースを作成、調査、利用、復旧、移管、削除できるなら、そのバックエンドはエージェントが操作可能です。ランタイムAPIへのアクセスは一つの手順にすぎません。プロジェクトのセットアップ、認証情報、障害、所有権、クリーンアップも含まれます。
最も早いテスト方法は、一つのデータベースまたはデプロイをライフサイクル全体で追跡することです。状態確認や削除の契約が欠けていれば、依然として人間向けダッシュボードに依存しています。
エージェントからアクセス可能であることと、操作可能であることは違う
エージェントからアクセス可能なバックエンドでは、人間が設定した後にアプリケーションがデータベースやAPIを呼び出せます。エージェントが操作可能なバックエンドでは、認可されたエージェントがその状態へ到達して維持するために必要な管理作業も実行できます。
| ライフサイクルの手順 | アクセス可能なバックエンド | 操作可能なバックエンド |
|---|---|---|
| 作成 | 人間がコンソールを使う | エージェントが型付きの作成アクションを呼ぶ |
| 検出 | 人間がIDとURLをコピーする | エージェントが構造化された識別子とエンドポイントを受け取る |
| 利用 | アプリケーションがサービスを呼ぶ | アプリケーションがスコープ付きデータプレーン認証情報を使う |
| 復旧 | 人間がログを読み、再試行する | エージェントが操作状態を読み、再試行契約に従う |
| ローテーション | 人間がシークレットを置き換える | 上流の認証情報を見ずに、エージェントがローテーションを要求する |
| 移管 | アカウントがすでに人間に属している | 明示的なフローで人間がclaimまたは所有権を引き受ける |
| 削除 | コンソール操作 | 依存関係と復旧ルールを備えた認可済み削除アクション |
エージェントネイティブ・インフラストラクチャのガイドでは、プラットフォーム全体に同じ区別を適用しています。
コントロールプレーンとデータプレーンを分ける
コントロールプレーンはリソースを作成し、設定を変更し、状態を報告し、所有権を処理し、請求を強制します。データプレーンはアプリケーションのリクエストを処理します。両者の認証情報は分けるべきです。
コーディングエージェントは構築中に管理用の認証情報を必要とする場合があります。デプロイされたアプリケーションには、必要なデータプレーンアクセスだけを渡します。ブラウザーバンドルには、認証情報が明示的に公開用であるか、短期セッショントークンと交換される場合を除き、どちらも渡してはいけません。
NISTのゼロトラストガイダンスは、ネットワーク上の位置ではなく、主体、リソース、ポリシーに基づいてアクセスを判断します。同じ原則がここでも役立ちます。要求されたリソースとアクションについてエージェントのIDを認可し、その判断をサービスで強制します。
リソース作成を観測可能にする
作成呼び出しは、リソースIDと操作状態を返す必要があります。処理が非同期で続く場合は、ready、failed、deletedなど安定した終了状態を持つ状態確認アクションを公開します。
ダッシュボードのURLやDNSレコードの存在から、エージェントに準備完了を推測させないでください。何が準備でき、何が保留中なのかをプラットフォームが明示する必要があります。
安全な書き込み動作を定義する
すべての書き込みについて、次の内容を文書化します。
- 冪等かどうか
- 再試行を識別する操作キーまたは冪等性キー
- サーバーがそのキーを保持する期間
- タイムアウト後の結果が既知か不明か
- 呼び出し元が元の結果を取得する方法
- 安全に再試行できる失敗
Stripeの冪等性ドキュメントは、キーに対する最初の結果を保存して返す明確な公開例です。保持期間やパラメーターのルールは異なっても構いませんが、同じ程度に明確な契約が必要です。
次のアクションが変わるエラーを返す
エージェントには安定したコード、短いメッセージ、構造化された詳細情報が必要です。有用な区別には次のものがあります。
| エラー | 次のアクション |
|---|---|
invalid_request |
指定されたフィールドを修正 |
not_authorized |
停止し、より狭い、または別のIDを要求 |
approval_required |
正確なアクションを人間へ表示 |
operation_in_progress |
提示された操作IDをpoll |
rate_limited |
提示された再試行時刻まで待機 |
quota_exceeded |
停止するか、プランまたは支出を変更する前に確認 |
dependency_conflict |
指定された依存リソースを解決 |
HTMLのエラーページや一般的な500エラーでは、エージェントが推測せざるを得ません。プロビジョニング中の推測は、リソースの重複と不完全なクリーンアップにつながります。
所有権をbootstrapから分ける
ユーザーがアカウントを作る前に、エージェントが隔離されたプロジェクトを作成する必要がある場合があります。そのプロジェクトにも失効期限と、後から人間がclaimする経路が必要です。claimによる所有権の拡大は明示的な同意後だけにし、承認URLでエージェントの一時シークレットを公開してはいけません。
Cohesivityはこのパターンを採用しています。npx @cohesivity/initは72時間有効な一時テナントを作成または再利用します。リソースのドキュメントは/offerings/<name>にあり、プロビジョニングには管理プレーンを使い、アプリケーションは別のedge認証情報を使います。人間によるclaimは、その後の同意手順です。
コーディングエージェントによるバックエンドリソースのプロビジョニング実践ガイドで、この流れを紹介しています。
依存する前に削除をテストする
使い捨てリソースを作成し、作成を中断し、同じ操作を繰り返し、アクセスをローテーションしてから削除します。依存サービスが存続するか、構造化された説明とともに削除を拒否することを確認します。古い認証情報が使えなくなることも確認してください。
以下のプロンプトは、プロバイダーに触れず、このプロジェクトですでに使われている一つのリソースに対して同じライフサイクルレビューを実行します。