コーディング エージェント用のエンタープライズ API ゲートウェイを構築する方法
IDE、リポジトリ、サンドボックス、MCP ツール、シークレット、モデル プロバイダー、予算全体でコーディング エージェントを管理するための実用的なリファレンス アーキテクチャ。
コーディング エージェントは単なる LLM リクエストではありません。ソース コードを読み取り、ファイルを変更し、シェル コマンドを実行し、ツールを呼び出し、プル リクエストをオープンし、多くのモデル ターンにわたってタスクを継続できます。実行環境がシークレットや無制限のネットワーク アクセスを公開している場合、エージェントはそれらにも触れる可能性があります。
これにより、ゲートウェイの問題が変わります。通常の LLM ゲートウェイは、API 件の呼び出しを認証し、モデルをルーティングし、トークンを測定し、支出制限を適用できます。コーディング エージェント API ゲートウェイにはこれらの制御が必要ですが、モデル呼び出しに関するワークロード (リポジトリ アクセス、サンドボックス分離、ツール権限、資格情報交換、ネットワーク下り、承認フロー、タスク レベルの監査証跡など) も管理する必要があります。
この記事では、エンタープライズ コーディング エージェント コントロール プレーンの実用的なリファレンス アーキテクチャを定義します。これは、IDE、GitHub ワークフロー、CLI ツール、およびマネージド サンドボックス全体にエージェントを展開するエンジニアリング リーダーとプラットフォーム チーム向けに書かれています。
コントロール プレーンの境界
ゲートウェイは、人間の開発者、エージェント ランタイム、モデル プロバイダー、リポジトリ、MCP サーバー、シークレット ストア、内部ネットワークの間に配置する必要があります。チャットの完了や模範的な応答のプロキシに限定されるべきではありません。
実際には、コントロール プレーンは各エージェント タスクの前およびタスク中に 7 つの質問に答える必要があります:
- このエージェントは誰のために、または何のために行動しているのですか?
- どのリポジトリ、ブランチ、ファイル、パッケージ レジストリにアクセスできますか?
- どのシェル コマンド、MCP ツール、およびネットワーク宛先が許可されますか?
- どの認証情報を、どのような目的で、どのくらいの期間発行できますか?
- どのモデル階層、予算、ターン制限が適用されますか?
- 人間の承認が必要なアクションはどれですか?
- どのようなトレース、使用状況、監査レコードをエクスポートする必要がありますか?
これにより、コーディング エージェント ゲートウェイはより広範な エンタープライズ LLM API インフラストラクチャ の一部になりますが、適用面が異なります。モデル呼び出しはワークロードの 1 ステップにすぎません。
リファレンス アーキテクチャ
実行可能なアーキテクチャには、ID、ポリシー、サンドボックス、認証情報ブローカー、モデル ゲートウェイ、監査および使用状況台帳の 6 つの層があります。これらの層はさまざまな製品で実装できますが、責任は分離したままにする必要があります。
1.アイデンティティレイヤー
ID レイヤーは、すべてのエージェント タスクに、属性の付与、制約、取り消しが可能な永続的な ID を与えます。すべてのタスクを同じように見せる共有開発者 API キーや汎用サービス アカウントは避けてください。
各タスクには少なくとも次のものを含める必要があります:
- アクター: タスクを開始したユーザー、サービス、またはオートメーション。
- エージェント サーフェス: IDE 拡張機能、CLI、GitHub エージェント、CI ジョブ、またはマネージド サンドボックス。
- リポジトリのスコープ: 組織、リポジトリ、ブランチ、作業ディレクトリ。
- 環境: 開発、テスト、ステージング、または本番環境。
- チームとコストセンター: 承認、報告、予算執行のため。
- タスク ID: モデル呼び出し、ツール呼び出し、シェル コマンド、プル リクエスト アクティビティにわたる安定した識別子。
最も強力なパターンは、有効期間の短いトークンを使用したエージェントごとまたはワークロードごとの ID です。 Workload Identity フェデレーションは、エージェントが有効期間の長いプロバイダー キーを運ぶ代わりに、信頼されたアサーションを有効期間の短いトークンと交換できるため、ここで役立ちます。専用のプリンシパル、正確なクレームの一致、最小限の権限、本番環境と非本番環境の ID の分離を使用します。
2.ポリシー層
ポリシー層はワークロードの決定点です。モデルアクセス以上のものを評価する必要があります。コーディング エージェントは、モデル リクエスト自体が無害であるように見えても、シェル コマンド、MCP ツール、パッケージ公開ステップ、またはネットワーク呼び出しを通じて損害を与える可能性があります。
ポリシーは以下をカバーする必要があります:
- リポジトリの許可リストとブランチの制限。
- 読み取り、書き込み、テスト、コミット、プル リクエストの権限。
- 許可されるシェル コマンド クラスと許可されないシェル コマンド クラス。
- MCP サーバーの検出、接続、およびツールの呼び出し。
- 送信ネットワーク モード: 無効、制限、または例外によりオープン。
- 目的地、目的、環境、寿命ごとの秘密のアクセス。
- モデル階層、最大ターン数、最大ツール呼び出し数、および予算制限。
- 危険な行為には人間の承認が必要です。
ポリシー決定ポイントは、モデルの呼び出し前だけでなく、ツールの実行前にも呼び出す必要があります。たとえば、エージェントはモデルに移行計画を求めることは許可されますが、運用データベース コマンドの実行やパッケージの公開はブロックされる場合があります。
3.サンドボックス レイヤ
サンドボックスは、ファイルシステム、シェル、パッケージ、およびネットワーク アクセスの実行境界です。コンビニエンス コンテナではなく、ワークロード環境として扱う必要があります。
実際のセグメンテーション モデルは次のとおりです:
- 低リスクの読み取り専用タスク: ユーザーまたはリポジトリごとに分離され、秘密はなく、ネットワークが制限されています。
- コード変更タスク: 分離された書き込み可能なワークスペース、リポジトリ スコープのトークン、テスト専用の認証情報。
- インフラストラクチャ タスク: 個別の強化されたサンドボックス、厳格な承認、本番環境のデフォルトなし。
- 本番環境に隣接するタスク: まれで、期限があり、大量にログが記録され、通常の開発者エージェントから分離されます。
意図的な共有でない限り、関係のないエージェントに書き込み可能なファイル システム、キャッシュ、資格情報、またはパッケージ レジストリを共有させないでください。共有キャッシュは速度を向上させますが、同時にタスク間の汚染を引き起こし、フォレンジック分析を困難にします。
ネットワーク下りは明示的である必要があります。一部のタスクには、パッケージ レジストリ、ドキュメント サイト、内部アーティファクト ストア、またはテスト サービスが必要です。これには、任意の送信アクセスは必要ありません。可能な場合は制限されたホスト許可リストを使用し、実際の宛先をログに記録します。
4.認証情報ブローカー
認証情報ブローカーは、長期間有効な秘密をサンドボックスの外に保持します。エージェントは、開発者ワークフローで実行されているという理由だけで、広範なクラウド キー、ソース管理管理者トークン、または運用アプリケーションのシークレットを受け取ってはなりません。
ブローカーは、ポリシーの承認後にのみ、有効期間が短く、範囲が限定された認証情報を発行する必要があります。ブローカーへのリクエストには、タスク ID、リポジトリ、宛先、要求された権限、および意図された操作が含まれている必要があります。
便利なブローカー パターンは次のとおりです:
- リポジトリ トークンは 1 つのリポジトリに制限されており、有効期限が短いです。
- パッケージ レジストリ トークンは、公開ではなくインストール操作に限定されます。
- クラウド認証情報は、非運用アカウントと読み取り専用アクションに限定されます。
- データベース認証情報はテスト環境に限定されます。
- 特定のアーティファクトに対する署名付き URL または一時的なアクセス許可。
ブローカーは曖昧なリクエストを拒否する必要があります。 「このエージェントに AWS アクセスを許可する」は安全なポリシー単位ではありません。 「このタスクに特定のステージング オブジェクト ストア パスの読み取りを 15 分間許可する」は、管理可能な単位に近いです。
5.モデルゲートウェイ
モデル ゲートウェイは依然として重要です。コーディング エージェントは、計画ループ、繰り返しのファイル読み取り、テストの失敗、ツールの出力、および再試行を通じて大量のトークンを生成する可能性があります。ゲートウェイは、認証、モデル ルーティング、予算の適用、使用状況の測定、プロバイダーの抽象化を処理する必要があります。
エージェントのワークロードの場合は、通常の API リクエストにはないフィールドを追加します:
- エージェント タスク ID。
- サンドボックス ID.
- リポジトリとブランチ。
- ツール呼び出し数。
- 最大ターン数ポリシー。
- 承認状態。
- リスク階層
- ドキュメントの更新、テスト生成、リファクタリング、依存関係のアップグレードなど、予期されるタスク クラス。
このメタデータにより、プラットフォーム チームは、すべてのモデルの使用状況を 1 つの未分化なストリームとして扱うのではなく、タスク タイプ間でコストと信頼性を比較できるようになります。また、セキュリティ チームは、インフラストラクチャの変更に関連してドキュメント エージェントが繰り返し呼び出しを行うなど、異常な使用パターンを特定することもできます。
6.監査および使用状況台帳
コーディング エージェントの監査証跡では、モデル呼び出しと実際のアクションを結び付ける必要があります。トークンの使用だけでは十分ではありません。
以下を含むタスク トレースをエクスポートします:
- 誰がどの面からタスクを開始したか。
- 使用されたモデル プロバイダーとモデル層。
- トークンの使用量、レイテンシー、エラー、コストの見積もり。
- リポジトリ、ブランチ、およびファイルがタッチされました。
- シェル コマンドが提案、承認、拒否、および実行されました。
- MCP 台のサーバーとツールが呼び出されました。
- ネットワーク宛先に到達したか、ブロックされました。
- 認証情報が要求、発行、拒否され、期限切れになりました。
- Pull リクエスト、コミット、コメント、または問題が作成されました。
- 最終タスクの結果: 完了、放棄、ブロック、取り消し、またはエスカレーション。
保持には注意が必要です。トレースには、独自のコード、プロンプト、ツール出力、エラー ログ、機密構成のフラグメントが含まれる場合があります。広範囲に展開する前に、編集、サンプリング、アクセス制御、保持を決定します。誰も安全にアクセスできない有用なトレースは、運用には役に立ちません。
ポリシーの例: ドキュメント更新エージェント
具体的なポリシーにより、アーキテクチャの評価が容易になります。プラットフォーム エンジニアリング チームが使用するドキュメント更新エージェントを検討してください。
エージェントは次のことを行うことができます:
- 承認されたドキュメント リポジトリ内のファイルを読み取ります。
- 一時的なブランチを作成します。
- マークダウン、サンプル、生成されたドキュメントを編集します。
- 例としてドキュメント テスト、リンク チェック、単体テストを実行します。
- タスク予算を持つ承認済みのモデル階層を使用します。
- 要求元の開発者に割り当てられたプル リクエストを開きます。
- 承認された MCP ツールをリポジトリ検索と課題検索に呼び出します。
エージェントは次のことを行ってはなりません:
- 本番環境の秘密にアクセスします。
- デフォルトのブランチに直接プッシュします。
- パッケージまたはコンテナ イメージを公開します。
- インフラストラクチャ展開コマンドを実行します。
- 任意の送信ホストに接続します。
- 特権付きソース管理トークンを使用します。
- 承認なしで最大ターン経過後に続行します。
このポリシーは意図的に範囲が狭いです。これでもエージェントは便利ですが、影響範囲がレビューとロールバックが簡単な作業タイプに制限されます。
実装手順
ステップ 1: エージェント サーフェスのインベントリ
コーディング エージェントが実行できるすべての場所をリストします: IDE プラグイン、CLI ツール、GitHub または Git プロバイダー エージェント、CI ワークフロー、マネージド サンドボックス、内部開発者ポータル、実験的スクリプト。現在非公式であるツールも含まれます。シャドウ導入は、プラットフォーム チームが制御モデルを構築する前にチームが有用なエージェントを見つけた場合によく発生します。
ステップ 2: タスク クラスを定義する
リスクと権限別にユースケースをグループ化します。役立つ開始クラスには、ドキュメントの変更、テスト生成、コードの説明、依存関係の更新、リファクタリング、インシデント分析、インフラストラクチャの変更、実稼働デバッグなどがあります。
各クラスは、許可されたリポジトリ、書き込み権限、ネットワーク アクセス、ツール、シークレット、モデル層、承認ルールにマップする必要があります。
ステップ 3: エージェント ID を標準化する
すべてのタスクにアクター、チーム、リポジトリ、環境、タスク ID のメタデータを含める必要があります。ツールがこれらのフィールドを直接渡すことができない場合は、それらをアタッチできるランチャー、プロキシ、またはブローカーでツールをラップします。
ステップ 4: 実行前にポリシーを置く
リポジトリ書き込みアクセス、シェル コマンド、MCP ツール呼び出し、資格情報リクエスト、アウトバウンド ネットワーク アクセス、モデル バジェットなど、価値の高い強制ポイントから始めます。強制を行わないロギングは、検出時には役立ちますが、ガバナンスではありません。
ステップ 5: シークレットをサンドボックスから移動する
エージェント環境から静的シークレットを削除します。有効期間が短い認証情報にはブローカーまたはボールト フローを使用します。宛先と目的、ログの発行と有効期限によって資格情報を制限します。
ステップ 6: エージェント対応テレメトリをエクスポートする
モデルの使用状況、ツール イベント、コマンド承認、リポジトリ アクティビティ、認証情報の発行、ネットワーク イベントを同じ分析プレーンに送信します。目的はセキュリティレビューだけではありません。これは、エンジニアリング チームや財務チームが信頼できる AI 使用状況分析でもあります。
ステップ 7: 段階的に展開
デフォルトではブロードアクセスを無効にします。選択した組織、リポジトリ、またはタスク クラスのエージェントを有効にします。読み取り専用で低リスクの書き込みワークフローから始めて、監査ログ、コスト帰属、承認パスが機能するようになったら拡張します。
事実、推奨事項、予測
事実: 現在のエージェント プラットフォームは、この方向を指すコントロールをすでに公開しています。 OpenAI ドキュメントでは、ホスト型エージェント ハーネスをサンドボックス環境から分離し、ファイル、パッケージ、シェル実行、MCP サーバー、および送信ネットワーク アクセスのサンドボックス制御について説明します。 GitHub は、エージェントの可用性、エージェント セッション、監査イベント、MCP の使用法、およびエージェント ポリシーのコーディングに関するエンタープライズ管理を文書化します。 Anthropic ドキュメント Claude 一元的な認証、使用状況追跡、コスト管理、監査ログ、モデル ルーティング、企業ネットワーク ルーティングのためのゲートウェイとプロキシ パターンをコード化します。
推奨事項: コーディング エージェントを管理されたワークロードとして扱います。エージェントごとまたはワークロードごとの ID を使用し、サンドボックスを分離し、ツールとネットワークのアクセスを制限し、認証情報を仲介し、予算とターン制限を強制し、タスク レベルのトレースをエクスポートします。モデル呼び出しの前だけでなく、実行の前にもポリシーを置きます。
予測: 導入が個人の開発者から組織全体への展開に移行するにつれて、コーディング エージェントのガバナンスは標準的なプラットフォーム エンジニアリングの責任になるでしょう。プロバイダーネイティブの制御は今後も有用ですが、複数のエージェント サーフェスとモデル プロバイダーを使用する企業には、ポリシー、レポート、コスト帰属のための正規化レイヤーが必要になります。
トレードオフ
中央ゲートウェイにより、セキュリティ、プラットフォーム、財務チームに一貫した制御が提供されますが、運用上の責任も増大します。ゲートウェイを所有するチームは、プロバイダーに直接接続するように設計された開発者ツールをサポートする必要があります。
厳密なサンドボックスとネットワーク分離により影響範囲は縮小されますが、実際のワークフローが中断される可能性があります。パッケージのインストール、プライベート レジストリ、統合テスト、および内部ドキュメントはすべてネットワーク アクセスを必要とする場合があります。答えは通常、ネットワークの全面的な禁止ではなく、可観測性を備えたアクセスの制限です。
エージェントごとの ID により帰属と取り消しが向上しますが、ライフサイクルの自動化が必要です。数千のサービス アカウントまたはキーを手動で管理すると失敗します。
ブローカー化されたシークレットは公開を減らしますが、ブローカーは重要なインフラストラクチャになります。資格情報の発行が失敗するとエージェントのワークフローが停止する可能性があり、過剰な発行はセキュリティ リスクを引き起こす可能性があるため、認証システムと同様に監視してください。
詳細なトレースはデバッグとコンプライアンスに役立ちますが、機密コードと出力をキャプチャする可能性があります。編集とアクセス制御はオプションの追加機能ではありません。
実用的な結論
コーディング エージェントを管理する実際的な方法は、コーディング エージェントをより大きなコンテキスト ウィンドウを備えたチャット セッションとして扱うのをやめることです。これらは、モデル アクセス、ファイル システム アクセス、ツール アクセス、リポジトリ アクセス、および場合によっては認証情報アクセスを備えた自律型エンジニアリング ワークロードです。
その現実に基づいてゲートウェイを構築します。各タスクにアイデンティティを与えます。ツールとシェル コマンドを実行する前にポリシーを評価します。サンドボックスを分離します。長期にわたる秘密を環境から遠ざけます。制御されたゲートウェイを介してモデル呼び出しをルーティングします。トークンの使用状況を実際のエンジニアリング アクションに結び付けるトレースをエクスポートします。
狭い範囲から始めます: 1 つのエージェント サーフェス、1 つの低リスク タスク クラス、1 セットのリポジトリ、制限されたネットワーク アクセス、運用シークレットなし、タスク レベルの監査ログ。コントロール プレーンが、誰が何をしたか、どのツールが使用されたか、コスト、何が変更されたかを表示できる場合にのみ展開します。
よくある質問
コーディング エージェント API ゲートウェイは LLM ゲートウェイと同じですか?
いいえ。 LLM ゲートウェイは、モデルのアクセス、ルーティング、使用法、コストを制御します。コーディング エージェント API ゲートウェイは、リポジトリ、シェル コマンド、MCP ツール、認証情報、ネットワーク アクセス、サンドボックス、承認、タスク トレースなど、モデル周辺の実行環境も管理します。
すべてのコーディング エージェントは独自の API キーを取得する必要がありますか?
必ずしも有効期間の長いキーである必要はありません。より強力なパターンは、ブローカーまたは Workload Identity フローを通じて発行される有効期間の短い資格情報を使用する、エージェントごとまたはワークロードごとの ID です。重要な要件は、タスクまたはワークロード レベルでの帰属と取り消しです。
ポリシーの適用はどこで行われるべきですか?
ポリシーは、モデルの呼び出し前とツールの実行前に適用する必要があります。リポジトリの書き込み、シェル コマンド、MCP 呼び出し、認証情報の要求、パッケージの公開、送信ネットワーク アクセスはすべてポリシー チェックが必要です。
最も安全な最初のロールアウトは何ですか?
ドキュメントの更新やテストの生成など、読み取り専用または低リスクの書き込みタスクから始めます。制限されたリポジトリを使用し、プロダクション シークレットを使用せず、モデルの予算を制限し、ネットワーク アクセスを制御し、マージ前のプル リクエスト レビューを使用します。