A collection of samples, best practices, and reference architectures to accelerate the building of Agentic AI applications on AWS.
Each sample demonstrates one pattern and is built as a building block: a
sample can consume other samples through their published interface (an
exported CDK construct and published SSM parameters), and later samples can
consume it. How the samples fit together (tenant identity, tenant isolation,
the control plane) is in the Architecture Overview.
Alongside the code,
every sample ships its design trail: an architecture.md describing the
implemented state, an ADR file recording the decisions and their reasoning,
and a design/ folder holding the working specification the sample was built
from — read those to understand why the sample looks the way it does, not
just what it does.
What every sample ships, and the bar it meets before it is merged, is described in the Sample Standard.
| Sample | Description |
|---|---|
| The Simple Cell-Based Control Plane | A minimal multi-tenant control plane for cell-based deployments — one service, one API, one DynamoDB table, one Step Functions workflow, script-driven provisioning via AWS CodeBuild. maxTenants: 1 degenerates the model to a silo. |
| Tenant Identity with Amazon Cognito | An identity layer that makes Amazon Cognito the trusted source of tenant identity, in three user-pool topologies chosen at deploy time — plus a tiered mode that runs two of them side by side — with RFC 8693 token narrowing to one tenant. |
| Runtime Isolation | A pooled agent backend on Amazon Bedrock AgentCore Runtime that trusts one ingress, which verifies the tenant token, maps each caller to their own microVM, signs every model call with tenant-scoped credentials, limits each tenant and attributes cost per tenant. |
A minimal multi-tenant control plane for cell-based deployments. A cell
is a deployment unit: one shared application deployment plus up to
maxTenants tenants, each with its own per-tenant deployment inside the
cell. Set maxTenants: 1 and the model degenerates to a silo — one tenant
per cell.
Tenant onboarding is a single POST /tenants call: placement claims a slot
in an existing cell or creates a new cell implicitly, then a Step Functions
workflow runs your provisioning scripts in AWS CodeBuild — the cell create
script first when a new cell is needed, then the tenant create script.
Provisioning is defined once, at deployment time, by a CellDefinition; cells
are homogeneous by construction and callers can never supply code. Every API
operation requires a JWT from your vendor IdP, validated by a Lambda
Authorizer.
The Simple Cell-Based Control Plane
Every multi-tenant application has to answer one question on every request: which tenant is this caller acting for? Amazon Cognito proves who a user is, but it has no notion of a tenant. The alternative — keeping a user-to-tenant mapping in an application table and consulting it on every request — puts a second source of truth on the request path that can drift from the directory.
This sample overlays tenant identity onto Cognito so the tenant rides in every
access token as a claim Cognito signs, and a service reads it from a verifiable
claim instead of a lookup. It builds the three overlays Cognito allows — one
pool per tenant, an immutable user attribute, or a group — side by side behind
one platform API and one token contract, chosen once at deploy time, and adds a
fourth tiered deployment mode that runs the pool-per-tenant and shared-pool
overlays together in one stack, with each tenant placed in a standard or
premium tier at onboarding. The vendor
manages tenants and users with IAM through /platform/*; a tenant admin manages
its own tenant's users through /tenant/*. Because a token can name every
tenant a user belongs to, a client trades a refresh token at an RFC 8693
exchange endpoint for an access token narrowed to one tenant, which Cognito
re-signs so it verifies the same way.
The sample stops at the token: verifying it and scoping a request belongs to the consuming service, which is an extension seam rather than built here. See Tenant Identity with Amazon Cognito.
A pooled agent backend serves every tenant from shared compute, so two questions follow on every request: which compute unit may this caller reach, and whose permissions does the agent use? If the client picks the session, or the agent holds one role for all tenants, a stolen token or a prompt-injected agent can reach another tenant's conversation or data.
This sample puts one ingress in front of an Amazon Bedrock AgentCore Runtime
and makes it the only principal the Runtime trusts. The ingress, an API
Gateway REST API or an AgentCore Gateway chosen at deploy time, verifies the
tenant-identity access token, derives the microVM session from the verified
tenant_id and sub, and vends TenantId-tagged credentials with a token
vending machine that is always on. The agent's own role holds no model or data
permission, so IAM, not agent code, keeps each tenant to its own model calls
and data. The ingress also limits each tenant's requests per minute and logs
per-tenant cost figures; model cost splits by tenant in the bill through the
IAM principal. Session mapping, scope checks and token forwarding are optional
modules.
It ships as one CDK construct, IsolatedRuntime, that later samples can
consume. See Runtime Isolation.
New samples follow the Sample Standard: the directory layout, the design trail (specification, ADRs, threat model, architecture), the diagram conventions, the code and test requirements, the security review, and the README structure. Section 9 of the standard is the definition of done a pull request is reviewed against. General contribution guidelines are in CONTRIBUTING.md.
Blogs and articles on multi-tenant agentic, written by AWS authors.
- Building multi-tenant agents with Amazon Bedrock AgentCore — part 1 of a series: ten design considerations for multi-tenant agents, and the silo, pool, and bridge deployment models with Amazon Bedrock AgentCore.
- Shared infrastructure, isolated tenants: Pool model multi-tenancy with Amazon Bedrock AgentCore — part 2: a working pool-model implementation with tenant-scoped credentials (token vending machine + ABAC), service tiers, Cedar policies, and per-tenant cost attribution.
- Apply fine-grained access control with Bedrock AgentCore Gateway interceptors — per-principal access control for MCP tools at the gateway layer.
- Implementing tenant isolation using Agents for Amazon Bedrock in a multi-tenant environment — tenant isolation patterns for Bedrock Agents using dynamically scoped credentials.
- Multi-tenant RAG with Amazon Bedrock Knowledge Bases — silo, pool, and bridge patterns for the retrieval layer of agentic applications.
- Multi-tenancy in RAG applications in a single Amazon Bedrock knowledge base with metadata filtering — metadata-based tenant isolation within a shared knowledge base.
- Building multi-tenant agents on AWS
- Secure shared multi-tenant agent memory namespaces using AgentCore Memory
- Secrets of Agentic Scale (SAS): The patterns towards 10,000 tenants — a six-part series on the distributed-systems problems that surface between 100 and 10,000 tenants on an agent platform:
- Agentic AI delegation patterns
Deploying a sample creates billable AWS resources in your account. Each sample's README documents how to exercise it and how to tear it down — delete the sample's stacks when you are done.
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.