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代理的構建和部署，使其成為無伺服器影像編輯等應用的強大工具。