Amazon Bedrock AgentCore — Fundamentals & Runtime

Hi mọi người, mình tên Huỳnh Nhật Minh - Solutions Architect tại AWS Premier Partner. Đây là series blog Deep dive về Bedrock AgentCore dành cho Solution Architect / GenAI Specialist.

Mục tiêu không chỉ giải thích kiến thức mà còn giúp mọi người hiểu được tư duy thiết kế (Architectural Thinking), các trade-off và các best practices trong môi trường production. Nội dung trình bày theo cấu trúc sau:

1. Executive Summary

2. Concept & Core Principles

3. Architecture Deep Dive

4. Request Flow từng bước

5. Thành phần chính và vai trò

6. Thiết kế theo AWS Well-Architected Framework

7. Security Best Practices

8. Performance & Scalability

9. Cost Optimization

10. Monitoring & Observability

11. Production Best Practices

12. Common Pitfalls & Anti-patterns

13. So sánh với các giải pháp tương đương

14. Use Cases thực tế

15. Ví dụ triển khai bằng Python và AWS SDK

16. Kiến trúc minh họa (ASCII)

17. Checklist dành cho Solution Architect

18. Interview Questions & Answers

Cập nhật: 29/07/2026 — đối chiếu AWS Developer Guide, Service Quotas & Pricing page

1. Executive Summary

Vấn đề gốc rễ. Trong 2024–2025, hầu hết doanh nghiệp đều xây được PoC agent trong 2 tuần, rồi mắc kẹt 6–9 tháng để đưa lên production. Lý do không phải là model hay prompt — mà là hạ tầng vận hành agent: session isolation, identity/OAuth, long-running execution, memory bền vững, tool governance, observability cho reasoning trace, và cost control cho workload có 30–70% thời gian nằm chờ I/O.

AgentCore là gì. Amazon Bedrock AgentCore là một agentic platform — không phải một framework, không phải một model. Nó là tập hợp các service module hoá (primitives) giải quyết chính xác lớp vận hành nói trên. Điểm khác biệt chiến lược so với Amazon Bedrock Agents (thế hệ trước): AgentCore không áp đặt framework hay model. Bạn viết agent bằng Strands, LangGraph, CrewAI, LlamaIndex, Google ADK, OpenAI Agents SDK hay code thuần; dùng Claude, Nova, GPT, Gemini, Llama, Mistral — trong hoặc ngoài Bedrock đều được.

Các primitive hiện có: Runtime, Harness, Memory, Gateway, Identity, Code Interpreter, Browser, Observability, Evaluations, Policy, Payments, Registry. Mỗi service dùng độc lập được — đây là quyết định thiết kế quan trọng nhất, vì nó cho phép adoption tăng dần thay vì rewrite toàn bộ.

AgentCore Runtime — trọng tâm tài liệu này. Là compute layer serverless, purpose-built cho agent. Ba đặc tính định nghĩa nó:

Điều cần nhớ nhất. Runtime không phải "Lambda có timeout dài hơn". Mô hình tính phí và mô hình isolation của nó được thiết kế riêng cho một loại workload rất cụ thể: stateful, bursty CPU, I/O-heavy, multi-tenant, cần chứng minh isolation cho auditor. Nếu workload của bạn không có ít nhất 3 trong 4 đặc tính đó, Lambda hoặc Fargate có thể rẻ hơn và đơn giản hơn.

Trade-off cốt lõi phải chấp nhận: bạn đánh đổi quyền kiểm soát hạ tầng (không chọn instance type, tối đa 2 vCPU / 8 GB mỗi session, ARM64-only, image ≤ 2 GB) để lấy isolation + billing model + operational simplicity. Với agent workload đây gần như luôn là đánh đổi đúng. Với batch data processing thì không.

2. Concept & Core Principles

2.1 What? — AgentCore là gì

Định nghĩa chính thức: một agentic platform để build, deploy và operate agent một cách bảo mật ở quy mô lớn, dùng bất kỳ framework và foundation model nào, không cần quản lý hạ tầng.

Định nghĩa dưới góc nhìn SA: AgentCore là một tập hợp managed primitives thay thế cho những gì trước đây bạn phải tự build:

2.2 Why? — Tại sao AWS xây cái này

Ba áp lực kỹ thuật mà kiến trúc serverless truyền thống không giải được:

(1) Agent là stateful, function là stateless. Một agent trong lúc reasoning giữ: message history, scratchpad, kết quả tool call trung gian, object trong RAM, file tạm. Lambda cưỡng ép bạn serialize toàn bộ state đó ra ngoài sau mỗi invocation → latency + complexity + rủi ro rò rỉ state.

(2) Multi-tenancy của agent nguy hiểm hơn của API. Một API bug rò rỉ 1 record. Một agent bug có thể để agent của tenant A đọc scratchpad của tenant B rồi đưa nội dung đó vào prompt của LLM — biến rò rỉ dữ liệu thành rò rỉ có tính lan truyền. Container reuse (mô hình Lambda) không đủ mạnh để chứng minh với auditor. Do đó: microVM per session, huỷ sau khi xong.

(3) Agent tiêu CPU theo dạng nhọn, chờ I/O rất lâu. Một session 60 giây điển hình: ~18 giây CPU thật, 42 giây chờ LLM/API/DB. Mô hình pre-allocated (Fargate task, EC2) buộc bạn trả tiền cho 60 giây × peak memory. AgentCore chỉ tính CPU khi thực sự tiêu, và tính memory theo peak tới thời điểm đó — chênh lệch tới 3.3× CPU cost theo ví dụ chính thức của AWS.

2.3 Core Principles — 6 nguyên lý thiết kế

1. Framework-agnostic / Model-agnostic. AgentCore không biết bên trong container bạn dùng gì. Nó chỉ yêu cầu bạn tuân thủ service contract (HTTP/MCP/A2A). Đây là hợp đồng duy nhất.
2. Modular, composable. Mỗi primitive độc lập. Dùng Runtime mà không dùng Memory được. Dùng Gateway cho agent chạy trên EKS được.
3. Session as the unit of isolation — không phải request, không phải container. Đây là điểm khác biệt tư duy quan trọng nhất so với Lambda.
4. Ephemeral by default, durable by choice. State trong session sẽ mất. Muốn bền → AgentCore Memory / S3 / DynamoDB / Session Storage.
5. Identity-first. Inbound auth (ai gọi được agent) và outbound auth (agent gọi được gì) là first-class, không phải add-on.
6. Observability là bắt buộc, không tuỳ chọn. Agent là hệ thống non-deterministic. Không có trace = không debug được = không production được.

2.4 Pros / Cons / Trade-offs của platform

Pros

• Không lock-in framework → team đang dùng LangGraph không phải rewrite.
• Adoption tăng dần → giảm rủi ro dự án.
• Isolation model đủ mạnh để pass audit trong ngành regulated (finance, healthcare).
• Billing model khớp bản chất workload.
• Observability + Evaluations có sẵn → rút ngắn giai đoạn "agent chạy nhưng không ai biết nó đúng hay sai".

Cons

• Bề mặt học tập rộng: 12 service, mỗi service có quota + pricing riêng.
• Nhiều capability còn ở preview (Session Storage, Registry, Payments, Optimization Insights) → không nên đặt lên critical path production.
• Không có VPC-native cho mọi mode ở mọi region → cần verify trước khi cam kết kiến trúc.
• Cost model tinh vi = khó forecast chính xác trước khi có traffic thật.
• Region availability hẹp hơn Bedrock core → ảnh hưởng data residency (đặc biệt với khách hàng VN cần ap-southeast-1).

Trade-offs cần quyết định sớm

2.5 Common Mistakes ở tầng concept

• Nhầm AgentCore = Bedrock Agents. Bedrock Agents là managed agent với action group, gắn chặt Bedrock model. AgentCore là platform hạ tầng, agnostic. Khác nhau về bản chất.
• Coi Runtime là "Lambda 8 giờ". Dẫn tới thiết kế sai: stateless handler, không dùng session, không tận dụng context reuse → mất hết lợi thế.
• Bật hết 12 primitive từ ngày đầu. Chi phí vận hành và learning curve tăng phi tuyến. Adoption tăng dần là design intent của platform.

2.6 Real-world Example

Một ngân hàng số ở Đông Nam Á có agent tư vấn sản phẩm, code bằng LangGraph, đang chạy trên EKS. Vấn đề: (a) compliance yêu cầu chứng minh session của khách A không thể chạm dữ liệu khách B; (b) chi phí EKS cao vì phải provision cho peak; (c) không debug được khi agent trả lời sai.

Migration path thực tế không phải rewrite: đóng gói LangGraph app vào container ARM64 tuân thủ contract /invocations + /ping → deploy lên Runtime (giữ nguyên 95% code) → bật Observability → sau 1 tháng thêm Memory cho personalization → sau đó chuyển 12 internal API sang Gateway. Bốn phase, mỗi phase độc lập rollback được.

3. Architecture Deep Dive

3.1 Mô hình phân lớp của AgentCore

3.2 Mô hình đối tượng của Runtime

🔹 Bước 1: Container Ingestion (Nạp Container)

• Developer đóng gói Agent thành image chuẩn kiến trúc ARM64 và đẩy lên Amazon ECR.
• Hệ thống lưu trữ định danh image (digest) kèm theo các thông tin cổng dịch vụ: cổng 8080 cho luồng HTTP tiêu chuẩn và cổng 8000 cho luồng MCP (Model Context Protocol).

🔹 Bước 2: Runtime Creation (Khởi tạo Runtime)

• Lệnh API CreateAgentRuntime sẽ đăng ký container image đó với hệ thống.
• Gán một workload identity (định danh thực thi) để phân quyền security, đồng thời đóng dấu phiên bản đầu tiên là Version 1.
• Mặc định tạo ra một DEFAULT endpoint trỏ thẳng tới Version 1 này để tiếp nhận traffic.

🔹 Bước 3: Session Bootstrap (Khởi tạo phiên làm việc)

• Khi nhận yêu cầu InvokeAgentRuntime đầu tiên đi kèm một runtimeSessionId mới, hệ thống sẽ tự động khởi tạo một môi trường thực thi (execution environment) hoàn toàn cô lập (isolated).
• Thời gian khởi động (bootstrap) được tối ưu hóa cực nhanh nhờ cơ chế chế độ lưu cache image digest và lazy layer extraction (chỉ giải nén các lớp dữ liệu cần thiết trước).

🔹 Bước 4: Invocation Handling (Xử lý lời gọi)

• Yêu cầu từ người dùng (payload hỗ trợ tối đa 100 MB) được truyền trực tiếp (stream) vào container.
• Agent xử lý và trả về kết quả dưới dạng văn bản JSON hoặc dạng dòng dữ liệu SSE (Server-Sent Events).
• Runtime chuyển tiếp dữ liệu này trực tiếp về cho ứng dụng gọi, đồng thời âm thầm thu thập dữ liệu giám sát/máy đo (observability data - logs, metrics).

🔹 Bước 5: Health Negotiation (Kiểm tra sức khỏe dịch vụ)

• Môi trường Runtime liên tục gửi yêu cầu kiểm tra tới route /ping của Agent.
• Agent phản hồi:
  • Healthy: Khi rảnh rỗi.
  • HealthyBusy: Khi đang thực hiện các tác vụ chạy ngầm (background tasks). Cơ chế này giúp các quy trình xử lý kéo dài không bị ngắt kết nối giữa chừng (khi trải qua các điểm await).

🔹 Bước 6: Credential Exchange (Trao đổi xác thực)

• Khi Agent cần gọi công cụ bên ngoài (External Tools) yêu cầu xác thực OAuth, nó sử dụng Workload token của mình đổi lấy một Scoped access token (token truy cập có phạm vi giới hạn) thông qua AgentCore Identity.
• Các token này có thời gian sống ngắn (short-lived) và gắn chặt với identity của người dùng đang thực hiện lời gọi.

🔹 Bước 7: Termination (Hủy môi trường)

• Sau 15 phút không hoạt động (inactivity) hoặc đạt tổng thời gian chạy tối đa 8 giờ, môi trường sẽ tự động bị hủy để tiết kiệm tài nguyên.
• Bộ nhớ RAM sẽ bị xóa sạch, bộ nhớ tạm thời bị hủy bỏ, và sessionId đó sẽ không còn liên kết với môi trường cũ nữa.

🔹 Bước 8: Version Update (Cập nhật phiên bản)

• Khi đóng gói và đẩy lên một image mới, hệ thống sẽ tự động gắn nhãn phiên bản tiếp theo (Version n+1).
• Khi Endpoint được cập nhật sang Version mới, các phiên làm việc (session) mới sẽ được dẫn sang Version n+1. Trong khi đó, các phiên làm việc hiện tại ở Version cũ vẫn tiếp tục chạy cho đến khi tự hoàn thành và kết thúc theo vòng đời tự nhiên.

3.3 Session lifecycle — cơ chế cốt lõi

Ba con số phải nhớ:

• Idle timeout: 15 phút — điều chỉnh được qua idleRuntimeSessionTimeout trong LifecycleConfiguration.
• Max session lifetime: 8 giờ — điều chỉnh được qua maxLifetime.
• Request timeout: 15 phút (không điều chỉnh được) — cho một synchronous request.

Hệ quả kiến trúc quan trọng nhất: dùng lại runtimeSessionId không đảm bảo context còn. Sau terminate, cùng session ID sẽ tạo môi trường mới sạch trơn. → Nếu context phải bền, bắt buộc dùng AgentCore Memory hoặc external store. Đừng thiết kế dựa trên giả định session sống mãi.

3.4 Service Contract — hợp đồng duy nhất bạn phải tuân thủ

Đây là API surface mà container của bạn phải expose. Không tuân thủ = deploy thành công nhưng invoke fail.

Container requirements (bắt buộc):

HTTP protocol — 3 path:

/ping là cơ chế điều khiển async, không chỉ là health check. Khi agent đang chạy background task, bạn trả HealthyBusy → Runtime hiểu session vẫn active và không terminate nó vì idle. Đây là cách chính thức để chạy job dài tới 8 giờ. Rất nhiều team bỏ qua chi tiết này rồi thắc mắc "sao job của tôi bị kill sau 15 phút".

Protocol khác: ngoài HTTP, Runtime hỗ trợ MCP (deploy MCP server làm tool cho agent khác) và A2A (Agent-to-Agent, cho multi-agent discovery & communication). Mỗi protocol có contract riêng — chọn qua protocolConfiguration khi create runtime.

3.5 Hai deployment mode — quyết định sớm

Lưu ý phản trực giác: direct code deploy có rate tạo session cao hơn (25 TPS ≈ 1500/phút so với 400/phút của container). Nếu workload của bạn là nhiều session ngắn, direct code deploy thắng ở cả speed lẫn scale.

4. Request Flow từng bước

4.1 Flow đầy đủ — invocation đầu tiên của một session (OAuth inbound)

4.2 Flow long-running async (job > 15 phút)

Common mistake ở đây: giữ HTTP connection mở chờ job xong. Sẽ bị cắt ở 15 phút (sync) hoặc 60 phút (streaming). Pattern đúng là accept-then-poll + HealthyBusy.

4.3 Flow so sánh cold vs warm — tác động latency

→ Design implication: vì cold start chỉ trả một lần cho cả session (không phải mỗi turn như Lambda), agent hội thoại nhiều turn được lợi rất lớn. Ngược lại, workload "1 session = 1 request" trả cold start cho mọi request → đây là anti-pattern.

5. Thành phần chính và vai trò

5.1 Bảng tổng hợp 12 primitive

5.2 Các thành phần bên trong Runtime

5.3 Cách các primitive nối với nhau — 3 pattern

6. Thiết kế theo AWS Well-Architected Framework

Áp dụng 6 pillar + GenAI Lens (lens riêng của AWS cho workload GenAI).

6.1 Operational Excellence

Anti-pattern: deploy bằng agentcore deploy từ laptop lên production. CLI tuyệt vời cho dev; production phải qua pipeline.

6.2 Security

Xem chi tiết ở mục 7. Tóm tắt WAF-alignment:

• Identity foundation: inbound auth bắt buộc (OAuth2 cho end-user, SigV4 cho service-to-service).
• Traceability: mọi invocation có trace ID; CloudTrail cho control plane.
• Defence in depth: Inbound Auth → Policy (Cedar) → execution role least-privilege → Bedrock Guardrails.
• Data protection: session isolation ở biên VM; memory sanitize khi terminate; KMS CMK cho Memory/S3.
• Keep people away from data: agent tự vận hành; con người xem trace đã mask PII.

6.3 Reliability

6.4 Performance Efficiency

6.5 Cost Optimization

Xem mục 9. Nguyên tắc chính: tối ưu peak memory và CPU-active time, vì đó là hai thứ duy nhất bị tính tiền ở tầng Runtime. Nhưng nhớ: chi phí FM token thường lớn hơn chi phí Runtime 10–100×. Tối ưu sai chỗ là lỗi phổ biến nhất.

6.6 Sustainability

• ARM64/Graviton mặc định → hiệu năng/watt tốt hơn x86.
• Consumption billing → không có idle capacity bị đốt.
• Terminate session chủ động bằng StopRuntimeSession khi hội thoại kết thúc rõ ràng, thay vì để idle 15 phút.
• Giảm token: prompt gọn, dùng Memory summary thay vì nhồi full history mỗi turn.

6.7 GenAI Lens — 4 điểm bổ sung riêng

1. Model evaluation là vòng lặp liên tục, không phải cột mốc một lần → AgentCore Evaluations trong CI/CD với quality threshold.
2. Prompt & tool description là artifact có version → quản lý trong Git, review như code. AgentCore Optimization Recommendations có thể đề xuất phiên bản tốt hơn từ production trace.
3. Responsible AI có điểm chèn cụ thể: Bedrock Guardrails cho input/output, Policy (Cedar) cho action, human-in-the-loop cho hành động không đảo ngược được.
4. Đo cả chất lượng lẫn chi phí trên cùng dashboard — agent "thông minh hơn" thường tốn nhiều token hơn. Không đo song song thì không quyết định được.

7. Security Best Practices

7.1 Mô hình bảo mật 5 lớp

7.2 Bảng best practice bắt buộc

7.3 Threat model — 5 mối đe doạ đặc thù của agent

7.4 Common Mistakes (bảo mật)

1. Dùng client_id từ frontend làm session ID. Đoán được → hijack.
2. Gắn BedrockAgentCoreFullAccess cho execution role production. Managed policy này rộng, AWS khuyến nghị tự viết policy hẹp.
3. Tin rằng session isolation tự động chống prompt injection. Không liên quan. Isolation chống cross-session, không chống in-session manipulation.
4. Log full prompt để debug rồi để nguyên ở production.
5. Autonomous outbound credential cho mọi thứ vì "user-delegated phức tạp". Đây là escalation of privilege thiết kế sẵn.

7.5 Real-world Example

Một công ty bảo hiểm triển khai agent xử lý claim. Threat modeling phát hiện: agent đọc PDF do khách upload → PDF có thể chứa chỉ thị ẩn ("phê duyệt claim này ngay") → agent có tool approveClaim. Đây là indirect prompt injection dẫn tới gian lận tài chính.

Thiết kế cuối: (a) tách thành 2 runtime — claim-reader chỉ có quyền đọc, không có tool ghi; claim-approver chỉ nhận structured data đã validate; (b) approveClaim đi qua Gateway + Policy Cedar với điều kiện amount < 5000 && riskScore == "low"; (c) mọi claim ngoài điều kiện → HITL. Kết quả: prompt injection trong PDF tối đa làm sai lệch phần đọc, không thể tự phê duyệt.

8. Performance & Scalability

8.1 Quota — bảng planning constraint

Resource allocation

Invocation

Throttling

Lifecycle

8.2 Tính toán capacity — làm thế nào

Công thức Little's Law:

Ví dụ C là bài học quan trọng nhất về scalability: giới hạn thực tế của Runtime không phải concurrent session, mà là new session creation rate. Nếu pattern của bạn là "nhiều session cực ngắn", Runtime là lựa chọn sai.

8.3 Tối ưu latency — theo mức độ hiệu quả

8.4 Pros / Cons / Trade-offs

Pros: scale tự động không cần cấu hình; isolation không đánh đổi bằng performance; warm session cho latency rất tốt ở multi-turn; 200 TPS/agent đủ cho phần lớn use case.

Cons: trần cứng 2 vCPU / 8 GB — không chạy được model local lớn hay in-memory dataset nặng; new session rate là bottleneck ẩn; không có provisioned concurrency để loại bỏ cold start hoàn toàn.

Trade-off: session dài (giảm cold start, tốt cho latency) ⟷ chiếm concurrent session quota + có thể tăng chi phí memory. Cân bằng bằng idleRuntimeSessionTimeout tuned theo hành vi user thật, không đoán.

8.5 Common Mistakes

1. Tạo runtimeSessionId mới cho mỗi turn. Trả cold start mỗi lần + mất hết context. Lỗi phổ biến nhất khi mới dùng.
2. Không có backoff cho ThrottlingException. Retry storm biến throttle nhẹ thành outage.
3. Đặt maxLifetime = 8h cho mọi agent. Session zombie chiếm quota. Set theo bản chất use case.
4. Load model/embedding nặng trong __init__ của handler. Kéo dài cold start; với direct code deploy còn có thể vượt limit package.
5. Gửi payload 80 MB. Đúng luật (≤100 MB) nhưng latency và chi phí tệ. Đưa file lên S3, truyền reference.

9. Cost Optimization

9.1 Bảng giá (thời điểm 07/2026)

9.2 Cách billing của Runtime thực sự hoạt động

Đây là phần bị hiểu sai nhiều nhất:

Ví dụ chính thức của AWS (customer support agent, 10M session/tháng, 60s/session, 70% I/O wait, 1 vCPU active, memory 1→2→2.5 GB):

So sánh với pre-allocated pricing (phải provision 1 vCPU + 2.5 GB cho cả 60 giây): CPU đắt hơn tới 3.3×, memory đắt hơn 1.4×.

9.3 Chiến lược tối ưu — theo thứ tự tác động

9.4 Bẫy chi phí

9.5 Real-world Example

Fintech chạy 3 agent, hoá đơn tháng đầu $47,000 — cao hơn dự toán 4×. Phân tích:

• $31,000 = Bedrock FM token (66%)
• $8,200 = Evaluations chạy 100% production traffic
• $4,100 = CloudWatch (log full prompt + response mỗi span)
• $2,900 = Runtime
• $800 = Gateway + Memory

Runtime chỉ chiếm 6%. Hành động: (1) route intent classification sang Nova Lite → FM giảm 40%; (2) Evaluations sampling xuống 3% → $8,200 → $250; (3) log event thay vì full payload + TTL 30 ngày → $4,100 → $600. Tổng còn ~$21,000, giảm 55%, không chạm gì tới Runtime.

Bài học cho SA: luôn đo phân bổ chi phí trước khi tối ưu. Trực giác về "compute là thứ tốn tiền" đã lỗi thời với GenAI workload.

10. Monitoring & Observability

10.1 Kiến trúc observability

Bước bắt buộc, dễ bỏ sót nhất: bật CloudWatch Transaction Search trước khi deploy. Không bật → trace không đầy đủ, và bạn sẽ debug agent trong mù.

10.2 Bốn tầng telemetry

Điểm đặc thù của agent: trace quan trọng hơn metric. Một agent có p99 latency đẹp, error rate 0%, vẫn có thể trả lời sai 30% thời gian. Chỉ trace + evaluation phát hiện được.

10.3 Metric & alarm nên có

10.4 Best practices

1. Bật Transaction Search trước khi deploy. Không thương lượng.
2. Structured logging (JSON) với session_id, actor_id, trace_id, step, tool_name — để query được bằng CloudWatch Logs Insights.
3. Correlation ID xuyên suốt từ client → Runtime → Gateway → downstream. Không có nó thì không debug được multi-agent.
4. Data protection policy trên log group để mask PII. Trace agent chứa toàn bộ prompt và tool payload.
5. Không log full payload ở production. Log metadata + hash; bật full payload có điều kiện qua flag khi debug.
6. Sampling có chiến lược: 100% error, 100% high-value transaction, 1–5% happy path.
7. Đo cost cạnh chất lượng trên cùng dashboard.
8. TTL cho log group (30–90 ngày) — CloudWatch retention là chi phí dễ bị lãng quên.
9. Evaluations trong CI/CD với quality threshold — chặn deploy khi score tụt.
10. Optimization Insights để đọc pattern qua hàng trăm session thay vì đọc trace từng cái.

10.5 Common Mistakes

• Chỉ monitor error rate → agent "thành công" nhưng sai vẫn lọt.
• Không bật Transaction Search → trace thiếu, không debug được.
• Log full prompt vĩnh viễn → chi phí + rủi ro compliance.
• Không correlation ID trong multi-agent → mất khả năng debug hoàn toàn.
• Coi Evaluations là việc "làm sau" → thường không bao giờ làm.

11. Production Best Practices

11.1 Bảng checklist theo domain

Deployment & Release

Session & State

Reliability

Quality & Governance

11.2 Reference architecture production

Lý do có Lambda BFF ở giữa: đây là nơi duy nhất bạn kiểm soát được việc sinh session ID an toàn, và là nơi đặt logic chọn endpoint (canary routing) mà không phụ thuộc client.

12. Common Pitfalls & Anti-patterns

13. So sánh với các giải pháp tương đương

13.1 AgentCore Runtime vs các compute option của AWS

Khi nào chọn gì:

13.2 AgentCore vs Amazon Bedrock Agents (thế hệ trước)

Với dự án mới: AgentCore là lựa chọn mặc định. AgentCore Harness cho bạn trải nghiệm "1 API call" gần giống Bedrock Agents mà vẫn giữ được framework/model agnostic.

13.3 AgentCore vs các platform khác

Nhận định trung thực: điểm khác biệt kỹ thuật thật sự của AgentCore là (a) mô hình isolation ở biên VM per-session, và (b) mô hình tính phí không tính CPU khi chờ I/O. Hai điều này không có tương đương trực tiếp ở nơi khác tại thời điểm hiện tại. Ngược lại, nếu tổ chức bạn đã chuẩn hoá trên Azure/Entra hoặc Google Workspace, lợi thế tích hợp của các platform kia có thể lớn hơn.

14. Use Cases thực tế

UC1 — Customer Support Agent (use case phổ biến nhất)

Bài toán: trả lời câu hỏi sản phẩm, tra đơn hàng, xử lý hoàn tiền, escalate khi cần. Multi-turn, cần biết lịch sử user.

Kiến trúc: Runtime (HTTP, container) + Memory (STM cho hội thoại + LTM cho preference/lịch sử mua) + Gateway (OrderAPI, TicketAPI, RefundAPI) + Policy (refund ≤ $100 auto, > $100 → HITL) + Identity (Cognito OAuth) + Guardrails.

Vì sao Runtime: hội thoại 8–15 turn — warm session loại bỏ cold start cho turn 2..N; cần isolation vì multi-tenant; I/O wait cao (mỗi turn chờ LLM + API).

Kinh tế (theo ví dụ AWS): 10M session/tháng, 60s/session, 70% I/O wait → ~$7,235/tháng cho Runtime. FM token sẽ lớn hơn nhiều.

UC2 — Deep Research Agent

Bài toán: nhận một câu hỏi nghiên cứu, tự lập kế hoạch, tìm kiếm web, đọc tài liệu, tổng hợp báo cáo 20 trang. Chạy 30–120 phút.

Kiến trúc: Runtime (async pattern, HealthyBusy, maxLifetime = 3h) + Web Search + Browser + Code Interpreter (vẽ chart) + Memory + Session Storage (draft artifact).

Điểm kỹ thuật quyết định: đây là use case mà 8 giờ execution window là điều kiện tiên quyết — Lambda không làm được. Pattern accept-then-poll: trả job_id ngay, worker chạy background, /ping = HealthyBusy.

Cost lưu ý: Web Search $7/1000 query — agent research có thể gọi 50–200 query/job. Đây là dòng chi phí lớn nhất, cần cap.

UC3 — Coding Assistant / SWE Agent

Bài toán: đọc repo, hiểu issue, sửa code, chạy test, tạo PR.

Kiến trúc: Runtime + Session Storage (checkout repo, build artifact — đây chính là use case Session Storage được thiết kế cho) + InvokeAgentRuntimeCommand (chạy shell command deterministic trong cùng session mà agent đang chạy) + Code Interpreter + Gateway (GitHub qua outbound OAuth user-delegated).

Điểm kỹ thuật đặc biệt: InvokeAgentRuntime và InvokeAgentRuntimeCommand hoạt động trên cùng một session — command thấy đúng container, filesystem, environment mà agent đang dùng. Đây là khả năng không có ở Lambda.

Bảo mật: outbound auth phải là user-delegated — agent chỉ chạm được repo mà chính developer đó có quyền.

UC4 — Multi-Agent Financial Analysis

Bài toán: supervisor agent phân rã yêu cầu → agent chuyên biệt (market research, risk, compliance) → tổng hợp.

Kiến trúc: Supervisor trên Runtime (protocol A2A) + mỗi specialist là một Runtime riêng (protocol MCP hoặc A2A) + Registry (discovery) + Gateway + Policy + Observability với correlation ID xuyên suốt.

Vì sao tách runtime riêng: (a) scale độc lập; (b) execution role riêng — agent compliance không cần quyền trading; (c) deploy/rollback độc lập; (d) blast radius nhỏ.

Thách thức lớn nhất: observability. Không có correlation ID xuyên suốt thì debug multi-agent là bất khả thi.

UC5 — Web Automation Agent

Bài toán: đặt vé, điền form trên portal không có API, thu thập giá cạnh tranh.

Kiến trúc: Runtime + Browser (headless managed, Live View để con người can thiệp, Session Replay để audit) + Identity (credential portal) + Policy.

Kinh tế (ví dụ AWS): 100k session/tháng, 10 phút/session, 80% I/O wait → ~$1,227/tháng cho Browser.

Rủi ro cần quản: portal thay đổi UI → agent fail âm thầm. Cần evaluation + alarm trên tool success rate, và Session Replay để root cause.

UC6 — Tool Platform nội bộ (Gateway-centric)

Bài toán: 200 internal API, 12 team, mỗi team muốn xây agent riêng nhưng không muốn ai cũng wrap lại API.

Kiến trúc: Gateway biến 200 API thành MCP tool (semantic search để agent tìm tool đúng) + Policy (Cedar) kiểm soát team nào dùng tool nào + Registry (catalog + approval workflow) + mỗi team tự deploy agent lên Runtime riêng.

Kinh tế (ví dụ AWS): 50M interaction/tháng, 1 Search + 4 InvokeTool mỗi lần → ~$2,250/tháng cho Gateway.

Giá trị thật: đây không phải use case kỹ thuật mà là governance. Một điểm kiểm soát duy nhất cho việc "agent nào được làm gì với hệ thống nào".

15. Ví dụ triển khai bằng Python và AWS SDK

15.1 Agent code — tuân thủ service contract (SDK cách nhanh nhất)

# agent.py — dùng AgentCore Python SDK: tự lo /invocations, /ping, port 8080
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent
from strands.models import BedrockModel

app = BedrockAgentCoreApp()

# Khởi tạo NGOÀI handler → tái dùng cho mọi invocation trong cùng session
model = BedrockModel(model_id="anthropic.claude-sonnet-4-20250514-v1:0")
agent = Agent(
    model=model,
    system_prompt="Bạn là trợ lý hỗ trợ khách hàng. Trả lời ngắn gọn, chính xác.",
)


@app.entrypoint
def invoke(payload: dict, context) -> dict:
    """
    payload : body JSON của POST /invocations
    context : session context do Runtime inject (session_id, v.v.)
    """
    prompt = payload.get("prompt", "")
    if not prompt:
        return {"error": "missing 'prompt'", "status": "error"}

    session_id = getattr(context, "session_id", "unknown")
    result = agent(prompt)

    return {
        "response": result.message,
        "session_id": session_id,
        "status": "success",
    }


if __name__ == "__main__":
    app.run()   # bind 0.0.0.0:8080

15.2 Agent code — implement contract thủ công (khi không dùng SDK)

Hữu ích khi bạn cần hiểu chính xác contract, hoặc dùng framework không phải Python-first.

# manual_agent.py — FastAPI implement đúng service contract
import time
import threading
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse, StreamingResponse

app = FastAPI()

_state = {"busy": False, "last_update": int(time.time())}


# ── /ping : BẮT BUỘC ──────────────────────────────────────────────────
@app.get("/ping")
def ping():
    # HealthyBusy giữ session sống khi có background task (tới 8 giờ)
    status = "HealthyBusy" if _state["busy"] else "Healthy"
    return {"status": status, "time_of_last_update": _state["last_update"]}


# ── /invocations : BẮT BUỘC ───────────────────────────────────────────
@app.post("/invocations")
async def invocations(request: Request):
    body = await request.json()

    # Session ID được Runtime truyền qua header
    session_id = request.headers.get(
        "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id", "unknown"
    )

    # ---- Pattern async: accept-then-poll cho job dài ----
    if body.get("mode") == "async":
        job_id = f"job-{int(time.time())}"
        _state["busy"] = True
        _state["last_update"] = int(time.time())
        threading.Thread(target=_long_job, args=(job_id,), daemon=True).start()
        return JSONResponse({"job_id": job_id, "status": "accepted"})

    # ---- Streaming SSE (chunk ≤ 10 MB) ----
    if body.get("stream"):
        def gen():
            for token in _agent_stream(body["prompt"]):
                yield f'data: {{"event": {token!r}}}\n\n'
        return StreamingResponse(gen(), media_type="text/event-stream")

    # ---- Sync JSON (phải xong trong 15 phút) ----
    return JSONResponse({
        "response": _agent_run(body.get("prompt", "")),
        "session_id": session_id,
        "status": "success",
    })


def _long_job(job_id: str):
    try:
        time.sleep(1800)                     # công việc thật tới 8 giờ
        # ghi kết quả ra DynamoDB / S3 / AgentCore Memory
    finally:
        _state["busy"] = False               # → /ping trở lại "Healthy"
        _state["last_update"] = int(time.time())


def _agent_run(prompt: str) -> str: ...
def _agent_stream(prompt: str): ...


if __name__ == "__main__":
    import uvicorn
    # PHẢI là 0.0.0.0:8080 — bind 127.0.0.1 sẽ không nhận được traffic
    uvicorn.run(app, host="0.0.0.0", port=8080)

15.3 Dockerfile — ARM64 là bắt buộc

# --platform linux/arm64 KHÔNG được bỏ. Runtime chạy trên Graviton.
FROM --platform=linux/arm64 public.ecr.aws/docker/library/python:3.12-slim

WORKDIR /app

# Layer dependency riêng để cache tốt hơn
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

ENV PYTHONUNBUFFERED=1
EXPOSE 8080

CMD ["python", "manual_agent.py"]

# Build & push — image ≤ 2 GB
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=us-west-2
REPO=my-support-agent

aws ecr create-repository --repository-name $REPO --region $REGION
aws ecr get-login-password --region $REGION \
  | docker login --username AWS --password-stdin $ACCOUNT.dkr.ecr.$REGION.amazonaws.com

docker buildx build --platform linux/arm64 \
  -t $ACCOUNT.dkr.ecr.$REGION.amazonaws.com/$REPO:v1 --push .

15.4 Tạo Runtime bằng boto3 (control plane)

"""create_runtime.py — dùng bedrock-agentcore-control (CONTROL plane)."""
import boto3

REGION = "us-west-2"
ACCOUNT = boto3.client("sts").get_caller_identity()["Account"]

cp = boto3.client("bedrock-agentcore-control", region_name=REGION)

resp = cp.create_agent_runtime(
    agentRuntimeName="support-agent",
    description="Customer support agent, Strands + Claude",

    # ── Container deployment ──
    agentRuntimeArtifact={
        "containerConfiguration": {
            "containerUri": f"{ACCOUNT}.dkr.ecr.{REGION}.amazonaws.com/my-support-agent:v1"
        }
    },

    roleArn=f"arn:aws:iam::{ACCOUNT}:role/AmazonBedrockAgentCoreSupportAgentRole",

    # PUBLIC hoặc VPC. VPC cần thêm subnet/securityGroup — verify theo region.
    networkConfiguration={"networkMode": "PUBLIC"},

    protocolConfiguration={"serverProtocol": "HTTP"},   # HTTP | MCP | A2A

    # ⚠️ KHÔNG đặt secret ở đây — env var lộ qua GetAgentRuntime và log
    environmentVariables={
        "LOG_LEVEL": "INFO",
        "MEMORY_ID": "mem-abc123",
        "GATEWAY_URL": "https://gw-xyz.gateway.bedrock-agentcore.us-west-2.amazonaws.com",
    },

    # ── Inbound Auth: OAuth2 JWT ──
    # Bỏ block này => mặc định IAM SigV4
    authorizerConfiguration={
        "customJWTAuthorizer": {
            "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/"
                            "us-west-2_XXXX/.well-known/openid-configuration",
            "allowedAudience": ["my-app-client-id"],
            "allowedClients": ["my-app-client-id"],
        }
    },

    # ── Lifecycle: tune theo hành vi user thật, đừng để mặc định ──
    lifecycleConfiguration={
        "idleRuntimeSessionTimeout": 300,   # 5 phút (default 900 = 15 phút)
        "maxLifetime": 3600,                # 1 giờ (max 28800 = 8 giờ)
    },

    tags={
        "Environment": "production",
        "CostCenter": "cs-platform",
        "Owner": "support-eng",
    },
)

print("Runtime ARN:", resp["agentRuntimeArn"])
print("Version    :", resp["agentRuntimeVersion"])   # V1
print("Status     :", resp["status"])
# DEFAULT endpoint được tạo tự động và TRỎ TỚI VERSION MỚI NHẤT

15.5 Tạo named endpoint cho production (đừng dùng DEFAULT)

"""create_endpoints.py — endpoint riêng = kiểm soát version + rollback được."""
import boto3, time

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
RUNTIME_ID = "support-agent-abc123"

for name, version in [("prod", "1"), ("canary", "1")]:
    cp.create_agent_runtime_endpoint(
        agentRuntimeId=RUNTIME_ID,
        name=name,
        agentRuntimeVersion=version,
        description=f"{name} endpoint",
    )

# Chờ READY trước khi invoke
def wait_ready(endpoint_name: str, timeout: int = 300):
    deadline = time.time() + timeout
    while time.time() < deadline:
        st = cp.get_agent_runtime_endpoint(
            agentRuntimeId=RUNTIME_ID, endpointName=endpoint_name
        )["status"]
        if st == "READY":
            return
        if st in ("CREATE_FAILED", "UPDATE_FAILED"):
            raise RuntimeError(f"{endpoint_name} → {st}")
        time.sleep(5)
    raise TimeoutError(endpoint_name)

wait_ready("prod")
wait_ready("canary")


# ── Canary promote / rollback: version immutable nên đây là thao tác an toàn ──
def point_endpoint(endpoint_name: str, version: str):
    cp.update_agent_runtime_endpoint(
        agentRuntimeId=RUNTIME_ID,
        endpointName=endpoint_name,
        agentRuntimeVersion=version,
    )
    wait_ready(endpoint_name)

# point_endpoint("canary", "2")   # thử version mới trên canary
# point_endpoint("prod",   "2")   # soak xong → promote
# point_endpoint("prod",   "1")   # rollback tức thì

15.6 Invoke — sync, streaming, và session management đúng cách

"""invoke.py — CLIENT SIDE. Chú ý cách sinh session ID."""
import hashlib
import hmac
import json
import os
import time
import random
import boto3
from botocore.exceptions import ClientError

dp = boto3.client("bedrock-agentcore", region_name="us-west-2")  # DATA plane
AGENT_ARN = os.environ["AGENT_RUNTIME_ARN"]
SESSION_SECRET = os.environ["SESSION_SECRET"].encode()


# ── Session ID: sinh SERVER-SIDE, cryptographic, bind với user đã auth ──
def make_session_id(user_sub: str, conversation_id: str) -> str:
    """
    KHÔNG cho client tự chọn session ID tuỳ ý.
    Session ID đoán được = hijack được session người khác = phá vỡ isolation.
    Lưu ý: InvokeAgentRuntimeCommand yêu cầu session ID tối thiểu 33 ký tự.
    """
    mac = hmac.new(
        SESSION_SECRET, f"{user_sub}:{conversation_id}".encode(), hashlib.sha256
    ).hexdigest()
    return f"s-{mac}"          # 66 ký tự, an toàn


# ── Retry với exponential backoff + jitter cho ThrottlingException ──
def invoke_with_retry(session_id: str, payload: dict, qualifier="prod", max_retry=5):
    for attempt in range(max_retry):
        try:
            return dp.invoke_agent_runtime(
                agentRuntimeArn=AGENT_ARN,
                runtimeSessionId=session_id,
                qualifier=qualifier,
                payload=json.dumps(payload).encode(),
            )
        except ClientError as e:
            code = e.response["Error"]["Code"]
            if code in ("ThrottlingException", "ServiceQuotaExceededException") \
               and attempt < max_retry - 1:
                sleep = (2 ** attempt) + random.uniform(0, 1)   # jitter bắt buộc
                time.sleep(sleep)
                continue
            raise


# ── Hội thoại nhiều turn: DÙNG LẠI cùng session ID ──
def chat(user_sub: str, conversation_id: str, turns: list[str]):
    session_id = make_session_id(user_sub, conversation_id)
    for turn in turns:
        resp = invoke_with_retry(session_id, {"prompt": turn})
        body = b"".join(resp["response"]).decode()
        print(f"USER : {turn}")
        print(f"AGENT: {json.loads(body)['response']}\n")
    return session_id


# ── Streaming SSE ──
def chat_stream(session_id: str, prompt: str):
    resp = dp.invoke_agent_runtime(
        agentRuntimeArn=AGENT_ARN,
        runtimeSessionId=session_id,
        qualifier="prod",
        payload=json.dumps({"prompt": prompt, "stream": True}).encode(),
    )
    if "text/event-stream" in resp.get("contentType", ""):
        for line in resp["response"].iter_lines(chunk_size=1):
            if line and line.decode().startswith("data: "):
                print(line.decode()[6:], end="", flush=True)


# ── Dừng session chủ động khi hội thoại kết thúc → tiết kiệm chi phí + quota ──
def end_conversation(session_id: str):
    dp.stop_runtime_session(
        agentRuntimeArn=AGENT_ARN,
        runtimeSessionId=session_id,
        qualifier="prod",
    )


if __name__ == "__main__":
    sid = chat(
        user_sub="cognito-sub-1234",
        conversation_id="conv-987",
        turns=[
            "Đơn hàng A102 của tôi đến khi nào?",
            "Đổi địa chỉ giao sang Hà Nội được không?",   # WARM — không cold start
            "Cảm ơn.",
        ],
    )
    end_conversation(sid)

15.7 Deploy nhanh bằng AgentCore CLI (cho dev, không cho production)

# CLI phân phối qua npm, cần Node 20+, Python 3.10+, AWS CDK
npm install -g @aws/agentcore

# Scaffold project
agentcore create --name MyAgent \
  --framework Strands \        # Strands | LangChain_LangGraph | GoogleADK | OpenAIAgents
  --protocol HTTP \            # HTTP | MCP | A2A
  --build CodeZip \            # CodeZip (không cần Docker) | Container
  --model-provider Bedrock \
  --memory shortTerm           # none | shortTerm | longAndShortTerm

cd MyAgent

# Dev local — mô phỏng môi trường Runtime, hot reload, có agent inspector
agentcore dev
agentcore dev "Xin chào"          # invoke local

# Deploy (dùng CDK → CloudFormation)
agentcore deploy --plan            # xem trước, không thay đổi gì
agentcore deploy

# Test & quan sát
agentcore invoke --prompt "Kể chuyện cười" --stream
agentcore invoke --session-id my-session "Còn gì nữa không?"
agentcore status
agentcore logs
agentcore traces list

# Dọn dẹp
agentcore remove all && agentcore deploy

15.8 IAM — execution role least-privilege

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TrustAgentCore",
      "Effect": "Allow",
      "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "aws:SourceAccount": "111122223333" },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:*"
        }
      }
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "InvokeSpecificModelsOnly",
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
      "Resource": [
        "arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-sonnet-4-*",
        "arn:aws:bedrock:us-west-2::foundation-model/amazon.nova-lite-*"
      ]
    },
    {
      "Sid": "ApplyGuardrail",
      "Effect": "Allow",
      "Action": "bedrock:ApplyGuardrail",
      "Resource": "arn:aws:bedrock:us-west-2:111122223333:guardrail/gr-abc123"
    },
    {
      "Sid": "MemoryScopedToOneResource",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateEvent",
        "bedrock-agentcore:ListEvents",
        "bedrock-agentcore:RetrieveMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:memory/mem-abc123"
    },
    {
      "Sid": "GatewayToolsScoped",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeGateway",
      "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/gw-xyz789"
    },
    {
      "Sid": "SecretsScopedByPath",
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-west-2:111122223333:secret:support-agent/*"
    },
    {
      "Sid": "Telemetry",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams",
        "xray:PutTraceSegments", "xray:PutTelemetryRecords"
      ],
      "Resource": "*"
    }
  ]
}

Đối chiếu: AWS cung cấp managed policy BedrockAgentCoreFullAccess — dùng để explore, không dùng ở production. AWS cũng khuyến nghị tự copy các statement cần thiết và thu hẹp resource.

15.9 CloudFormation — IaC cho production

AWSTemplateFormatVersion: '2010-09-09'
Description: AgentCore Runtime — production pattern

Parameters:
  ImageUri:      { Type: String }
  AgentVersion:  { Type: String, Default: "1" }

Resources:
  ExecutionRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal: { Service: bedrock-agentcore.amazonaws.com }
            Action: sts:AssumeRole
            Condition:
              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }
      Policies:
        - PolicyName: least-privilege
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action: [bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream]
                Resource: !Sub 'arn:aws:bedrock:${AWS::Region}::foundation-model/anthropic.claude-sonnet-4-*'
              - Effect: Allow
                Action: [logs:CreateLogStream, logs:PutLogEvents, xray:PutTraceSegments]
                Resource: '*'

  SupportAgent:
    Type: AWS::BedrockAgentCore::Runtime
    Properties:
      AgentRuntimeName: support-agent
      Description: Customer support agent
      AgentRuntimeArtifact:
        ContainerConfiguration:
          ContainerUri: !Ref ImageUri
      RoleArn: !GetAtt ExecutionRole.Arn
      NetworkConfiguration:
        NetworkMode: PUBLIC
      ProtocolConfiguration:
        ServerProtocol: HTTP
      EnvironmentVariables:
        LOG_LEVEL: INFO
      Tags:
        - { Key: Environment, Value: production }
        - { Key: CostCenter,  Value: cs-platform }

  # Named endpoint — KHÔNG dùng DEFAULT cho production
  ProdEndpoint:
    Type: AWS::BedrockAgentCore::RuntimeEndpoint
    Properties:
      AgentRuntimeId: !GetAtt SupportAgent.AgentRuntimeId
      Name: prod
      AgentRuntimeVersion: !Ref AgentVersion

Outputs:
  AgentRuntimeArn: { Value: !GetAtt SupportAgent.AgentRuntimeArn }

15.10 Test contract trong CI trước khi deploy

"""test_contract.py — chạy trong CI. Bắt 90% lỗi deploy trước khi lên AWS."""
import subprocess, time, requests, pytest

BASE = "http://localhost:8080"


@pytest.fixture(scope="module")
def container():
    subprocess.run(
        ["docker", "buildx", "build", "--platform", "linux/arm64",
         "--load", "-t", "agent-test", "."], check=True
    )
    cid = subprocess.check_output(
        ["docker", "run", "-d", "-p", "8080:8080", "agent-test"]
    ).decode().strip()
    for _ in range(30):
        try:
            if requests.get(f"{BASE}/ping", timeout=2).status_code == 200:
                break
        except requests.RequestException:
            time.sleep(1)
    yield cid
    subprocess.run(["docker", "rm", "-f", cid], check=False)


def test_arm64_architecture():
    """Lỗi phổ biến nhất: build x86, deploy OK, container không chạy."""
    out = subprocess.check_output(
        ["docker", "inspect", "--format", "{{.Architecture}}", "agent-test"]
    ).decode().strip()
    assert out == "arm64", f"Phải là arm64, đang là {out}"


def test_ping_contract(container):
    r = requests.get(f"{BASE}/ping")
    assert r.status_code == 200
    body = r.json()
    assert body["status"] in ("Healthy", "HealthyBusy")
    assert isinstance(body["time_of_last_update"], int)


def test_invocations_json(container):
    r = requests.post(f"{BASE}/invocations", json={"prompt": "hello"})
    assert r.status_code == 200
    assert "application/json" in r.headers["content-type"]


def test_invocations_sse(container):
    r = requests.post(f"{BASE}/invocations",
                      json={"prompt": "hello", "stream": True}, stream=True)
    assert "text/event-stream" in r.headers["content-type"]


def test_image_size_under_2gb():
    size = int(subprocess.check_output(
        ["docker", "inspect", "--format", "{{.Size}}", "agent-test"]
    ).decode().strip())
    assert size < 2 * 1024**3, f"Image {size/1024**3:.2f} GB > 2 GB"

16. Kiến trúc minh họa (ASCII)

16.1 Toàn cảnh AgentCore platform

16.2 Runtime: quan hệ Version ↔ Endpoint ↔ Session

16.3 Session isolation — so sánh với Lambda

16.4 Cost model — tại sao "I/O wait miễn phí" quan trọng

16.5 Async long-running pattern

17. Checklist dành cho Solution Architect

Phase 0 — Đánh giá phù hợp (làm TRƯỚC khi viết code)

• Workload có stateful trong session không? (nếu không → xem lại Lambda)
• Session lifetime dự kiến? (< 15 phút → Lambda có thể rẻ hơn; 15 phút–8h → Runtime; > 8h → Fargate/Step Functions)
• Tỉ lệ I/O wait ước tính? (< 30% → lợi thế billing của Runtime giảm đáng kể)
• Peak resource cần thiết ≤ 2 vCPU / 8 GB? (nếu không → Fargate/EKS)
• Tính new session rate cần thiết? (> 6.7/s container hoặc > 25/s direct code → SAI kiến trúc)
• Có yêu cầu compliance về cross-tenant isolation cần chứng minh với auditor?
• Region cần thiết có AgentCore không? (verify — availability hẹp hơn Bedrock core; quan trọng với data residency VN)
• Team có framework agent sẵn không? (có → giữ nguyên; không → Strands)
• Đã tính TCO bao gồm FM token chưa? (FM thường 60–90% hoá đơn)

Phase 1 — Thiết kế

• Chọn deployment mode: container (system dependency) vs direct code (iteration nhanh, session rate cao hơn)
• Chọn protocol: HTTP (agent) / MCP (tool server) / A2A (multi-agent)
• Thiết kế session ID scheme: server-side, cryptographic, bind với authenticated user, ≥ 33 ký tự
• Quyết định state boundary: gì ở trong session (ephemeral), gì ra Memory/DDB/S3 (durable)
• Chọn inbound auth: IAM SigV4 (service-to-service) vs OAuth2 JWT (end-user)
• Chọn outbound auth mode: user-delegated (mặc định) vs autonomous (chỉ khi bắt buộc)
• Thiết kế endpoint strategy: dev / staging / prod / canary — không dùng DEFAULT cho prod
• Tune idleRuntimeSessionTimeout và maxLifetime theo use case, không để mặc định
• Quyết định primitive nào dùng phase 1 (khuyến nghị: Runtime + Observability)
• Network mode: PUBLIC hay VPC? Nếu VPC → subnet, SG, endpoint cần thiết
• Threat model: prompt injection (direct + indirect), session hijacking, excessive agency, exfiltration
• Xác định hành động nào cần HITL và hành động nào cần Policy (Cedar)
• Capacity plan: Little's Law → concurrent session cần → so với quota → xin tăng nếu cần

Phase 2 — Triển khai

• Contract test trong CI: ARM64, 0.0.0.0:8080, /invocations, /ping, image ≤ 2 GB
• Execution role least-privilege (không dùng BedrockAgentCoreFullAccess)
• Secret ở Secrets Manager / Identity vault, không ở environment variables
• IaC (CloudFormation/CDK) cho mọi environment
• Structured JSON logging với session_id, trace_id, actor_id, step
• Bật CloudWatch Transaction Search — bước bị bỏ sót nhiều nhất
• Data protection policy trên log group (mask PII)
• Exponential backoff + jitter ở client cho ThrottlingException
• Idempotency key cho mọi tool call có side effect
• Max iteration cap cho agent loop
• /ping trả HealthyBusy đúng khi có background task
• Golden dataset + Evaluations trong CI/CD với quality threshold
• Cost allocation tag trên mọi resource

Phase 3 — Trước khi lên production

• Load test tới quota giới hạn (concurrent session, TPS, new session rate)
• Test rollback path thật (UpdateAgentRuntimeEndpoint về version cũ)
• Test hành vi khi session terminate giữa hội thoại (context rỗng → reload từ Memory)
• Test throttling behaviour đầu-cuối
• Alarm: error rate, throttle, session count vs quota, cold start rate, evaluation score
• CloudTrail + alert cho control plane operation bất thường
• Runbook: agent sai / loop / throttle / downstream down / cost spike
• Security review: threat model đã có mitigation cho từng mục
• Chi phí thực tế từ staging đã extrapolate ra production và được approve
• Xác nhận không có preview feature nào trên critical path (Session Storage, Registry, Payments, Optimization Insights)

Phase 4 — Vận hành liên tục

• Review Evaluations score theo tuần (không chỉ khi có incident)
• Review Optimization Insights theo tháng để tìm failure pattern
• Cost review theo tháng, phân bổ theo tag, so với baseline
• Cập nhật golden dataset từ production failure
• Theo dõi release notes AgentCore (quota, feature, GA của preview) — service thay đổi nhanh
• Audit định kỳ: execution role còn least-privilege? Policy còn đúng business rule?

18. Interview Questions & Answers

Q1. AgentCore Runtime khác Lambda ở đâu về bản chất, không chỉ về timeout?

Ba khác biệt cấu trúc. (1) Đơn vị isolation: Lambda isolate ở mức execution environment và reuse nó giữa các request — bạn phải tự đảm bảo không rò state. Runtime isolate ở mức microVM per session, huỷ và sanitize memory khi xong; điều này chứng minh được với auditor. (2) Mô hình state: Lambda stateless — mọi state phải serialize ra ngoài sau mỗi invocation. Runtime giữ context (RAM, biến, file tạm) xuyên nhiều invocation trong cùng session, nên turn 2..N của hội thoại không phải rebuild context. (3) Mô hình tính phí: Lambda tính GB-second theo memory allocated cho toàn bộ duration. Runtime tính CPU theo mức tiêu thụ thật — thời gian chờ I/O không tính tiền CPU. Với agent workload có 30–70% I/O wait, chênh lệch CPU cost lên tới 3.3× theo ví dụ chính thức của AWS.

Q2. Container của bạn phải thoả những gì để chạy được trên Runtime?

Bốn container requirement: bind 0.0.0.0 (không phải 127.0.0.1), port 8080, platform ARM64 (Graviton), image ≤ 2 GB. Hai HTTP path bắt buộc: POST /invocations (input JSON, output JSON hoặc SSE text/event-stream) và GET /ping (trả {"status": "Healthy"|"HealthyBusy", "time_of_last_update": <unix>}). Tuỳ chọn: /ws cho WebSocket, cùng port 8080. Hai lỗi thường gặp nhất là build image x86 (deploy thành công nhưng container không chạy) và bind localhost (test local OK, production không nhận traffic).

Q3. /ping để làm gì ngoài health check?

Nó là cơ chế điều khiển lifecycle của session cho workload async. Khi agent đang chạy background task, trả HealthyBusy → Runtime hiểu session vẫn active và không terminate vì idle. Đây là cách chính thức để chạy job tới 8 giờ mà không giữ HTTP connection mở. Pattern đúng là accept-then-poll: /invocations trả job_id ngay trong dưới 15 phút, worker chạy background, /ping báo HealthyBusy, client poll trạng thái bằng invocation nhẹ cùng session ID. Nhiều team bỏ qua chi tiết này rồi thắc mắc tại sao job bị kill sau 15 phút.

Q4. Giải thích quan hệ Version, Endpoint, Session — và cái bẫy ở đây.

AgentRuntime là logical resource có ARN. Mỗi lần UpdateAgentRuntime tạo một Version immutable, chứa toàn bộ snapshot config (image/code, protocol, network, env). Endpoint là alias trỏ tới một version cụ thể — bạn chọn qua tham số qualifier khi invoke. Session là runtime instance: một runtimeSessionId = một microVM, phục vụ nhiều invocation.

Cái bẫy: endpoint DEFAULT được tạo tự động và tự động trỏ sang version mới nhất mỗi lần update. Nếu production dùng DEFAULT, mọi deploy là big-bang không có canary. Best practice: production dùng named endpoint pin vào version cụ thể. Vì version immutable, rollback chỉ là UpdateAgentRuntimeEndpoint trỏ về version cũ — tức thì, zero-downtime.

Q5. Điều gì xảy ra nếu tôi invoke lại cùng runtimeSessionId sau khi session đã terminate?

Runtime tạo execution environment hoàn toàn mới — microVM mới, filesystem sạch, context rỗng. Session ID không phải là handle bền. Session terminate khi: 15 phút không hoạt động (điều chỉnh qua idleRuntimeSessionTimeout), đạt 8 giờ tổng (maxLifetime), hoặc bị coi là unhealthy. Hệ quả thiết kế: mọi state cần bền phải nằm ngoài session — AgentCore Memory, DynamoDB, S3. Và code agent phải xử lý được tình huống "session mới, context rỗng" một cách graceful bằng cách reload từ store bền, không crash.

Q6. Làm sao bạn thiết kế runtimeSessionId cho một app multi-tenant?

Đây là câu hỏi bảo mật, không phải câu hỏi tiện lợi. Session ID phải: (a) sinh server-side, không để client tự chọn tuỳ ý; (b) không đoán được — dùng HMAC(user_sub, conversation_id, server_secret) hoặc UUIDv4 có map server-side; (c) bind với identity đã xác thực; (d) tối thiểu 33 ký tự nếu dùng InvokeAgentRuntimeCommand.

Lý do: session isolation của AgentCore chỉ có ý nghĩa nếu attacker không đoán được session ID của người khác. Nếu bạn dùng session ID đoán được (ví dụ user_id thuần, hay số tăng dần), bạn đã tự tay phá vỡ toàn bộ isolation model mà AWS cung cấp. Và tuyệt đối không pool/share session giữa nhiều user để "tiết kiệm cold start" — đó là lỗi thiết kế nghiêm trọng nhất có thể mắc.

Q7. Session isolation có bảo vệ bạn khỏi prompt injection không?

Không, và đây là sự nhầm lẫn rất phổ biến. Isolation chống cross-session contamination — session A không đọc được dữ liệu session B. Prompt injection là tấn công trong session: attacker điều khiển agent làm sai ý định trong chính session của họ, với chính quyền của session đó.

Chống prompt injection cần lớp khác: Bedrock Guardrails cho input/output; AgentCore Policy (Cedar) intercept mọi tool call trước khi execute — deterministic, không phụ thuộc vào việc LLM có "nghe lời" hay không; execution role least-privilege để giới hạn thiệt hại; HITL cho hành động không đảo ngược; và quan trọng nhất là coi mọi tool output là untrusted input (indirect injection qua PDF, web page, ticket).

Q8. Khi nào bạn KHÔNG nên dùng AgentCore Runtime?

Bốn trường hợp rõ ràng. (1) Request ngắn stateless volume cao: new session rate là bottleneck ẩn — 400 TPM cho container mode (~6.7/s), 25 TPS cho direct code. Nếu bạn cần 500 request/s, mỗi request một session, Runtime là sai kiến trúc; dùng Lambda. (2) Cần > 2 vCPU / 8 GB hoặc > 8 giờ: trần cứng, không điều chỉnh được → Fargate/EKS. (3) Batch data processing / ETL: không có I/O wait để tận dụng lợi thế billing, và throughput không phải điểm mạnh → Glue/EMR. (4) Workload CPU-bound liên tục: lợi thế "I/O wait miễn phí" biến mất, pre-allocated có thể rẻ hơn.

Q9. Chi phí AgentCore Runtime được tính thế nào, và tối ưu ở đâu?

$0.0895/vCPU-hour cho CPU tiêu thụ thật + $0.00945/GB-hour cho peak memory tới thời điểm đó, tính per-second, tối thiểu 1 giây và 128 MB. Phạm vi tính từ microVM boot → init → active → idle → terminate, bao gồm system overhead.

Hai chi tiết quan trọng: (a) CPU không tính khi chờ I/O — đây là lợi thế lớn nhất; (b) memory tính theo peak, nên một spike 4 GB trong 2 giây làm bạn trả 4 GB cho phần còn lại của session → tối ưu peak memory quan trọng hơn tối ưu average.

Nhưng câu trả lời hoàn chỉnh phải nói: ở hầu hết kiến trúc thực tế, FM token chiếm 60–90% hoá đơn, Runtime thường chỉ 5–10%. Tối ưu Runtime trước khi tối ưu token là sai thứ tự. Thứ tự đúng: đo phân bổ chi phí → tối ưu FM (model routing, prompt gọn) → tối ưu Evaluations/Observability sampling → cuối cùng mới tới Runtime.

Q10. Thiết kế canary deployment cho một agent trên Runtime.

Version immutable là nền tảng. Tạo hai named endpoint: prod pin V(n), canary pin V(n+1). Runtime không có built-in traffic splitting, nên việc chia traffic làm ở tầng trên — thường là Lambda BFF hoặc application logic: 95% request gửi qualifier="prod", 5% gửi qualifier="canary", chia theo user cohort để trải nghiệm nhất quán.

Gate promotion không chỉ là error rate: cần Evaluations score (correctness, goal success rate) so sánh giữa hai endpoint, cộng latency p95, token/session, tool error rate. Soak 24–48 giờ. Promote = UpdateAgentRuntimeEndpoint("prod", version=n+1). Rollback = trỏ lại V(n) — tức thì vì version cũ vẫn còn nguyên. Điểm quan trọng thường bị quên: test rollback path trước khi cần đến nó.

Q11. Multi-agent trên AgentCore: một runtime hay nhiều runtime?

Nhiều runtime, với bốn lý do. (1) Execution role riêng — agent compliance không cần quyền trading; đây là least-privilege ở mức kiến trúc. (2) Scale độc lập — mỗi agent có pattern traffic khác nhau. (3) Deploy/rollback độc lập — không phải redeploy supervisor khi sửa một specialist. (4) Blast radius nhỏ — một agent lỗi không kéo cả hệ thống.

Supervisor dùng protocol A2A để communicate và discover; specialist có thể expose qua MCP để dùng như tool. Registry giúp discovery ở quy mô tổ chức. Thách thức lớn nhất không phải kỹ thuật orchestration mà là observability: không có correlation ID xuyên suốt tất cả các hop, debug multi-agent là bất khả thi. Đây là thứ phải thiết kế từ ngày đầu, không thể thêm sau.

Q12. AgentCore Memory khác gì với việc tự lưu hội thoại vào DynamoDB?

Memory có hai tầng. Short-term memory lưu raw event trong session — về cơ bản bạn tự làm được bằng DynamoDB. Long-term memory là phần giá trị thật: nó chạy pipeline extraction/consolidation để rút ra fact, preference, summary, episodic memory từ raw event, rồi cho retrieve semantic — bạn tự build sẽ cần vector DB + embedding pipeline + prompt tóm tắt + logic dedupe/conflict resolution.

Trade-off cụ thể: built-in strategy $0.75/1000 record/tháng (AWS lo hết) vs self-managed/override $0.25/1000 (bạn kiểm soát model và prompt, nhưng trả model cost riêng). Chọn self-managed khi bạn cần kiểm soát chính xác cái gì được nhớ — ví dụ ngành y tế cần lọc PHI trước khi lưu.

Q13. Bạn triển khai agent cho khách hàng ở Việt Nam có yêu cầu data residency. Cân nhắc gì?

Ba việc phải làm theo thứ tự. (1) Verify region availability — AgentCore không có ở mọi region, và tập region hẹp hơn Bedrock core. Đây là ràng buộc cứng, phải xác nhận trước khi thiết kế bất cứ thứ gì. (2) Vẽ data flow đầy đủ — không chỉ Runtime: FM inference ở đâu (cross-region inference profile có thể route ra ngoài region!), Memory lưu ở đâu, CloudWatch log ở region nào, Gateway target ở đâu. Trace agent chứa full prompt nên log cũng là dữ liệu cá nhân. (3) Nếu region không đủ — cân nhắc kiến trúc hybrid: agent orchestration ở region có AgentCore, nhưng dữ liệu sensitive không bao giờ vào prompt (dùng tokenization/reference), hoặc self-host trên EKS trong region yêu cầu và chỉ dùng Gateway/Identity làm control plane.

Tôi sẽ không cam kết kiến trúc nào cho khách hàng trước khi verify được (1) và (2) bằng tài liệu chính thức tại thời điểm đó, vì availability thay đổi liên tục.

Q14. Làm sao bạn biết agent của mình đang hoạt động ĐÚNG ở production?

Metric truyền thống không trả lời được câu này. Một agent có p99 latency đẹp và error rate 0% vẫn có thể trả lời sai 30% thời gian — đó là "success" về mặt kỹ thuật và "failure" về mặt nghiệp vụ.

Cần bốn tầng: Metrics (hệ thống có khoẻ không) → Logs (chuyện gì xảy ra ở request này) → Traces (vì sao agent quyết định như vậy, chậm ở đâu — cần bật CloudWatch Transaction Search trước khi deploy) → Evaluations (agent trả lời đúng không). Tầng thứ tư là tầng bị bỏ qua nhiều nhất và quan trọng nhất.

Cụ thể: golden dataset + Evaluations trong CI/CD với quality threshold chặn deploy; production sampling 2–5% (100% sẽ tốn hơn cả Runtime); alarm trên evaluation score giảm, không chỉ error rate tăng; và Optimization Insights để đọc failure pattern qua hàng trăm session thay vì đọc trace từng cái.

Q15. Trade-off lớn nhất khi chọn AgentCore là gì?

Bạn đánh đổi quyền kiểm soát hạ tầng để lấy isolation model + billing model + operational simplicity. Cụ thể mất: không chọn instance type, trần 2 vCPU / 8 GB, ARM64-only, image ≤ 2 GB, region availability hẹp hơn, và một số capability còn ở preview.

Với agent workload đúng nghĩa (stateful, I/O-heavy, multi-tenant, cần chứng minh isolation), đây gần như luôn là đánh đổi đúng — vì tự build lại session isolation ở mức microVM, identity vault, OTEL agent tracing và consumption billing là hàng người-năm engineering.

Với workload không phải agent, đây là đánh đổi sai. Cách tôi quyết định: nếu workload không có ít nhất 3 trong 4 đặc tính (stateful trong session, > 15 phút, > 30% I/O wait, cần isolation chứng minh được), tôi sẽ đề xuất Lambda hoặc Fargate.