Amazon Bedrock AgentCore Harnessを使用したサーバーレス画像編集エージェントの構築

自然言語で画像を編集できるAIエージェントを構築するには、通常、オーケストレーションループ、ツールルーティング、メモリ管理、そしてそれを実行するコンピューティング環境が必要です。Amazon Bedrock AgentCoreハーネスは、設定だけでこれらのスタック全体を処理します。エージェントの役割を宣言するだけで、ハーネスはステートフルで分離されたマイクロVM上で実行し、組み込みのメモリ、ツールルーティング、および可観測性を提供します。

この記事では、ユーザーが写真をアップロードし、プレーンな英語で編集を説明すると、数秒で結果が得られるサーバーレス画像エディターの構築方法を説明します。エージェントはカスタムオーケストレーションコードなしでAgentCoreハーネス上で実行されます。認証、暗号化ストレージ、3つの画像編集ツール、Reactフロントエンドを含む完全なソリューションを、単一のデプロイコマンドでデプロイします。インフラストラクチャはAWS CDKで定義されています。

画像編集アプリケーション

このアプリケーションは、「車の色を青に変更」や「画像を右に200ピクセル拡張」といったプロンプトを受け入れます。Claude Sonnet 4.6を搭載したエージェントが要件を一連のステップに分解し、それぞれが異なるStability AIモデルに関連付けられたツール呼び出しをオーケストレーションします。次に編集を実行し、マイクロVM上のシェルコマンドを使用して透かしを適用し（トークンコストなし）、結果を返します。

このアプリケーションは、AgentCoreハーネスの以下の機能を示しています。

• 設定駆動型エージェント作成：エージェントはAPIパラメータのみで定義されます。Pythonのオーケストレーションコード、フレームワーク、コンテナは不要です。
• 呼び出しごとのモデル切り替え：フロントエンドは、基本的なチャットをClaude Haiku 4.5にルーティングし、編集をClaude Sonnet 4.6にルーティングします。エージェントはモデル切り替え間で会話コンテキストを保持します。
• 呼び出しごとのペルソナオーバーライド：ユーザーは業界ペルソナ（不動産、小売、自動車）を選択し、再デプロイなしでドメイン固有のシステムプロンプトを注入します。
• AgentCoreメモリ：会話履歴をAgentCoreサービスに30日間保存します。セッション内のターン全体で完全なコンテキストを保持するため、フロントエンドが履歴を再送信しなくても以前の編集を参照できます。このサンプルはセッションIDをlocalStorageに保持するため、ブラウザリフレッシュ後も会話は存続します。ブラウザデータをクリアするとフロントエンドで新しいセッションが開始されますが、会話履歴はListEvents APIを介してAgentCoreで引き続き利用可能です。
• AgentCore GatewayとMCP：3つのLambdaバッキングツールがModel Context Protocol（MCP）を介して公開され、セマンティックルーティングが行われます。エージェントはプロンプトに基づいて適切なツールを選択します。
• InvokeAgentRuntimeCommand：編集後、PythonスクリプトがAgentCoreランタイムマイクロVM上で直接実行され、透かしが追加されます。モデルの推論は不要で、トークンも消費されません。

ソリューション概要

画像編集アプリケーションのアーキテクチャは4つの層で構成されています。

1. AWS AmplifyでホストされるReactフロントエンド：ユーザーが画像をアップロードし、マスクを描画し、編集指示を入力します。
2. AWS Lambdaプロキシ：ブラウザの認証情報とハーネスAPIの間のセキュリティ境界として機能し、許可されるシステムプロンプトを制御します。
3. Amazon Bedrock AgentCoreハーネスエージェント（AgentCore Memoryを使用して会話を永続化）。
4. 3つのツールLambda関数：Amazon Bedrockを介してStability AI基盤モデルを呼び出し、画像を生成します。

設定によるエージェントの作成

AgentCoreハーネスでは、エージェント定義はcreate_harness APIに渡されるパラメータのセットです。以下は、CDKデプロイ中にエージェントを作成するプロビジョニングコードの核心です。

harness_params = {
    'harnessName': 'img_editor',
    'executionRoleArn': execution_role_arn,
    'model': {'bedrockModelConfig': {'modelId': 'us.anthropic.claude-sonnet-4-6'}},
    'systemPrompt': [{'text': system_prompt}],
    'tools': [{'type': 'agentcore_gateway', 'name': 'gateway',
                'config': {'agentCoreGateway': {'gatewayArn': gateway_arn}}}],
    'allowedTools': [
        'inpaint-target___inpaint',
        'outpaint-target___outpaint',
        'search-replace-target___search_and_replace',
    ],
    'maxIterations': 10,
    'timeoutSeconds': 300,
}
harness_params['memory'] = {
    'agentCoreMemoryConfiguration': {'arn': memory_arn}
}
response = client.create_harness(**harness_params)

これがエージェント全体です。オーケストレーションループ、ツール実行ロジック、ストリーミングハンドラー、エラーリトライコードは一切ありません。AgentCoreハーネスがすべてを処理します。

AgentCore Gatewayによるツールの宣言

エージェントにツールへのアクセスを提供するには、通常、モデルからのツール呼び出しを受け取り、引数を解析し、ターゲット関数を呼び出し、エラーを処理し、結果を返すコードを記述する必要があります。ハーネスを使用すると、これらすべてをスキップできます。AgentCore Gatewayでツールスキーマを宣言し、Lambda関数をポイントするだけです。ハーネスはツールを検出し、推論中にモデルに提示し、Gatewayを介して選択したツールを呼び出し、結果を自動的に会話にフィードバックします。

以下は、CDKスタックで検索置換ツールを宣言する方法です。

this.gateway.addLambdaTarget('SearchReplaceTarget', {
    gatewayTargetName: 'search-replace-target',
    lambdaFunction: this.searchReplaceLambda,
    toolSchema: agentcore.ToolSchema.fromInline([{
        name: 'search_and_replace',
        description: '説明によって画像内のオブジェクトを検索して置換します。マスクは不要です。ユーザーが特定のオブジェクトを置換したい場合に使用します。',
        inputSchema: {
            type: agentcore.SchemaDefinitionType.OBJECT,
            properties: {
                source_image_key: { type: agentcore.SchemaDefinitionType.STRING },
                search_prompt: { type: agentcore.SchemaDefinitionType.STRING },
                prompt: { type: agentcore.SchemaDefinitionType.STRING },
            },
            required: ['source_image_key', 'search_prompt', 'prompt'],
        },
    }]),
});

エージェントはこれらのツールの説明を読み、ユーザープロンプトに基づいて適切なツールを選択します。ルーティングロジックは不要です。ハーネスはモデルの推論を通じてツール選択を処理します。

呼び出しごとのモデルとペルソナの切り替え

ハーネスはすべての呼び出しでモデルパラメータを受け入れます。異なるモデルIDを渡すと、そのターンを処理する基盤モデルが変わります。ハーネスはAgentCore Memoryから完全な会話履歴を自動的にロードし、新しいモデル用にフォーマットするため、追加コードなしでコンテキストが引き継がれます。モデル切り替えロジック、履歴取得、入力フォーマットを記述する必要はありません。ハーネスは単一のパラメータ変更に基づいてこれらすべてを内部的に管理します。

Lambdaプロキシはこれを使用して、基本的なチャットをHaikuに、画像編集をSonnetにルーティングします。

invoke_params = {
    'harnessArn': harness_arn,
    'runtimeSessionId': session_id,
    'messages': [{'role': 'user', 'content': [{'text': input_text}]}],
    'actorId': actor_id,
}
if model_override:
    invoke_params['model'] = {
        'bedrockModelConfig': {'modelId': model_override}
    }
if persona_text:
    invoke_params['systemPrompt'] = [{'text': persona_text}]
response = client.invoke_harness(**invoke_params)

フロントエンドは、プロンプトに編集キーワードが含まれているかどうかに基づいて使用するモデルを決定します。「hi」や「何ができる？」のような短いメッセージはレイテンシを低くするためにHaikuに送られ、編集はより高品質なツール選択のためにSonnetに送られます。ユーザーはメニューから手動でモデルを選択することもできます。

AgentCore Memoryは、ハーネスで設定されたモデルの変更に関係なく、完全な会話履歴を保持します。Sonnetが「車を黒に変更」を処理した後にHaikuが「青はどう？」を受け取ると、Memoryがアクティブなモデルに完全な履歴を提供するため、Haikuは「青」が車を指していることを認識します。

後処理：シェルコマンドの使用（トークンコストなし）

エージェントが画像を生成した後、マイクロVM上でPythonスクリプトを直接実行して透かしを追加します。これにはInvokeAgentRuntimeCommandを使用します。これにより、モデルを経由せずにエージェントの環境へのシェルアクセスが提供されます。

script = '\n'.join([
    'from PIL import Image, ImageDraw, ImageFont',
    'import boto3, io',
    's3 = boto3.client("s3")',
    f'obj = s3.get_object(Bucket="{bucket_name}", Key="{result_key}")',
    'img = Image.open(io.BytesIO(obj["Body"].read())).convert("RGBA")',
    '# ... 透かしテキストをタイル状に配置 ...',
    's3.put_object(Bucket=bucket, Key=key, Body=buf.getvalue())',
])
encoded_script = base64.b64encode(script.encode()).decode()
client.invoke_agent_runtime_command(
    agentRuntimeArn=harness_arn,
    runtimeSessionId=session_id,
    body={'command': f'echo {encoded_script} | base64 -d | python3'},
)

このパターンは、決定論的な後処理に役立ちます。モデルに送信する前に画像のサイズを変更する（入力トークンを節約）、エージェント出力の検証、構造化データの抽出、ビジネスロジックの適用などが可能です。マイクロVMにはデフォルトでPythonとbashが利用可能で、実行時に追加パッケージをインストールすることもできます。

ハーネスは設定のみで駆動されるため、カスタムロジックを追加できるエージェントスクリプトはありません。InvokeAgentRuntimeCommandは、エージェントが実行されるのと同じマイクロVM上で、エージェントループの外部で独自のコードを実行する方法です。Lambdaプロキシはエージェントのターン終了後にこれを呼び出します。コマンドが実行され、処理が行われ、結果が返されます。エージェントはその発生を知りません。

前提条件

このソリューションをデプロイするには、以下が必要です。

• IAMロール、Lambda関数、S3バケット、Cognitoプール、AgentCoreリソースを作成する権限を持つAWSアカウント。
• Node.js 20.x以降。
• Python 3.13以降（Lambda関数ランタイム用）。
• 認証情報が設定されたAWS CLI 2.x。
• Amazon BedrockでのAnthropic Claudeモデル（Sonnet、Haiku）へのアクセス。
• Amazon BedrockでのStability AIモデルへのアクセス。
• 推定デプロイ時間は3〜5分。

ソリューションのデプロイ

デプロイスクリプトはすべてをエンドツーエンドで処理します。前提条件のインストール、Lambda依存関係のバンドル、CDKスタックのデプロイ、フロントエンドのビルド、Amplifyへのアップロード、テストユーザーの作成を行います。

GitHubリポジトリをクローンし、プロジェクトディレクトリに移動します。

git clone https://github.com/aws-samples/sample-serverless-image-editing-agent-bedrock-agentcore-harness
cd sample-serverless-image-editing-agent-bedrock-agentcore-harness

デプロイスクリプトを実行します。

./deploy.sh

最後に、ライブURLとログイン資格情報が出力されます。

CDKスタックは、単一のAWS CloudFormationスタックですべてのリソースを作成します。このソリューションは、認証処理のためにAmazon Cognito（ユーザープールとIDプールの両方）を使用します。画像はAWS KMS暗号化で保護されたS3バケットに保存されます。画像編集機能は、AgentCore Gatewayを介してMCPツールとして公開される3つのLambda関数によって提供されます。これらのツールは、メモリを備えたAgentCoreハーネスエージェントによってオーケストレーションされ、Lambdaプロキシを介してアクセスされます。フロントエンドでは、AWS AmplifyアプリケーションがReactベースのユーザーインターフェイスを提供します。

ウォークスルー

サインイン後、エディタは左側にキャンバス、右側にチャットインターフェイスを表示します。

1. 画像をアップロード：画像はS3のユーザーのIDスコーププレフィックスにアップロードされます。
2. 編集内容を説明：チャット入力に自然言語の指示を入力します。オブジェクトの置換（例：「空を夕焼けに変更」）の場合、エージェントは自動的に検索置換を使用します。
3. 領域固有の編集のためのマスクを描画：画像の特定の領域を編集するには、キャンバス上にマスクを描画して領域を定義し、マスク領域に生成する内容を入力します。
4. 結果を表示：編集された画像がチャットスレッドに表示され、マイクロVMのシェルコマンドによって適用されたタイル状の透かしが付きます。「舞台裏」パネルには、使用されたモデル、呼び出されたツール、トークン数、レイテンシ、透かしが適用されたかどうかが表示されます。
5. オプションでモデルを切り替え：ユーザーはメニューからモデルを選択して、デフォルトのルーティングを上書きできます。

このソリューションは、AgentCoreハーネスがAIエージェントの構築とデプロイをいかに簡素化し、サーバーレス画像編集などのアプリケーションに強力なツールを提供するかを示しています。