Customize answers per tenant in Amazon Bedrock Managed Knowledge Base Amazon Web Services added retrieval instructions to Amazon Bedrock Managed Knowledge Base, letting developers set per-tenant persona, answerFormat, retrievalGuidance and answerPolicy fields that agentic retrieval applies to each request. The managed, versioned resource replaces the prior workaround of disabling response generation, calling a model directly and maintaining prompts in every application, and a single request can apply a tenant's instruction across up to five knowledge bases. AWS cautions that retrieval instructions are not an authorization or data-isolation boundary, so tenants must use metadata filters or separate knowledge bases to control what each can retrieve. Artificial Intelligence https://aws.amazon.com/blogs/machine-learning/ Customize answers per tenant in Amazon Bedrock Managed Knowledge Base With retrieval instructions in Amazon Bedrock Managed Knowledge Base https://docs.aws.amazon.com/bedrock/latest/userguide/kb-build-managed.html , you can customize answers per tenant. The same product and policy documents often serve several audiences, such as customers in different regions or internal teams, and each audience needs its own answer. You set the voice, format, retrieval guidance, and answer policy that agentic retrieval https://docs.aws.amazon.com/bedrock/latest/userguide/kb-test-agentic-retrieve.html applies to each request. Before this feature, you couldn’t set the answer style, so agentic retrieval could use a different style from one request to the next. For a fixed voice or structured output, you had to turn off response generation, call a model yourself, and maintain the prompt in every application. Now you write that guidance once, as a managed, versioned Amazon Bedrock https://aws.amazon.com/bedrock/ resource, and each request references it. When you change an instruction, you can pin a version so that each application switches to the new version when you’re ready. Take AnyCompany Smart Home, a fictitious company that sells a home controller and room sensors in three sales regions. Its customer assistant serves all three regions, and its support, field sales, and legal teams use internal assistants that they built on the same documents. AnyCompany defines each region and internal team as a tenant here, and each needs a different answer. A customer in Sales Region Central needs Spanish with day/month/year dates, and a support agent needs a short ticket note. To keep the example compact, every tenant queries one knowledge base. However, agentic retrieval can search up to five knowledge bases https://docs.aws.amazon.com/bedrock/latest/userguide/kb-test-agentic-retrieve.html kb-agentic-retrieve-api in a single request, and the tenant’s instruction applies to all of them. Retrieval instructions change how the assistant answers, but they aren’t an authorization or data-isolation boundary. Use metadata filters or separate knowledge bases to control what each tenant can retrieve. In this post, we show how to give each tenant its own answers from shared knowledge bases while keeping each tenant’s data separate. By the end, you can roll out a change to one tenant’s instruction and confirm which version answered each request. Why tenants need their own instructions Tenants that share documents still differ in language, date and money conventions, voice, and which policy values they can quote. A retrieval instruction has four fields for these differences: - persona : who the assistant is, including identity, tone, and language. - answerFormat : how the answer is structured, including how it cites sources. - retrievalGuidance : how the agent interprets the question and what it prioritizes when it searches. - answerPolicy : whether and how to answer, including questions outside scope. The persona , answerFormat , and answerPolicy fields apply only when generateResponse is true , which is the default, and retrievalGuidance applies either way. For details, see Create and manage retrieval instructions https://docs.aws.amazon.com/bedrock/latest/userguide/kb-test-agentic-retrieve-instruction.html . Table 1 shows how the answer to the same return question changes when the request includes the Sales Region Central instruction and names the customer’s region. | Compared | No instruction | With the instruction and the customer’s region | | Answer | Every region’s return window, then a question about where the unit was bought | 45 days from delivery, in Spanish | | Last line | None | Source: central-returns-addendum.md | Table 1: The same return question with and without the Sales Region Central instruction These patterns come up across industries. An enterprise software provider can run one assistant for many of its own customers. Each customer uploads its policies, standard operating procedures, and company values, and persona and answerPolicy give each one its own voice and rules. A regulated enterprise can put a fixed disclaimer in answerPolicy and a set citation form in answerFormat , so every answer includes both. A team that sends answers to downstream code can get strict JSON from an answerFormat , without a separate generation step. In each case, the documents are shared, and the voice, format, and policy change from caller to caller. How retrieval instructions work An instruction belongs to your AWS account and AWS Region, not to a knowledge base, and goes through these stages: 1. Create – CreateRetrievalInstruction returns HTTP 202. 2. Review – Amazon Bedrock reviews the instruction’s fields asynchronously, and you poll for the result. If the review fails, lastTransitionStatusReasons says why. 3. Activate – A passing review makes the instruction ACTIVE , and DRAFT points to its current content. 4. Version – CreateRetrievalInstructionVersion saves an immutable numbered version. 5. Apply – A request names the instruction and, optionally, a version, which defaults to DRAFT . 6. Report – The first Planning trace event includes appliedInstruction . Scope and trade-offs Instructions set voice, format, conventions, and policy wording. They don’t limit which documents the agent can retrieve, and they don’t choose the tenant’s own values, which come from naming the tenant in the request. Use metadata filters https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-test-config.html or separate knowledge bases to limit what each tenant can retrieve. Solution overview Each tenant gets its own instruction and metadata filter. The instruction sets the voice, format, and policy of the answer, and the filter limits which documents the agent retrieves. Your backend chooses both from the authenticated tenant, so one shared knowledge base can serve every tenant. In Figure 1, your backend maps the authenticated tenant to an instruction version and a metadata filter, and adds a short tenant line to the message. Then it calls AgenticRetrieveStream on one shared managed knowledge base. The same pattern works with a separate knowledge base for each tenant. A request can query a shared global knowledge base and the tenant’s own knowledge base together, each with its own filter. The example uses 32 short, fictitious AnyCompany Smart Home policy and product documents for the AnySmartProduct-5 home controller and AnySmartProduct-6 room sensors. They’re stored in an Amazon Simple Storage Service Amazon S3 https://aws.amazon.com/s3/ bucket, and each has region , audience team , and sensitivity metadata. Each of the six tenants, three regions and three teams, has its own instruction pinned to version 1. Two restricted engineering notes belong to no tenant, so no tenant’s filter should return them. The code is in the GitHub repo https://github.com/aws-samples/sample-managed-knowledge-base-patterns/tree/main/retrieval-instructions , in Python and TypeScript, and runs in the US East N. Virginia Region us-east-1 by default. To use another AWS Region, set AWS REGION . For the latest Region support, see Supported AWS Regions https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-regions.html . Prerequisites You need the following: - An AWS account with permissions to create retrieval instructions, AWS Identity and Access Management IAM roles, and an S3 bucket. - One or more managed knowledge bases, with a metadata file for each document you want to filter on. - Python 3.10 or later and a current version of the AWS SDK for Python Boto3 . Older Boto3 versions don’t include the retrieval instruction operations. - A current version of the AWS Command Line Interface AWS CLI for control-plane commands. AgenticRetrieveStream has no CLI command, so call it through an SDK. - Optional: an AWS Key Management Service AWS KMS https://aws.amazon.com/kms/ customer managed key, if you want to encrypt instructions with your own key. Examples use Python with these two clients. Later snippets leave out the client setup and import lines. Create a retrieval instruction for each tenant The Sales Region Central instruction sets the language, date and money formats, and policy wording: To create and pin each tenant’s instruction: 1. Select a tenant key, such as sales-region-central , for the name and the tenant tag. 2. Enter the instruction fields for that tenant. 3. Send CreateRetrievalInstruction with the content and tags. 4. Poll GetRetrievalInstruction until lastTransitionStatus is neither CREATING nor UPDATING . 5. If the status isn’t ACTIVE , read lastTransitionStatusReasons , revise, and update. 6. Create a version and record it in your release configuration. This code runs steps 3 and 6. The repo version adds the polling for steps 4 and 5. An update replaces the whole instruction, including the description, so resend every field you want to keep. To encrypt an instruction with your own key, set customerEncryptionKeyArn when you create it. You can’t add or change the key later. Your key policy also needs the statement in Encryption of retrieval instructions https://docs.aws.amazon.com/bedrock/latest/userguide/encryption-kb.html encryption-kb-retrieval-instruction . Keep tenant data apart with metadata filters An instruction doesn’t limit which documents the agent retrieves. On a shared knowledge base, a Sales Region North customer’s question can return the Sales Region Central and South addenda, and even notes that no tenant should see. To keep each tenant to its own documents, add a metadata filter built from the authenticated tenant, or give the tenant its own knowledge base. A request can still query the tenant’s knowledge base alongside shared ones. Figure 2 compares the three approaches. A metadata filter keeps one knowledge base to sync and maintain, but every document needs accurate metadata, and your backend must build the filter correctly on every request. A separate knowledge base per tenant isolates tenant data by design, but each tenant adds a k