外部エージェント

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

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

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

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

前提条件

• GitLab Duo Agent Platformの前提条件を満たしていること。
• フロー実行を有効にする。
• 外部エージェントが有効になっている必要があります。

セキュリティに関する考慮事項

外部エージェントはサードパーティのAIモデルプロバイダーと統合し、GitLabに組み込まれているエージェントやフローとは異なるセキュリティ特性を持っています。外部エージェントを使用すると、以下のリスクを許容することになります:

• Prompt injection vulnerabilities: GitLabは、プロンプトインジェクションのリスクを軽減するために、サードパーティのプロンプトスキャンを実装しています。このスキャンは外部エージェントでは利用できません。
• Third-party provider dependency: 外部のAIモデルプロバイダーが、すべてのセキュリティコントロール（プロンプトスキャン、モニタリング、およびアラートを含む）を管理しており、GitLabではありません。
• Network access: 外部エージェントは、サードパーティのAIプロバイダーに対してネットワーク呼び出しを行います。これらのプロバイダーに送信されるデータは、プロバイダーのセキュリティポリシーおよびデータ処理慣行に従います。
• Limited isolation: 外部エージェントは、GitLabネイティブのエージェントやフローに適用されるものと同じレベルのネットワーク分離およびセキュリティ制限を持っていません。

組織で外部エージェントを有効にする前に、セキュリティ要件と選択したAIモデルプロバイダーが提供するセキュリティドキュメントを確認してください。

GitLab Duo Agent Platformにおけるセキュリティ上の脅威と軽減策のより広範な概要については、GitLab Duo Agent Platformのセキュリティ脅威に関するドキュメントを参照してください。

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

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

• Claude Code
• OpenAI Codex
• Amazon Q
• Gemini

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

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

管理エージェントを有効にして使用するために必要な手順:

1. AIカタログでエージェントにアクセスします。エージェント名を検索するか、直接URLを使用します。

   GitLabマネージドの外部エージェントには、GitLabが管理するバッジ（ ）が表示されます。

2. エージェントを有効にする。

3. 外部エージェントを使用する（イシュー、エピック、またはマージリクエスト内で）。

Claudeコードエージェント

GitLabによるClaude Code Agentは、GitLabが管理する認証情報を使用し、追加の設定を必要としません。

Codexエージェント

GitLabによるCodex Agentは、GitLabが管理する認証情報を使用し、追加の設定を必要としません。

Amazon Q Developerエージェント

Amazon Q Developer Agentは、GitLabが管理する認証情報を使用しません。このエージェントを使用するには、独自の認証情報を提供する必要があります。

Amazon Q Developerエージェントを使用するには:

• プロジェクトのCI/CD設定に次の環境変数を追加します:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION_NAME
  • AMAZON_Q_SIGV4

Geminiと連携するエージェント

Develop with Gemini Agentは、GitLabが管理する認証情報を使用しません。このエージェントを使用するには、独自の認証情報を提供する必要があります。

Develop with Geminiエージェントを使用するには:

• プロジェクトのCI/CD設定に次の環境変数を追加します:

  • GOOGLE_CREDENTIALS - Googleの認証情報JSONファイルの場所を追加します。詳細については、GOOGLE_APPLICATION_CREDENTIALS環境変数を参照してください。
  • GOOGLE_CLOUD_PROJECT
  • GOOGLE_CLOUD_LOCATION

GitLabマネージドのエージェントを他のインスタンスに追加する

管理者は、ClaudeエージェントおよびCodexエージェントをGitLabインスタンスに追加できます。

前提条件:

• 管理者である必要があります。

外部エージェントをインスタンスに追加するには:

sudo gitlab-rake gitlab:ai_catalog:seed_external_agents

bundle exec rake gitlab:ai_catalog:seed_external_agents

また、APIを使用して外部エージェントを追加することもできます。

アクセス認証情報

外部エージェントは、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でのみ使用できます。

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

GitLabが管理する認証情報の場合、次のAIモデルがサポートされています:

Anthropic Claude:

• claude-haiku-4-5-20251001
• claude-opus-4-5-20251101
• claude-opus-4-6
• claude-sonnet-4-20250514
• claude-sonnet-4-5-20250929
• claude-sonnet-4-6

OpenAI Codex:

• gpt-5
• gpt-5-codex
• gpt-5-mini-2025-08-07
• gpt-5.1
• gpt-5.1-2025-11-13
• gpt-5.1-codex
• gpt-5.2-2025-12-11
• gpt-5.3-codex
• gpt-5.4-2026-03-05
• gpt-5.4-mini
• gpt-5.4-nano

CI/CD変数を設定する

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

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。

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

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

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

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

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

     APIキーおよびパーソナルアクセストークンの変数には、マスクするまたはマスクして非表示を選択します。

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

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

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

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

   • 値: APIキー、パーソナルアクセストークン、またはホストの値を入力します。

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

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

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

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

IDトークンで認証する

サードパーティのOpenID Connect（OIDC）サービスでカスタム外部エージェントを認証するには、エージェントの設定でIDトークンを宣言します。GitLab CI/CDは、署名付きJSONウェブトークン（JWT）を生成し、それをエージェントジョブに挿入します。

長期の認証情報を保存することなく認証するには、IDトークンを使用します。例えば、シークレットマネージャーからシークレットを取得することや、アーティファクトに署名することができます。

IDトークンを設定するには、外部エージェントの設定にid_tokensブロックを追加します。各トークンには、aud（オーディエンス）クレームが必要です:

injectGatewayToken: true
image: node:22-slim
commands:
  - my-authentication-script.sh "$VAULT_ID_TOKEN"
id_tokens:
  VAULT_ID_TOKEN:
    aud: https://vault.example.com

audクレームには、単一の文字列または文字列のリストを指定できます。各トークンは、そのトークンの名前を使用する環境変数としてエージェントジョブで利用できます。

トークンのペイロードに関する詳細は、IDトークンを使用したOpenID Connect（OIDC）認証を参照してください。

エージェントを有効にする

エージェントを有効にすると、イシュー、マージリクエスト、またはディスカッションからそれをトリガーできます。

プロジェクトでエージェントを有効にすると、そのプロジェクトのトップレベルグループでも同時に有効になります。

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。

外部エージェントは、グループおよびプロジェクトのAI > エージェントページに表示されます。トップレベルグループ内の任意のプロジェクトのメンバーは、自分のプロジェクトでエージェントを有効にできるようになりました。

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

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

外部エージェントがすでにトップレベルグループで有効になっている場合、そのグループのプロジェクトで有効にすることができます。

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。
• プロジェクトのトップレベルグループでエージェントを有効にする必要があります。

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

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 左側のサイドバーで、AI > エージェントを選択します。
3. 右上隅で、グループからのエージェントを有効にするを選択します。
4. ドロップダウンリストから、有効にする外部エージェントを選択します。
5. トリガーを追加で、以下を選択します:
   • 1つ以上のトリガーイベントタイプ。
   • トリガーイベントタイプに必要な場合は、トリガーイベントアクション。
6. 有効化を選択します。

外部エージェントは、プロジェクトのAI > エージェントリストに表示されます。

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

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

前提条件:

• プロジェクトのデベロッパー、メンテナー、またはオーナーロールが必要です。
• GitLabが管理する外部エージェントおよびAIカタログで作成されたカスタム外部エージェントの場合、外部エージェントはプロジェクトで有効になっている必要があります。
• エージェントが作成したブランチ（^duo/(fix|feature|refactor|docs/).*`で始まるブランチ）に対してエージェントがプッシュできるようにするには、ブランチルールの作成が必要になる場合があります。

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

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

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

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

カスタム外部エージェントを作成する

GitLab Self-Managedでは、ai_catalog_create_third_party_flows機能フラグが有効になっている場合、AIカタログを使用して外部エージェントを作成し、環境で実行するように設定できます。

GitLab.comでは、カスタム外部エージェントを作成できません。代わりに、GitLabが管理する外部エージェントを使用してください。

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

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

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

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

エージェントの表示レベル

カスタム外部エージェントを作成する際に、それを管理するプロジェクトを選択し、エージェントを公開するか非公開にするかを決定します。

公開エージェント:

• 誰でも閲覧でき、前提条件を満たすすべてのプロジェクトで有効にできます。

非公開エージェント:

• ゲスト、プランナー、レポーター、デベロッパー、メンテナー、またはオーナーのロールを持つ管理プロジェクトのメンバーのみが閲覧できます。
• 管理対象プロジェクト以外のプロジェクトでは有効にできません。

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

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

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。

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

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

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

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

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

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

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

設定ファイルを作成する

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

前提条件:

• プロジェクトのデベロッパー、メンテナー、またはオーナーロールが必要です。

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

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

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

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

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

前提条件:

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

外部エージェントをメンションする各プロジェクトには、それぞれ一意のグループサービスアカウントが必要です。外部エージェントにタスクを割り当てる際は、サービスアカウントのユーザー名をメンションしてください。

AIカタログから外部エージェントを作成し、トップレベルグループで有効にすると、ai-<agent>-<group>という名前のサービスアカウントが自動的に作成されます。たとえば、Claude code agentという名前のエージェントをGitLab Duoグループで有効にした場合、サービスアカウント名はai-claude-code-agent-gitlab-duoになります。

サービスアカウントをセットアップするには、次の手順に従います。十分な権限がない場合は、インスタンス管理者またはトップレベルグループのオーナーにサポートを依頼してください。

1. トップレベルグループで利用するためのサービスアカウントを作成します。インスタンス用に作成されたサービスアカウントはサポートされていません。

   既存のサービスアカウントを外部エージェントとして設定する場合、そのアカウントにはパーソナルアクセストークンを関連付けることはできません。この動作は、サービスアカウントのセキュリティを維持することを目的としています。

2. 次のスコープを指定して、サービスアカウントのパーソナルアクセストークンを作成します:

   • write_repository
   • api
   • ai_features

3. サービスアカウントをプロジェクトに追加し、デベロッパーロールを付与します。これにより、サービスアカウントに必要最小限の権限が付与されます。

サービスアカウントをプロジェクトに追加する際は、サービスアカウントの正確な名前を入力する必要があります。誤った名前を入力すると、外部エージェントは機能しません。

トリガーを作成する

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

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

外部エージェントの有効/無効を切り替える

デフォルトでは、外部エージェントは有効になっています。トップレベルグループまたはインスタンスでオン/オフを切り替えることができます。

外部エージェントが無効の場合:

• ユーザーは外部エージェントの作成、有効化、無効化、変更、または実行ができません。これにはGitLabが管理する外部エージェントと、カスタム外部エージェントの両方が含まれます。
• 既存の外部エージェントは、プロジェクトのAI > エージェント > 有効の下には表示されなくなります。
• プロジェクトで作成された外部エージェントは、AI > エージェント > 管理中の下に表示されますが、変更または実行することはできません。
• カスタムエージェントと基本エージェントは引き続き利用可能です。