TechMoon 科技月球
WordPress、SEO 與 AI 工具實測指南
TechMoon 科技月球
WordPress、SEO 與 AI 工具實測指南

AWS 兩位技術專家 11 月 11 日在官方部落格發表 Spring AI 搭配 Amazon Bedrock AgentCore 的完整實作,並開源兩個應用:單代理旅遊助理與五專員多代理文件處理系統。本文對照官方文章與兩個 GitHub 儲存庫,拆解 /invocations 執行契約、@Tool 工具呼叫、長短期記憶策略與 SpEL 規則引擎,並列出示範程式與生產部署之間的差距與版本前提不一致之處。
用 AI 摘要這篇文章:
AWS 兩位技術專家在 2026 年 11 月 11 日於官方機器學習部落格發表完整的 Java 代理實作教學,標題是 Build autonomous AI agents with Amazon Bedrock and Spring AI,作者為 Viquar Khan 與 Mahammadali Saheb,台北時間 11 月 12 日上午 9 時 18 分上線。文章本身屬於 Technical How-to 等級,搭配的是一個剛開源的 aws-samples 範例庫,裡面放了兩個可以直接部署的應用:一個是官方建議起點的旅遊助理單代理,另一個是五個專員分工的文件處理多代理系統。對已經有 JVM 服務、部署流程與維運人員的 Java 團隊來說,這份教學真正值得記下的東西有兩件:一份把代理推上託管執行環境的介面契約,以及一份官方自己寫清楚的示範與生產差距清單。這也是繼 AWS Web Answer 與 Claude Code 遠端代理範例之後,AWS 再次把 AgentCore 當成代理基礎設施的主角推到開發者面前。

Amazon Bedrock AgentCore 的 runtime 負責代理的生命週期與擴縮,它對你的 Java 應用只有兩個要求:暴露 POST /invocations 接收請求並以 JSON 或 Server-Sent Events 串流回應,以及 GET /ping 回報健康狀態。健康狀態有 Healthy 與 HealthyBusy 兩種,官方特別提醒長時間執行的任務必須主動回報忙碌,否則 runtime 可能以為代理閒置而把它縮減。介面小到這個程度,代表「能不能上託管環境」幾乎不再是架構問題。
在 Spring AI 這側,這份契約被包成一個註解。方法上標 @AgentCoreInvocation,/invocations 與 /ping 兩個端點、JSON 序列化、SSE 框架與健康回報就全部自動生成。官方範例裡同一支 Spring Boot 程式同時開兩個入口:一個是給 runtime 呼叫的 @AgentCoreInvocation 方法,另一個是給 React 介面用的 /api/chat REST 端點,兩者共用同一個 service 方法。這個安排的意義很實際:為了上託管環境,你不需要另外維護一個部署版本。
串流有一個官方明文的小陷阱值得抄下來:把模型串流直接回傳是最適合聊天視窗的做法,但當代理要發出多參數的工具呼叫時,要改用阻塞式的 call() 先把回應組好再切塊串流,工具參數的綁定才可靠。
記憶功能走 Spring AI 的 advisor 模式,也就是在提示送達模型之前先攔截、補上脈絡的攔截器。對話識別採 actor:session 形式,讓每個使用者的歷史彼此隔離。官方在這裡放了一句對資安團隊很重要的提醒:對外部署時,actor 要從驗證過的 OAuth 2.0(JWT)身分推導,不能拿客戶端自己送來的值,否則使用者有機會讀到彼此的對話歷史。記憶的儲存位置換成託管服務很容易,身分這一關才是真正容易漏掉的部分。
長期記憶有四種策略可以挑:semantic 記使用者的長期事實、user preference 記明確的偏好設定、summary 濃縮對話歷史讓跨作業階段延續、episodic 記過去互動學到的經驗。擷取是非同步且可選的,建立記憶資源時決定要開哪些,AgentCore 在每場對話結束後於背景抽取與整合,不會阻塞代理的回應。官方的選法建議也務實:旅遊助理用 user preference 記住單位與座位偏好,多輪長對話開 summary,要累積經驗的場景開 episodic。
官方文章對「什麼算代理」給了一個可以直接拿來檢視自家系統的定義:規劃(把目標拆成步驟並隨新資訊修正)、工具使用(呼叫外部函式、資料庫、程式碼直譯器去行動)、記憶(短期跨輪、長期跨作業階段)三者缺一不可,在一個目標導向的迴圈裡運作直到任務完成或確認無法繼續。按這個標準,檢索增強生成(RAG)應用只有檢索這一種有限工具、沒有規劃迴圈,還不算代理。這條界線對正在盤點內部「AI 功能」的團隊很好用:先問系統有沒有規劃迴圈,再談代理架構。
Spring AI 把代理三能力裡的工具使用做成一個註解:方法上標 @Tool 並寫清楚描述,模型在推理時自己決定何時呼叫、帶什麼參數,Spring AI 攔下模型的工具呼叫回應、執行被標註的方法、再把結果餵回模型繼續推理。結構化輸出則是直接要求一個 Java record 型別,Spring AI 把 record 的 schema 加進提示、再把回覆解析回 Java 型別,多模態輸入就是在使用者訊息上附加媒體檔案。
這裡有兩條官方自己寫下的但書。一條是這套做法只以 Anthropic Claude Sonnet 4.5 在 Bedrock 上驗證過,其他模型家族的行為可能不同;另一條是結構化輸出屬於 best-effort:模型偶爾會回傳不符合 schema 的輸出,需要更嚴格的保證時,要改用供應端的原生 schema 強制,或在 Spring AI 加驗證與重試。對打算把模型回應直接寫進資料庫的團隊,這兩條要直接當成設計輸入看待。
另一個範例是文件處理多代理系統。ClassifierAgent 先讀文件並分派給五個專員代理:Lawyer、Mortgage、Insurance、Tax 與 General,每個專員繼承同一個 AbstractDocumentAgent 模板、各有自己的提示與工具,用 Bedrock 的多模態 Converse API 抽出帶信心分數的結構化 JSON。

協作模式官方列了三種,但範例的基礎版只實作兩種:router 模式讓輕量協調器按文件類型分派、本身不帶領域邏輯;evaluator 模式在專員回報後,由規則引擎對合併輸出跑可設定的商業規則。剩下的 parallel fan-out 是官方標明的選配擴充,基礎版的批次端點是逐份循序處理,需要多視角同時分析時才自己加上併發分派與結果聚合。
規則引擎值得單獨看清楚,因為它的名字容易讓人誤會。它是一個寫在 application.yml 裡、用 Spring Expression Language(SpEL)對抽取結果做條件判斷的在程式內評估器,官方明文它不是 AWS Step Functions 那類工作流協調服務。規則按嚴重度分級行為:INFO 與 WARN 只記日誌,ALERT 交給可替換的 AlertService(預設實作記日誌併發指標,換個 bean 就能改送到 SNS、Slack 或電子郵件),BLOCK 則把文件留住等人工審核。官方的定位說明也很直白:因為規則由維運者以組態方式提供、來源受控,它是一個安全且可稽核的擴充點,加新規則是改設定,不是重新部署。這對合規導向的場景(法務文件沒簽名要警示、負債比超過門檻要人工審核)是整個範例裡最能直接搬走的部分。
這篇文章難得的地方,是差距不需要讀者自己挖,官方集中在生產整備章節寫出來了。
安全防護方面,範例內建的 GuardrailService 官方明說是一個輕量在程式內預檢的「替身示範」,用 guardrailsEnabled 旗標逐請求開關,篩選不允許的意圖與提示注入。官方要求生產部署改用 Amazon Bedrock Guardrails 當標準控制,對每個請求套用,而不是逐請求開關。Guardrails 覆蓋輸入與輸出兩側:內容過濾按可設定的閾值擋有害或離題內容、拒絕主題把自訂範圍外的主題擋下、敏感資訊過濾偵測並遮罩個人識別資訊,官方並點名這支援 GDPR 與 HIPAA 這類要求。
身分與閘道方面,runtime 預設走 AWS IAM 驗證,對使用者導向的代理要再加上 OAuth 2.0(JWT)授權器並從驗證身分推導記憶的 actorId。IAM 執行角色遵循最小權限:ECR 拉取映像、限定範圍的 CloudWatch Logs 與 X-Ray、Bedrock 的 InvokeModel、代理工作負載身分的存取權杖、以及限定到特定 Memory 資源 ARN 的記憶操作。AgentCore Gateway 扮演 OAuth 2.0 資源伺服器驗證 JWT,支援 Cognito、Okta、Auth0 或自建 OIDC 供應商,但它的速率限制預設 fail-open,官方明文這只能當輔助,核心資安控制仍然要另外建。
可觀測性方面有兩個官方明文「本文未實作」的擴充:分散式追蹤的 OpenTelemetry bridge 依賴已附進範例但部署時沒有開採樣、沒有架 collector,要自己設非零的 TRACING_SAMPLING 並把端點指向 collector 才會把追蹤送進 X-Ray;自動化評測與最佳化回饋迴圈同樣未實作,官方給的路徑是把指標、追蹤、稽核事件與人工審核結果存成評測資料集,用 AgentCore Evaluations 對版本化的提示、模型、工具與路由規則做比較,這一條與先前介紹過的 AWS UAEF 評測框架 是同一個方向的基礎建設。
帳單的口徑兩份官方文件寫法不同,值得核對再規劃預算。部落格的清理章節寫 runtime「規模縮到零且按呼叫計費」,範例庫 README 的部署章節則寫「按代理實際使用的 CPU 與記憶體逐秒計費」,兩邊都沒有給數字,一致的部分是:閒置代理幾乎不收費,主要變動成本是 Bedrock 的 token 用量,外加少量的 CloudWatch 與 ECR 儲存。要估成本,回到兩份定價頁看當期費率,範例的清理腳本與 memory 資源清理都要跑,不留 ECR 映像。
韌性與組態這兩塊,範例已經把生產級的骨架放進去。每次模型呼叫都套上 Resilience4j 的指數退避重試、斷路器與逾時,模型呼叫反覆失敗或逾時就快速失敗,串流路徑在出錯時改送一段 fallback 訊息,避免把原始錯誤直接吐給使用者;流量超過帳號與區域的服務配額時,AgentCore runtime 會回 HTTP 429,重試邏輯就是為此準備的。組態全面走十二因素:區域、模型 ID、記憶 ID、逾時、速率限制、系統提示全部是環境變數綁到型別化的 @ConfigurationProperties 類別,應用程式無狀態、啟動快、縮減時把進行中的回合排空,整個服務以一個不可變的 ARM64 映像從開發環境原封不動晉升到生產環境。
教學的路徑要跑起來,版本前提是硬門檻,而且官方兩份文件在細節上不一致,照較嚴的那份準備最穩。

部落格的 prerequisites 寫 JDK 21(必要)、Spring Boot 4.1(搭配 Spring AI 2.0 與 spring-ai-agentcore 2.0)、Maven 3.9+、Node.js 18+、Terraform 1.5+、Docker 與 Buildx、AWS CLI v2。範例庫 README 的 requirements 則寫 Java 21+、Node.js 20+、Terraform 1.6 以上。對照範例庫的 parent pom.xml,四個關鍵版本釘得很死:java.version 21、spring-boot-starter-parent 4.1.0、spring-ai 2.0.0、spring-ai-agentcore 2.0.0。SDK 本身的儲存庫又寫 Java 17+ 與 Spring Boot 4.x,比範例的 JDK 21 寬。另有一個時間差要注意:教學綁 spring-ai-agentcore 2.0.0,但 Maven Central 上同一個 BOM 的最新版已經到 2.3.0(後設資料 10 月 17 日更新),SDK README 的快速入門也叫讀者直接用 Maven Central 徽章上的最新版。跟著教學走會拿到落後三個 minor 版本的 SDK,這不一定是錯,但要知道自己在哪條版本線上。
部署形態也有幾個不可協商的條件:容器映像必須是 ARM64(AgentCore runtime 跑 linux/arm64,x86 機器要靠 buildx 跨建)、ECR 儲存庫使用不可變標籤、每次部署都要換新標籤;Terraform 分成 ECR 儲存庫、最小權限 IAM 角色與 AgentCore runtime 三個模組,預設區域 us-east-1,預設模型是 Claude Sonnet 4.5 的推論設定檔。已經標準化在 Kubernetes 的團隊有選配路徑:同一個 ARM64 映像可以跑在 EKS 上,用 IRSA 取得最小權限的 pod 層級憑證,應用程式本身不用改。另外範例也提供本機 Docker Compose 全棧(兩個後端加兩個 UI 加登陸頁),本機跑時 AgentCore 的記憶、瀏覽器與程式碼直譯器是關閉的。
時間軸可以把整件事看得更準。SDK 儲存庫 spring-ai-agentcore 由 spring-ai-community 社群維護,2025 年 11 月 29 日建立,Apache-2.0 授權,SDK 的 GA 官方部落格發在 2026 年 4 月 14 日;這次的範例庫 10 月 13 日才建立,教學 11 月 11 日發表,最後一次推送就落在教學上線前約 24 分鐘(台北 11 月 12 日上午 8 時 54 分),發表當下星數仍是零。這是一份很新的官方示範,程式碼在教學上線前一刻才定稿,採用時期要預期它會變。SDK 的能力面也遠大於這篇教學的範圍:模組表上還有部落格主軸沒用到的 Payments(x402 付費 API 包裹)、Artifact Store(工作階段範圍的檔案儲存)、Browser 與 Code Interpreter。
對已經把服務建立在 Spring Boot 上的團隊,這份教學是目前最完整的官方端到端起點:版本釘死、部署腳本齊全、契約只有兩個端點,把「代理上生產」拆成可以逐項核對的清單。但照範例原樣上線是不夠的,官方自己已經把話說明白:防護要用 Bedrock Guardrails 換掉示範替身、閘道限流不能算進主防線、追蹤與評測迴圈要自己補。驗證範圍也要記得:整份教學的結構化輸出行為只在 Claude Sonnet 4.5 上驗證過,範例的實際部署成本與穩定度,官方文件沒有提供數字,想採用的團隊要用自己的工作負載驗證。SDK 版本迭代速度快,動手前先對一次 Maven Central 的最新版與範例庫的推送狀態,再決定跟教學的 2.0 線還是直接上新版。