13. AgentCore adapter
이 장에서 처음 나오는 말5개
AgentCore RuntimeAmazon Bedrock AgentCore Runtime- Agent code를 AWS가 session 단위로 격리·실행·확장하는 관리형 환경이다.
PrivateLinkAWS PrivateLink- VPC의 private IP를 통해 AWS service API를 호출해 public internet traversal을 피하는 방식이다.
custom JWT authorizerCustom JWT Authorizer- 사내 IdP token의 issuer·audience·scope·claim을 runtime 앞에서 검증하는 기능이다.
CedarCedar Policy Language- AgentCore Gateway tool action을 결정적으로 허용·거부하는 policy 언어다.
CodeZipDirect Code Deployment- Agent code와 dependency를 ZIP으로 묶어 S3에서 Runtime에 배포하는 AgentCore artifact 방식이다.
전체 중 AgentCore의 자리
섹션 제목: “전체 중 AgentCore의 자리”
private 경로를 써도 runtime control/data plane과 session compute는 AWS region에 있다. “인터넷을 안 지난다”와 “data가 온프렘을 떠나지 않는다”를 같은 말로 쓰지 않는다.
Runtime contract와 격리
섹션 제목: “Runtime contract와 격리”AgentCore Runtime은 custom code와 LangGraph·CrewAI·ADK 같은 framework를 Container 또는 CodeZip으로 실행한다. HTTP, MCP, A2A, AG-UI contract를 지원하며 version과 endpoint를 관리한다. Runtime은 ARM64에서 동작하므로 container image와 CodeZip의 native dependency가 Linux ARM64인지 adapter가 검증한다.
각 runtime session은 전용 microVM의 compute·memory·filesystem으로 격리된다. idle timeout이나 최대 lifecycle에 도달하면 compute는 종료되고, 필요한 상태는 Memory나 session storage로 내린다. 단, AWS도 user와 session ID의 연결은 client backend가 관리해야 한다고 명시한다.
Agent 타입 enum이 없다
섹션 제목: “Agent 타입 enum이 없다”kagent의 Agent.spec.type이나 Dapr Agents의 클래스처럼 Agent 종류에 이름을 붙이는 API가 AgentCore에는
없다. Runtime은 framework를 가리지 않고 artifact를 받고, 구분은 두 곳에서만 나타난다 — artifact가
따르는 protocol contract와 session lifecycle이다. 즉 AgentCore는
Agent 종류 분류의 격리(MICROVM)와
managed 상주 축에 답하고, 작성 방식·활성화 축은 기록할 자리가 없으므로 platform domain model이 소유한다.
구성형 Agent를 이 target에 두려면 adapter가 platform 공통 runtime artifact에 prompt·knowledge·tool binding을
주입해 코드형과 같은 배포물로 번역한다. 행위 위험 차원은 Gateway의 Cedar Policy라는 별도 층이 맡는다.
Container와 CodeZip을 정책으로 고른다
섹션 제목: “Container와 CodeZip을 정책으로 고른다”AgentCore CLI 문서는 CodeZip과 Container 두 build type을 지원하고 CodeZip을 CLI 기본값으로 제시한다. 그러나 provider 기본값과 회사 production 기본값은 다르다.
| artifact | 장점 | 제약 | 플랫폼 정책 |
|---|---|---|---|
| Container | 기존 OCI CI·SBOM·signature·digest와 portability를 재사용 | ARM64 image build, 최대 image·cold start 조건 검증 | production portable 기본 |
| CodeZip | Docker 없이 빠른 iteration, 작은 package의 update가 단순 | package size·native dependency·S3 artifact와 AgentCore 종속 | 명시적 provider extension, 승인된 build profile만 허용 |
CodeZip을 허용하면 source tree를 그대로 보내지 않는다. 재현 가능한 build가 dependency lock, SBOM, source commit,
ZIP digest와 S3 object version을 만들고 AgentVersion.artifact에 고정한다. direct code 문서의
package limit과 runtime requirement는 대상 region에서 PoC 시작 시 다시 확인한다.
공통 객체 매핑
섹션 제목: “공통 객체 매핑”| 공통 객체 | AgentCore 표현 |
|---|---|
AgentVersion | ECR image digest 또는 CodeZip digest·S3 object version + immutable Runtime config |
KnowledgeBinding | Runtime artifact에 주입한 retrieval config 또는 승인된 Gateway capability |
DeploymentTarget | AWS account·region·VPC subnet·SG·execution role preset |
Deployment | Runtime version + endpoint |
providerRef | Runtime ARN, version, endpoint qualifier |
| runtime identity | execution role과 AgentCore workload identity |
ToolBinding | Gateway target, credential provider, Policy association |
adapter는 artifact upload 자체보다 승인된 digest와 provenance가 맞는지, native dependency가 ARM64인지, target VPC가 필요한 endpoint를 갖는지, execution role이 허용 범위를 넘지 않는지 검증한다. Runtime update가 새 version을 만들면 publication은 새 endpoint 검증 뒤 전환한다.
사내망처럼 사용하는 조건
섹션 제목: “사내망처럼 사용하는 조건”AgentCore Runtime과 built-in tool은 지정 VPC subnet에 ENI를 만들어 private resource에 접근할 수 있다. AgentCore data/control/Gateway API에는 PrivateLink interface endpoint를 둘 수 있다. VPC와 온프렘이 DX나 VPN으로 연결됐다면 private MCP·API·DB로 이어질 수 있다.
인터넷이 없는 VPC mode에서는 ECR·S3·CloudWatch Logs 등 필요한 VPC endpoint와 private DNS를 준비한다. 사내 CA, Route 53 Resolver, return route, security group까지 end-to-end로 검증한다.
Identity와 Agent별 ACL
섹션 제목: “Identity와 Agent별 ACL”Runtime은 IAM SigV4 또는 custom JWT inbound auth를 사용한다. JWT authorizer는 audience, client, scope와
groups contains Finance 같은 custom claim을 검사할 수 있다. provider 경계의 coarse policy로 유용하다.
그러나 사용자가 매 Agent마다 개인 email과 여러 부서를 바꾸는 entitlement를 전부 IAM/JWT config로 생성하면 policy가 폭증한다. portal ACL이 먼저 세밀한 결정을 내리고, AgentCore에는 portal workload 또는 큰 group boundary만 허용하는 구성을 기본으로 한다.
Gateway·Policy·Registry를 혼동하지 않는다
섹션 제목: “Gateway·Policy·Registry를 혼동하지 않는다”| 구성요소 | 맡는 일 | 대신하지 않는 것 |
|---|---|---|
| Identity | inbound token 검증, workload/outbound credential | 임직원 directory·Agent catalog ACL |
| Gateway | API·Lambda·MCP를 Agent tool로 노출 | Agent runtime 자체 |
| Policy | Gateway tool action을 Cedar로 허용·거부 | 누가 catalog의 Agent를 볼지 |
| Registry | Agent·MCP·skill metadata 검색과 승인 | 완성된 사내 marketplace UI |
Agent Registry는 AWS와 온프렘 resource를 함께 catalog할 수 있어 장기적으로 adapter와 잘 맞는다. 다만 현재 Preview이고 search authorization은 registry 단위가 중심이므로, product-neutral catalog의 단일 원본으로 바로 의존하지 않는다. 승인된 record를 mirror하는 provider catalog로 먼저 사용한다.
잘 맞는 경우와 불리한 경우
섹션 제목: “잘 맞는 경우와 불리한 경우”잘 맞는다: AWS가 승인된 data boundary이고, platform team이 runtime 격리·scale·session 기반을 직접 운영하지 않으려 하며, VPC·IAM·CloudWatch 운영 역량이 있다.
불리하다: 실행·prompt·memory가 물리적 온프렘을 벗어나면 안 되거나, AgentCore 미지원 region·quota가 문제거나, AWS API·ECR·ARM64 contract 종속성을 받아들이기 어렵다.
13장 요약
섹션 제목: “13장 요약”- AgentCore는 AWS 안의 managed runtime target이며 사내 catalog·ACL·session ownership을 대신하지 않는다.
- Runtime artifact는 Container와 CodeZip을 지원한다. OCI를 portable production 기본으로 두고 CodeZip은 명시적 extension으로 관리한다.
- session별 microVM 격리와 user-session binding은 다른 책임이다. 후자는 portal backend가 소유한다.
- VPC·PrivateLink는 private path를 만들지만 data가 온프렘에 남는다는 뜻은 아니다.
- Registry와 Policy는 각각 provider catalog 보조와 tool action 경계이며 회사 Publication·Grant를 대신하지 않는다.
참고 자료
섹션 제목: “참고 자료”- AgentCore Runtime 동작 — framework, version, protocol.
- Runtime build types — CodeZip·Container 선택과 ARM64 조건.
- Direct code deployment — ZIP packaging과 Container 비교.
- Runtime session 격리 — microVM과 client의 session 책임.
- VPC 연결 — ENI, subnet, endpoint 요구.
- JWT authorizer — scope와 custom claim.
- Agent Registry — catalog와 Preview 상태.