Remote SWE Agents

English | 日本語

これは完全に自律型のソフトウェア開発AIエージェントの実装例です。エージェントはクラウド上の開発環境で独立して動作するため、ノートパソコンに縛られることなく作業ができます！

主な特徴

• 完全自律型のソフトウェア開発エージェント - AI駆動の開発ワークフロー自動化
• Webベースの管理インターフェース - セッション管理とリアルタイムモニタリング用のモダンなNext.js webapp
• Slack App統合 - エージェントはSlackからも呼び出し可能です
• REST APIインターフェース - REST APIでもエージェントを操作できるため、多様なシステムと統合できます
• AWS サーバーレスサービスによる最小限のメンテナンスコスト
• システムを使用しない間は前払いや固定費用なし
• MCP サポート
• OSS フォークリポジトリでも動作可能

例

Remote SWE エージェントによるセッション例：

例1	例2	例3	例4
GitHub issueによる指示。結果のPR	単一の指示で複数のリポジトリに対応 PR#1、PR#2、PR#3	エージェントは画像の入出力も可能。	エージェントは英語以外の言語も話せます。結果のPR

Remote SWE Agentsによって作成されたプルリクエスト

エージェントによって作成された公開プルリクエストはすべてこちらで確認できます。このGitHubユーザーからプッシュされたすべてのコミットは、エージェントによって自律的に作成されています。

インストール手順

最小限の設定で簡単にデプロイするには、ワンクリックデプロイメントソリューションをご利用いただけます: AWS Sample One-Click Generative AI Solutions

前提条件

• Node.js（バージョン22以上）
• npm（バージョン9以上）
• AWS CLI
• 適切な権限を持つAWS IAMプロファイル
• Docker

---

クイックスタート

Webインターフェースでシステムを起動します。

1. リポジトリのクローン

git clone https://github.com/aws-samples/remote-swe-agents.git
cd remote-swe-agents

2. 環境変数のセットアップ

cdk ディレクトリ内にあるサンプルテンプレートから .env.local ファイルを作成してください：

cd cdk
cp .env.local.example .env.local

[!IMPORTANT] .env.local.example ファイルは cdk/ ディレクトリ内にあります。デプロイ前にこのファイルをコピーして編集してください。

cdk/.env.local を編集して、以下のオプション設定を行います：

Webappユーザー作成（推奨）

デプロイ中に初期webappユーザーを自動作成できます：

INITIAL_WEBAPP_USER_EMAIL=your-email@example.com

設定すると、デプロイ中にCognitoユーザーが作成され、指定されたメールアドレスに一時パスワードが送信されます。

この変数を設定しない場合は、後でAWS Cognitoマネジメントコンソールを通じて手動でユーザーを作成できます。AWS管理コンソールでの新しいユーザーの作成を参照してください。

その他のオプション設定

ワーカーインスタンス設定

ワーカーインスタンスロールにアタッチする追加のマネージドポリシーを設定できます。AWSマネージドポリシーの名前とARN形式の両方を設定できます：

WORKER_ADDITIONAL_POLICIES=AmazonS3ReadOnlyAccess,arn:aws:iam::123456789012:policy/CustomPolicy

既存VPCの使用

新しいVPCを作成する代わりに既存のVPCを使用する場合は、VPC IDを指定します：

VPC_ID=vpc-12345abcdef

Bedrock クロスリージョン推論

クロスリージョン推論プロファイルのリージョンを選択します（デフォルト: us）：

BEDROCK_CRI_REGION_OVERRIDE=global  # global, us, eu, apac, jp, au から選択

[!NOTE] 一部のモデル（例：Opus 4.5）は global プロファイルが必要です。

[!NOTE] ここでは、GitHub Actions変数から設定を注入するために環境変数を使用しています。これが便利でない場合は、bin/cdk.ts内の値を直接ハードコードすることもできます。

3. デプロイ

cd cdk && npm ci
npx cdk bootstrap
npx cdk deploy --all

デプロイには通常約10分かかります。

以上です！ デプロイ後、CDKスタック出力に表示されるWebappUrlを通じてwebappにアクセスできます。この時点では、WebインターフェースとAPIを通じてシステムを利用でき、エージェントはタスクを実行できますが、次のステップでGitHub連携を設定するまでGitHubへのアクセスはできません。

---

オプション：GitHub連携

エージェントがGitHubリポジトリとやり取り（クローン、PR作成など）できるようにするには、以下のいずれかのオプションを設定します。

どちらのオプションを選ぶべきか？

• Personal Access Token（オプションA）：個人利用向けのシンプルなセットアップ。単一のユーザーアカウントに紐づけられます。
• GitHub App（オプションB）：チームや組織での利用に推奨。より詳細な権限設定が可能で、個人アカウントに紐づけられません。

オプションA：Personal Access Token (PAT)

1. GitHub設定 > 開発者設定 > 個人アクセストークンにアクセス
2. 適切なリポジトリアクセス権を持つ新しいトークン（クラシック）を生成
3. 必要なスコープ：repo, workflow, read:org
4. 許可するスコープが多いほど、エージェントがさまざまなタスクを実行できます
5. 生成したトークン文字列でSSMパラメータを作成（$TARGET_ENV はデプロイ環境名、例: Sandbox）： bash aws ssm put-parameter \ --name /remote-swe/$TARGET_ENV/github/personal-access-token \ --value "your-access-token" \ --type String
6. cdk/bin/cdk.ts のスタックpropsにGitHub設定を追加： typescript github: { personalAccessTokenParameterName: `/remote-swe/${targetEnv}/github/personal-access-token`, },

[!NOTE] システムを複数の開発者と共有したい場合、個人の権限の悪用を防ぐために、自分のアカウントのPATを使用するのではなく、GitHubのマシンユーザーアカウントを作成することをお勧めします。

オプションB：GitHub App

1. GitHub設定 > 開発者設定 > GitHub Appsにアクセス
2. 新しいGitHub Appを作成
3. 権限を設定し、秘密鍵を生成
4. 必要な権限：Actions(RW)、Issues(RW)、Pull requests(RW)、Contents(RW)
5. 秘密鍵用のSSMパラメータを作成（$TARGET_ENV はデプロイ環境名）： bash aws ssm put-parameter \ --name /remote-swe/$TARGET_ENV/github/app-private-key \ --value "$(cat your-private-key.pem)" \ --type String
6. 使用したいGitHub組織にアプリをインストール
7. アプリをインストールした後、URL（https://github.com/organizations/<YOUR_ORG>/settings/installations/<INSTALLATION_ID>）からインストールIDを確認できます
8. cdk/.env.local に以下の環境変数を設定： sh GITHUB_APP_ID=your-github-app-id GITHUB_INSTALLATION_ID=your-github-installation-id
9. cdk/bin/cdk.ts のスタックpropsにGitHub設定を追加： typescript github: { privateKeyParameterName: `/remote-swe/${targetEnv}/github/app-private-key`, appId: process.env.GITHUB_APP_ID!, installationId: process.env.GITHUB_INSTALLATION_ID!, },

[!NOTE] 現在、GitHub Appを使用する場合、単一の組織（つまり、アプリのインストール）の下のリポジトリのみを使用できます。

再デプロイ

GitHub連携を設定した後、再デプロイします：

cd cdk && npx cdk deploy --all

---

オプション：Slack連携

Slackボット機能を有効にして、Slackから直接エージェントとやり取りできるようにします。

Slackアプリの作成

1. Slack Appsダッシュボードにアクセス
2. 「Create New App」（新しいアプリを作成）をクリック
3. 「From manifest」（マニフェストから）を選択
4. 提供されているSlackアプリのマニフェストYAMLファイルを使用：manifest.json
5. Slackワークスペース管理者がより広い権限をボットに付与することを許可している場合は、slack-app-manifest-relaxed.jsonも利用できます。これを使うと、botにメンションをしなくても、Slackスレッド内でエージェントと会話することができます。
6. エンドポイントURL（https://redacted.execute-api.us-east-1.amazonaws.com）を実際のURLに置き換えてください
7. 実際のURLはCDKデプロイメント出力のSlackBoltEndpointUrlで確認できます（Slack有効化デプロイ後）
8. 注意: Slack有効化の初回デプロイ後にこのURLを更新する必要があります
9. 以下の値を必ずメモしておいてください：
10. 署名シークレット（Basic Informationで確認可能）
11. ボットトークン（OAuth & Permissions内、ワークスペースにインストール後に確認可能）

詳細については、こちらのドキュメントを参照してください：マニフェストでアプリを作成および設定する

Slack用SSMパラメータの作成

SlackのシークレットをAWSアカウントに登録します（$TARGET_ENV はデプロイ環境名）：

aws ssm put-parameter \
    --name /remote-swe/$TARGET_ENV/slack/bot-token \
    --value "your-slack-bot-token" \
    --type String

aws ssm put-parameter \
    --name /remote-swe/$TARGET_ENV/slack/signing-secret \
    --value "your-slack-signing-secret" \
    --type String

CDK設定の更新

cdk/bin/cdk.ts のスタックpropsにSlack設定を追加：

slack: {
  botTokenParameterName: `/remote-swe/${targetEnv}/slack/bot-token`,
  signingSecretParameterName: `/remote-swe/${targetEnv}/slack/signing-secret`,
},

（オプション）Slackからのアクセス制限

Slackワークスペース内のどのメンバーがエージェントにアクセスできるかを制御するには、cdk/.env.local にSlackユーザーIDのカンマ区切りリストを記述します：

SLACK_ADMIN_USER_ID_LIST=U123ABC456,U789XYZ012

[!NOTE] 共有（個人ではなく）Slackワークスペースを使用している場合は、エージェントへのアクセスを制御するためにSLACK_ADMIN_USER_ID_LISTの設定を推奨します。この制限がないと、ワークスペース内の誰でもエージェントにアクセスでき、潜在的にあなたのGitHubコンテンツにもアクセスできてしまいます。

[!NOTE] デプロイ後にユーザーにアプリへのアクセス権を付与するには、approve_userメッセージとユーザーのメンションをアプリでメンションします。例：@remote-swe approve_user @Alice @Bob @Carol

再デプロイ

cd cdk && npx cdk deploy --all

完了です！ これでWebインターフェースに加えてSlackボット機能も利用できます。

---

デプロイしたシステムへのアクセス

デプロイが成功した後、以下の方法でRemote SWE Agentsシステムにアクセスできます：

1. Webインターフェース：CDKスタック出力の webapp URL にアクセス（出力でWebappUrlを探してください）
2. セッション管理用のモダンなWebダッシュボードにアクセス
3. エージェントセッションをリアルタイムで作成・監視
4. コスト分析とシステム使用状況の確認

5. 画像のアップロードと設定管理

6. Slackインターフェース（設定済みの場合）：Slackアプリをメンションするだけで、エージェントにタスクを割り当て開始

7. Slackワークスペースとの直接統合
8. エージェントとのスレッドベースの会話

9. リアルタイムの進捗更新

10. APIアクセス：プログラマティック統合用のRESTful APIエンドポイントを使用

11. セッションの作成と管理
12. 自動化されたワークフローとCI/CD統合

13. カスタムアプリケーションの開発

14. GitHub Actions統合（GitHub設定済みの場合）：GitHub Actionsを使用してリポジトリと統合

15. GitHub イベントからエージェントを自動的にトリガー
16. issue コメントやアサインメントに対応
17. シームレスなCI/CD統合

エージェントを効果的に使用するためのヒントについては、以下の「有用なヒント」セクションを参照してください。

GitHub Actions統合

このリポジトリはGitHub Actionとして使用でき、issueコメント、アサイン、PRレビューなどのGitHubイベントから自動的にRemote SWEエージェントをトリガーできます。GitHub ActionはRemote SWE API機能を使用してエージェントセッションを作成・管理します。

ワークフローでaws-samples/remote-swe-agentsを使用し、APIベースURLとキーをリポジトリシークレットとして設定してください。APIキーはデプロイされたwebappインターフェースから生成できます。入力パラメータについてはaction.ymlを、完全なワークフロー例については.github/workflows/remote-swe.ymlを参照してください。

アクセス制御（またはテナント分離モデル）

このプロジェクトは現在、シングルテナントシステムとして設計されており、テナントごとにデプロイすることを想定しています。

完全従量課金制モデルに従っているため、複数のインスタンスをデプロイするオーバーヘッドは、インフラストラクチャコストの観点では最小限です。

各テナントのアクセスを制御するために、以下のアクセス許可設定があります：

1. Slackアプリ：CDKでSLACK_ADMIN_USER_ID_LIST環境変数を設定して、許可されていないユーザーからのアクセスを拒否できます。その後、approve_user Slackコマンドを使用して許可されたユーザーを追加できます。
2. Webapp：Cognitoのセルフサインアップはデフォルトで無効になっています。Cognito管理コンソールからユーザーを追加できます。現在、Cognitoアカウントを持つ人は誰でも同等の権限を持ちます。ユーザーはWeb UIからシステムの設定、新しいセッションの作成、APIキーの発行、またはコスト分析の確認ができます。さらに、AWS WAFを使用してIPアドレス制限を適用し、Webインターフェースへのアクセスをさらに制限することもできます。
3. REST API：APIキーを知っている人は誰でもアクセスできます。使用されなくなったキーは削除する必要があります。追加のセキュリティとして、AWS WAFを使用してIPアドレス制限を実装することもできますが、これによりGitHub Actionsなどのパブリックランナーを使用するCI/CD環境からAPIを利用する能力が制限される可能性があることに注意してください（これらは動的IPアドレスを使用するため）。
4. GitHub Actions：リポジトリへの書き込みアクセス権を持つ人（つまり、コラボレーター）は誰でもアクションを呼び出すことができます。

有用なヒント

プロンプトのベストプラクティス

エージェントを起動するとき、指示には少なくとも以下の内容を含めるべきです：

1. エージェントが見るべきGitHubリポジトリ
2. 解決したい機能またはバグの説明
3. 最初にチェックすべきファイル（ファイルパスが最適ですが、キーワードのみでも機能します）

ワークフローを簡素化するために、上記の情報を含むGitHub issueをリポジトリに作成し、エージェントにそのURLを渡すことができます。 この方法では、リポジトリはURLから自動的に推測され、新しいPRを対応するissueにリンクすることもできます。

Web UIによるグローバル設定

デプロイされたWeb UIを通じて、すべてのエージェントのグローバル設定を行うことができます。これらの設定はWebインターフェースとSlackの両方から起動されるエージェントに適用されます：

1. デフォルトの基盤モデル: 新しいエージェントセッションがすべて使用するデフォルトの基盤モデルを設定できます。最新の利用可能なモデルの一覧は、models.tsを参照してください。

2. 共通エージェントプロンプト: すべてのエージェントが使用する共有システムプロンプトを設定できます。これは組織全体のコーディング規約、推奨ライブラリ、またはすべての開発タスクに適用すべき特定の指示を設定する際に有用です。

これらの設定にアクセスするには、デプロイされたwebappインターフェースの設定ページに移動してください。

MCPサーバーとの統合

エージェントはMCPクライアントとして機能できるため、さまざまなMCPサーバーと簡単に統合できます。統合を設定するには、mcp.jsonを編集してCDK deployを実行します。例えば、

  "mcpServers": {
    "awslabs.cdk-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.cdk-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }

これにより、すべての新しいエージェントがMCPサーバーをツールとして使用できるようになります。

仕組み

このシステムはSlack Boltアプリケーションを利用して、ユーザー操作を管理し、スケーラブルなワーカーシステムを実装しています。以下が主なワークフローです：

1. メッセージの受信と処理
2. ユーザーがSlackでメッセージを送信すると、それはwebhookを介してSlack Boltアプリケーションに転送されます

3. API Gatewayがwebhook要求を受け取り、Lambda関数に渡します

4. イベント管理とメッセージ配信

5. Lambda関数はユーザーメッセージをAppSync Eventsに発行します

6. メッセージ履歴は後続の処理で参照するためDynamoDBに保存されます

7. ワーカーシステム管理

8. 新しいSlackスレッドが作成されると、ワーカーマネージャーに通知されます
9. ワーカーマネージャーはEC2インスタンスとEBSボリュームで構成されるワーカーユニットをプロビジョニングします

10. 各ワーカーユニットには実際の処理を担当するSWEエージェントが含まれています

11. フィードバックループ

12. ワーカーユニットはAppSync Eventsを購読してユーザーメッセージを受信します
13. 処理結果と進捗状況の更新は、ユーザーへの返信としてSlackに送信されます
14. ジョブステータスはDynamoDBで管理されます

このアーキテクチャにより、スケーラブルで信頼性の高いメッセージ処理システムが実現されます。サーバーレスコンポーネント（Lambda、API Gateway）とワーカーごとの専用EC2インスタンスの組み合わせにより、リソースの分離と柔軟なスケーラビリティが確保されます。

AIエージェントのセキュリティベストプラクティス

AIエージェントは強力な機能を提供しますが、同時に潜在的なセキュリティリスクももたらします。以下は、これらのリスクを軽減するための推奨プラクティスです：

1. 実行環境の分離
2. エージェントは専用のVM上で動作し、潜在的なファイルシステムへの損害をその環境のみに限定

3. エージェントがローカルファイルシステムを操作するような誤動作があっても、ユーザーのシステムには影響しない

4. 最小権限の原則

5. デフォルトでは、ワーカーインスタンスには最小限のIAMポリシーのみが割り当てられている（ログ記録、自己終了、S3読み取りアクセスなど）
6. WORKER_ADDITIONAL_POLICIES環境変数で権限を追加する場合は、エージェントの意図しない動作に関連するリスクを慎重に評価すること

7. 権限の影響範囲を考慮し、絶対に必要なものだけに制限する

8. **