外部エージェント

GitLab Duo Agentは並行して動作し、コードの作成、調査結果の生成、複数タスクの同時実行を支援します。

エージェントを作成し、外部AIモデルプロバイダーと連携させることで、組織のニーズに合わせてカスタマイズできます。その後、プロジェクトのイシュー、エピック、またはマージリクエストにおいて、コメントやディスカッションでその外部エージェントにメンションし、タスクの完了を依頼できます。

外部エージェントは次のことを行います:

• 周辺のコンテキストとリポジトリ内のコードを読み取り、分析する。
• プロジェクトの権限を遵守し、監査証跡を保持しながら、実行すべき適切なアクションを判断する。
• CI/CDパイプラインを実行し、すぐにマージ可能な変更またはインラインコメントのいずれかの形でGitLab上で応答する。

GitLab管理の外部エージェントのクイックスタート

次のインテグレーションはGitLabによってテストされており、利用可能です:

• Claude Code
• OpenAI Codex

エージェントを作成して外部AIモデルプロバイダーと統合する前に、GitLab Duo Agent Platformの前提条件を満たす必要があります。

管理対象の外部エージェントは、GitLabで管理された認証情報を使用し、追加のエージェント設定なしでグループで有効にできます。

次のエージェントは、AIカタログで利用できます:

• GitLabのClaude Code Agent
• GitLabのCodex Agent

ClaudeまたはCodexを有効にして使用するために必要な手順:

1. AIカタログでエージェントにアクセスします。claudeまたはcodexを検索するか、直接URLを使用します。
2. トップレベルグループでエージェントを有効にする。
3. プロジェクトでエージェントを有効にする。
4. イシュー、エピック、またはマージリクエストで外部エージェントを使用する。

前提条件

エージェントを作成して外部AIモデルプロバイダーと統合する前に、GitLab Duo Agent Platformの前提条件を満たす必要があります。

エージェントを外部AIモデルプロバイダーと統合するには、GitLabが提供および管理するアクセス認証情報も必要です。

アクセス認証情報

外部エージェントは、AIゲートウェイを介してGitLabで管理された認証情報を使用します。

GitLab管理の認証情報を使用する場合:

• 外部エージェント設定でinjectGatewayToken: trueを設定します。
• GitLab AIゲートウェイのプロキシエンドポイントを使用するように外部エージェントを設定します。

injectGatewayTokenがtrueの場合、次の環境変数が自動的に挿入されます:

• AI_FLOW_AI_GATEWAY_TOKEN: AIゲートウェイの認証トークン
• AI_FLOW_AI_GATEWAY_HEADERS: APIリクエスト用に整形されたヘッダー

GitLab管理の認証情報は、Anthropic ClaudeとOpenAI Codexでのみ使用できます。

サポートされているモデル

次のAIモデルがサポートされています:

Anthropic Claude:

• claude-3-haiku-20240307
• claude-haiku-4-5-20251001
• claude-sonnet-4-20250514
• claude-sonnet-4-5-20250929

OpenAI Codex:

• gpt-5
• gpt-5-codex

CI/CD変数を設定する

まず、変数をプロジェクトに追加します。これらの変数は、GitLabがサードパーティプロバイダーに接続する方法を決定します。

前提条件:

• プロジェクトのメンテナーロール以上が必要です。

プロジェクト設定で変数を追加または更新するには、次の手順に従います:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > CI/CDを選択します。
3. 変数を展開します。
4. 変数を追加を選択し、フィールドに入力します:

   • タイプ: **変数（デフォルト）**を選択します。

   • 環境: **すべて（デフォルト）**を選択します。

   • 表示レベル: 目的の表示レベルを選択します。

     パーソナルアクセストークン変数の場合は、マスクするまたはマスクして非表示を選択します。

   • 変数の保護チェックボックスをオフにします。

   • 変数参照を展開チェックボックスをオフにします。

   • 説明（オプション）: 変数の説明を入力します。

   • キー: CI/CD変数の環境変数名（例: GITLAB_HOST）を入力します。

   • 値: パーソナルアクセストークンまたはホストの値。

5. 変数を追加を選択します。

詳細については、プロジェクトの設定にCI/CD変数を追加する方法を参照してください。

外部エージェントのCI/CD変数

次のCI/CD変数を使用できます:

外部エージェントを作成する

次に、外部エージェントを作成し、お使いの環境で実行するように設定します。

推奨されるワークフローは次のとおりです:

1. AIカタログでエージェントを作成します。
2. トップレベルグループのエージェントを有効にします。
3. エージェントをプロジェクトに追加し、エージェントの呼び出す方法を決定するトリガーを指定します。

この場合、サービスアカウントが作成されます。エージェントの実行時には、ユーザーのメンバーシップとサービスアカウントのメンバーシップの組み合わせが使用されます。この組み合わせは、複合IDと呼ばれます。

必要に応じて、外部エージェントを手動で作成できます。

AIカタログでエージェントを作成する

まず、AIカタログで外部エージェントを作成します。

前提条件:

• プロジェクトのメンテナーロール以上が必要です。

外部エージェントを作成するには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 自動化 > エージェントを選択します。
3. 新しいエージェントを選択します。
4. 基本情報で、次の操作を行います:
   1. 表示名に、名前を入力します。
   2. 説明に、説明を入力します。
5. 表示レベルとアクセスの下にある表示レベルで、非公開または公開を選択します。
6. 設定で、次の操作を行います:
   1. 外部を選択します。
   2. 外部エージェント設定を入力します。独自のYAMLを作成するか、サンプル設定を編集できます。
7. エージェントを作成を選択します。

外部エージェントがAIカタログに表示されます。

トップレベルグループでエージェントを有効にする

次に、トップレベルグループでエージェントを有効にします。

前提条件:

• グループのオーナーロールが必要です。

トップレベルグループで外部エージェントを有効にするには:

1. 上部のバーで、検索または移動先 > 検索を選択します。
2. AIカタログを選択し、次にエージェントタブを選択します。
3. 有効にする外部エージェントを選択します。
4. 右上隅で、グループで有効にするを選択します。
5. ドロップダウンリストから、外部エージェントを有効にするグループを選択します。
6. 有効化を選択します。

外部エージェントがグループの自動化 > agentページに表示されます。

グループ内にサービスアカウントが作成されます。アカウントの名前は、次の命名規則に従います: ai-<agent>-<group>。

プロジェクトで有効にする

前提条件:

• プロジェクトのメンテナーロール以上が必要です。
• エージェントは、プロジェクトのトップレベルグループで有効になっている必要があります。

プロジェクトで外部エージェントを有効にするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 自動化 > エージェントを選択します。
3. 右上隅で、グループからのエージェントを有効にするを選択します。
4. ドロップダウンリストから、有効にする外部エージェントを選択します。
5. トリガーを追加で、外部エージェントをトリガーするイベントタイプを選択します:
   • メンション: イシューまたはマージリクエストのコメントでサービスアカウントユーザーがメンションされたとき。
   • アサイン: サービスアカウントユーザーがイシューまたはマージリクエストにアサインされたとき。
   • レビュアーをアサインする: サービスアカウントユーザーがレビュアーとしてマージリクエストにアサインされたとき。
6. 有効化を選択します。

外部エージェントがプロジェクトの自動化 > agentリストに表示されます。

トップレベルグループのサービスアカウントがプロジェクトに追加されます。このアカウントには、デベロッパーロールが割り当てられます。

外部エージェントを使用する

前提条件:

• プロジェクトのデベロッパーロール以上が必要です。
• AIカタログから外部エージェントを作成した場合、プロジェクトでそのエージェントを有効にする必要があります。
• エージェントがワークロードブランチ（workloads/*）にプッシュできるようにするには、ブランチルールの作成が必要になる場合があります。

1. プロジェクトで、イシュー、マージリクエスト、またはエピックを開きます。

2. サービスアカウントユーザーにメンション、割り当て、またはレビューをリクエストします。例:

   @service-account-username Can you help analyze this code change?

3. 外部エージェントがタスクを完了すると、確認メッセージが表示され、すぐにマージ可能な変更またはインラインコメントが表示されます。

外部エージェントを手動で作成する

UIのワークフローに従わない場合は、外部エージェントを手動で作成できます:

1. プロジェクトに設定ファイルを作成します。
2. サービスアカウントを作成します。
3. エージェントの呼び出す方法を決定するトリガーを作成します。
4. エージェントを使用します。

この場合、エージェントの実行に使用されるサービスアカウントを手動で作成します。

設定ファイルを作成する

手動で設定ファイルを追加して外部エージェントを作成する場合は、外部エージェントごとに異なる設定ファイルを作成する必要があります。

前提条件:

• プロジェクトのデベロッパーロール以上が必要です。

設定ファイルを作成するには:

1. プロジェクトで、YAMLファイルを作成します。例: .gitlab/duo/flows/claude.yaml
2. いずれかの設定ファイルの例を使用してファイルにデータを入力します。

サービスアカウントを作成する

外部エージェントを使用するプロジェクトへのアクセス権を持つサービスアカウントを作成する必要があります。

エージェントの実行時には、ユーザーのメンバーシップとサービスアカウントのメンバーシップの組み合わせが使用されます。この組み合わせは、複合IDと呼ばれます。

前提条件:

• GitLab.comでは、プロジェクトが属するトップレベルグループのオーナーロールが必要です。
• GitLab Self-ManagedおよびGitLab Dedicatedでは、次のいずれかが必要です:
  • インスタンスへの管理者アクセス権。
  • トップレベルグループのオーナーロールおよびサービスアカウントを作成する権限。

サービスアカウントを作成して割り当てるには:

トリガーを作成する

次に、外部エージェントがいつ実行されるかを定義するトリガーを作成する必要があります。

たとえば、ディスカッションでサービスアカウントにメンションしたとき、またはサービスアカウントをレビュアーとしてアサインしたときに、エージェントがトリガーされるよう指定できます。