2026-07-08 00:51 UTC+8站內改寫5 分鐘閱讀更新: 2026-07-08 01:19 UTC+8

使用Amazon Bedrock AgentCore Harness構建無服務器圖像編輯代理

本文介紹如何構建一個無服務器圖像編輯器，用户上傳照片後用自然語言描述編輯需求，幾秒內即可獲得結果。代理運行在AgentCore harness上，無需自定義編排代碼。通過單一部署命令即可部署完整解決方案，包括身份驗證、加密存儲、三個圖像編輯工具和React前端。基礎設施使用AWS CDK定義。

來源AWS Machine Learning Blog作者: Salman Ahmed

構建一個能夠根據自然語言編輯圖像的AI代理通常需要編排循環、工具路由、內存管理以及運行它的計算環境。Amazon Bedrock AgentCore harness通過配置處理了整個流程。您只需聲明代理的職責，harness就會在一個有狀態、隔離的微VM中運行它，內置內存、工具路由和可觀測性。

本文介紹瞭如何構建一個無服務器圖像編輯器，用户上傳照片，用簡單的英語描述編輯需求，然後在幾秒內收到結果。代理運行在AgentCore harness上，無需自定義編排代碼。通過單一部署命令，您可以部署完整的解決方案，包括身份驗證、加密存儲、三個圖像編輯工具和React前端。基礎設施使用AWS Cloud Development Kit（AWS CDK）定義。

圖像編輯應用程序

該應用程序接受諸如“將汽車顏色改為藍色”或“將圖像向右擴展200像素”之類的提示。由Claude Sonnet 4.6驅動的代理將需求分解為一系列步驟，並編排工具調用，每個工具與不同的Stability AI模型關聯。然後執行編輯，使用微VM上的shell命令應用水印（無token成本），並返回結果。

此應用程序展示了AgentCore harness的以下能力：

配置驅動的代理創建：代理完全通過API參數定義，無需Python編排代碼、框架或容器。
每次調用模型切換：前端將基本聊天路由到Claude Haiku 4.5，將編輯路由到Claude Sonnet 4.6，代理在模型切換時保持對話上下文。
每次調用角色覆蓋：用户選擇行業角色（房地產、零售、汽車），這些角色會注入特定領域的系統提示，無需重新部署。
AgentCore內存：將對話歷史存儲在AgentCore服務中30天。代理在會話中的各輪次之間保持完整上下文，因此可以引用先前的編輯，而無需前端重新發送歷史。此示例將會話ID保存在localStorage中，因此對話在瀏覽器刷新後仍然存在。清除瀏覽器數據會在前端啓動新會話，但對話歷史仍可通過ListEvents API在AgentCore中獲取。
AgentCore Gateway與MCP：三個AWS Lambda支持的工具通過Model Context Protocol（MCP）暴露，並具有語義路由。代理根據提示選擇正確的工具。
InvokeAgentRuntimeCommand：每次編輯後，Python腳本直接運行在AgentCore運行時微VM上以添加水印。無需模型推理，不消耗token。

解決方案概述

圖像編輯應用程序的架構有四層：

託管在AWS Amplify上的React前端，用户上傳圖像、繪製遮罩並輸入編輯指令。
AWS Lambda代理，作為瀏覽器憑據與harness API之間的安全邊界，並控制允許哪些系統提示。
Amazon Bedrock AgentCore harness代理，具有AgentCore Memory以實現對話持久性。
三個工具Lambda函數，通過Amazon Bedrock調用Stability AI基礎模型進行圖像生成。

使用配置創建代理

使用AgentCore harness，代理定義是傳遞給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 harness處理了所有這些。

通過AgentCore Gateway聲明工具

賦予代理訪問工具的權限通常需要編寫代碼來接收來自模型的工具調用、解析參數、調用目標函數、處理錯誤並將結果返回。使用harness，您可以跳過所有這些。您在AgentCore Gateway上聲明工具模式並將其指向Lambda函數。Harness發現工具，在推理過程中將它們呈現給模型，通過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'],
        },
    }]),
});

代理讀取這些工具描述並根據用户提示選擇正確的工具，無需路由邏輯。Harness通過模型的推理處理工具選擇。

每次調用的模型和角色切換

Harness在每次調用時接受一個模型參數。傳遞不同的模型ID會改變處理該輪對話的基礎模型。Harness自動從AgentCore Memory加載完整對話歷史，併為新模型格式化，因此上下文無需額外代碼即可傳遞。您無需編寫模型切換邏輯、歷史檢索或輸入格式化。Harness基於單個參數變化在內部管理所有這些。

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保留完整的對話歷史，無論harness中配置的模型如何更改。當Haiku收到“藍色的怎麼樣？”而之前Sonnet處理了“把車變成黑色”時，Haiku知道“藍色”指的是汽車，因為Memory將完整歷史提供給任何活躍的模型。

後處理：使用shell命令（無token成本）

代理生成圖像後，我們直接運行Python腳本在harness微VM上添加水印。這使用InvokeAgentRuntimeCommand，它提供對代理環境的shell訪問，無需通過模型。

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'},
)

這種模式對於確定性後處理非常有用：在發送給模型之前調整圖像大小（節省輸入token）、驗證代理輸出、提取結構化數據或應用業務邏輯。微VM默認有Python和bash，您還可以在運行時安裝額外的包。

由於harness僅通過配置驅動，沒有代理腳本可以添加自定義邏輯。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（用户池和身份池）處理身份驗證。圖像存儲在由AWS KMS加密的S3存儲桶中。圖像編輯能力由三個Lambda函數提供，這些函數通過AgentCore Gateway暴露為MCP工具。這些工具由配備內存的AgentCore harness代理編排，通過Lambda代理訪問。前端方面，AWS Amplify應用程序提供基於React的用户界面。

操作指南

登錄後，編輯器左側顯示畫布，右側顯示聊天界面。

上傳圖像：圖像上傳到S3中用户身份範圍內的前綴。
描述編輯：在聊天輸入中輸入自然語言指令。對於對象替換（例如“將天空改為日落”），代理會自動使用搜索替換。
繪製遮罩進行區域編輯：要編輯圖像中的特定區域，在畫布上繪製遮罩定義區域，然後輸入要在遮罩區域生成的內容。
查看結果：編輯後的圖像出現在聊天線程中，帶有由微VM shell命令應用的平鋪水印。“幕後”面板顯示使用了哪個模型、調用了哪個工具、token計數、延遲以及是否應用了水印。
可選地切換模型：用户可以從菜單中選擇模型以覆蓋默認路由。

此解決方案展示了AgentCore harness如何簡化AI代理的構建和部署，使其成為無服務器圖像編輯等應用的強大工具。