Managed Kb API

Public only. Uses the public aws bedrock-agent commands. Always pass --region <REGION> and --profile <PROFILE>. ARNs are references, not secrets; never print secret values. Read public docs per safety-and-iam (opens in a new tab) (curl + the .md endpoint, never web_fetch).

Ingestion and retrieval are user-run steps, and this file gives no interface for either. The agent provisions only. Afterwards the user starts ingestion and runs the retrieval comparison against the new (owned) data sources, never the original. §3 and §5 describe those surfaces well enough to explain them, plan around them and report what changes for callers — for request shapes the user goes to the AWS API reference. The shapes in this file are the ones the agent itself issues: creates and read-only probes.

Never invent a request shape, supported model, or dimension count. Confirm parameter names against the public docs and/or aws bedrock-agent <command> --generate-cli-skeleton, preferring the user’s Region. If it isn’t confirmed, say so and re-verify against the docs. The one exception is connectorParameters — free-form in the API model, so the skeleton renders it as {} and proves nothing. For the connector body this file and the per-connector doc page (§2b/§2c) are the authority; never infer a connector field from the self-managed shape, which differs deliberately.

Contents

• 1. CreateKnowledgeBase (MANAGED)
• 2. CreateDataSource (MANAGED_KNOWLEDGE_BASE_CONNECTOR)
• 2b. Auth-based connectors — exact managed shapes
• 2c. Doc sources
• 2d. CUSTOM connector (direct ingestion)
• 3. Retrieval surfaces (runtime, user-run)
• 3b. ACL-aware retrieval — capability and its boundary
• 4. Read / status commands (read-only probes)
• 5. StartIngestionJob — a user-run handoff step
• 6. API error → cause → fix
• 7. Client tokens (idempotency)
• 9. Rate limits & batching

1. CreateKnowledgeBase (MANAGED)

Embedding model — two modes, set by embeddingModelType (verify support in the docs; don’t guess):

• MANAGED (default): service-managed model — omit embeddingModelArn/embeddingModelConfiguration; keeps the built-in managed reranker.
• CUSTOM: your own Bedrock model ARN at the managed dimension and data type for text models (read them from Create a managed knowledge base (opens in a new tab); any other value is rejected — see table), available in the KB’s Region; a multimodal model has its own rules (mapping (opens in a new tab) → Key findings). Disables the managed reranker. Text and multimodal models are both eligible.

Don’t hardcode the supported CUSTOM model set — it can change; fetch it at create time. An unlisted model → "The specified embedding model ... is not supported" (pick one the docs list). embeddingModelType can’t change after creation.

Response: knowledgeBase.knowledgeBaseId, knowledgeBase.status (CREATING → ACTIVE). Poll get-knowledge-base (§4) for ACTIVE before creating data sources.

Canonical API reference — check it for the current field list and limits before every call. The API reference governs the request/response shape (field names, required/optional, types); the user guide governs behavior and defaults. Read the API reference for CreateKnowledgeBase and confirm the current fields against it (or --generate-cli-skeleton) before building the call — fields and limits change: CreateKnowledgeBase API reference (opens in a new tab).

Encryption at rest — carry the source CMK forward

A managed KB is always encrypted. kmsKeyArn only decides which key: omit it and Bedrock uses an AWS-owned key (invisible to the customer — no ARN, no key policy, no CloudTrail on its use, no rotation control); supply it and the KB uses the customer’s customer-managed key (CMK), which they can audit, rotate, and revoke. Because migration is create-new-then-cut-over, a fresh serverSideEncryptionConfiguration is chosen at create time — so a source KB that used a CMK silently drops to the AWS-owned key unless the key is carried forward.

Discovery already records the source encryption value (aws-owned | cmk-arn). Use it:

1. If the source used a CMK, ask the customer explicitly which they want on the new KB: reuse the same key ARN (default recommendation — preserves posture), use a different CMK, or accept the AWS-owned default. If the source had no CMK, state plainly that the new KB will use the AWS-owned key, and offer the CMK path if they want to raise posture during the migration. Never decide silently.

2. The same CMK can serve the source and the new KB at the same time. A KMS key is account-level and referenced by ARN; passing the source’s key to the new KB is normal — both run on it during the parallel-validation window.

3. Bedrock creates a grant on the key — it never edits the key policy. On CreateKnowledgeBase with a kmsKeyArn, Bedrock verifies it can use the key and creates KMS grants automatically. Grants can remain after the KB is deleted (observed: all of them stayed); after deleting a CMK-encrypted KB, check with aws kms list-grants --key-id <KEY_ARN> and retire the stale ones. A grant is a separate authorization object; Bedrock does not modify the key policy to do this, and neither should the agent describe it that way. The managed KB’s own service role needs no permission on this KB-storage key.

4. The customer owns the key policy — recommend, never modify. The one prerequisite lives in the key policy, which the customer owns and updates: it must permit the identity that runs CreateKnowledgeBase to kms:CreateGrant (plus GenerateDataKey/Decrypt), scoped with kms:ViaService: bedrock.<region>.amazonaws.com. Once the key policy permits the creating identity, Bedrock’s automatic grant covers the KB’s ongoing use of the key. Recommend the policy below for the customer to apply to their own key — never edit their key policy for them, and never imply Bedrock edits it.

   jsonCopy

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": { "AWS": "arn:aws:iam::<account-id>:role/<creating-identity>" },
         "Action": ["kms:CreateGrant"],
         "Resource": "*",
         "Condition": {
           "StringEquals": { "kms:ViaService": "bedrock.<region>.amazonaws.com" },
           "ForAllValues:StringEquals": {
   
   
   
   
   
   
   
   
   
   
   
   
   

5. If create fails with a KMS error (AccessDenied/KMSKeyNotFound), the cause is the creating identity lacking kms:CreateGrant on the key — name it rather than burning the retry ladder guessing.

Authoritative reference for the create-time grant behavior and the exact key policy: Encryption of knowledge base resources (opens in a new tab).

2. CreateDataSource (MANAGED_KNOWLEDGE_BASE_CONNECTOR)

deletionProtectionConfiguration is a sibling of connectorParameters and is shown in the request above as the secure default: ENABLED, with the threshold left at the service default unless the customer sets one. It is optional at the API level, but emit it explicitly rather than relying on omission; set "deletionProtectionStatus": "DISABLED" only on an explicit customer opt-out. The CUSTOM connector (direct ingestion) does not support deletion protection — omit this block for a CUSTOM data source (§2d).

syncSchedule is also an optional sibling of connectorParameters (shown above for illustration). It sets a recurring schedule on which Amazon Bedrock automatically syncs the data source for all native data source connectors. The AWS docs (kb-managed-connect-ds.html (opens in a new tab)) state you specify exactly one of: daily (an empty object — “Syncs once per day at a system-chosen off-peak time”); weekly (requires dayOfWeek, a value SUNDAY–SATURDAY); or monthly (requires dayOfMonth, holding either a dayNumber (allowed range: DayOfMonth (opens in a new tab)) or an empty lastDayOfMonth object). “Omit syncSchedule to sync on demand only.” The schedule is carried over from the source, not asked: no timer on the source means omit it (on demand, as today); a timer the schedule can express is carried; any other timer stays the customer’s own (see plan (opens in a new tab) → “Sync schedule”). In CloudFormation it is SyncSchedule on ManagedKnowledgeBaseConnectorConfiguration of AWS::Bedrock::DataSource, with exactly one of Daily (JSON {}), Weekly (DayOfWeek) or Monthly (DayOfMonth with DayNumber or LastDayOfMonth); every one is “Update requires: No interruption” (SyncSchedule (opens in a new tab)). Unlike ConnectorParameters, these are PascalCase typed properties. For Terraform, check the provider’s schema for the attribute (see iac-schema (opens in a new tab)); never write one the schema does not have.

--vector-ingestion-configuration is intentionally omitted above. Omitting it is required when the KB uses the managed embedding model: any chunkingConfiguration (even FIXED_SIZE/NONE) is rejected with ValidationException: "A chunking strategy cannot be specified with a managed embedding model", and the managed fixed-size default applies (size and overlap on the Customize ingestion page). Only when the KB uses a CUSTOM embedding model may you pass --vector-ingestion-configuration to set FIXED_SIZE or NONE explicitly; SEMANTIC/HIERARCHICAL are rejected either way, so omit for those.

S3 filters preserved; no dedicated bucket by default. A source S3 data source’s key-prefix scoping and size limits carry over through the managed filterConfiguration block (below); the managed KB reads the existing bucket — a migration does not require a dedicated bucket by default.

Response: dataSource.dataSourceId, dataSource.status (CREATING → AVAILABLE).

Canonical API reference — check it for the current field list and limits before every call. The API reference governs the request/response shape; the user guide (and the per-connector pages in §2c) govern behavior and defaults. Read the API reference for CreateDataSource and confirm the current fields against it (or --generate-cli-skeleton, remembering the connectorParameters body is free-form and unmodelled — §2b) before building the call: CreateDataSource API reference (opens in a new tab).

2b. Auth-based connectors (SharePoint, Confluence, OneDrive) — exact managed shapes

The managed connector shape differs from the self-managed connector — the managed secret field is connectionConfiguration.secretArn (not credentialsSecretArn), the auth-type values are different, and fields are grouped into connectionConfiguration / dataEntityConfiguration / filterConfiguration sub-objects. Auth-based connectors are the top cause of FAILED data sources, almost always a secret or certificate problem. Re-verify these shapes against the per-connector doc pages (§2c) before building a call.

Connector authentication — what carries over and who does what.

• No documented mapping exists from a self-managed auth type to a managed one, and the managed secret’s key set differs (each connector’s section below). Choose the managed authType from that connector’s page, with the customer; treat the source secret as reference only. Confluence BASIC was carried over in live testing with a new secret holding the managed key set; the SharePoint and OneDrive application paths are not verified here — say so.
• User-managed setup (3LO), authType: MANAGED_OAUTH2 on SharePoint, OneDrive and Confluence, is a console sign-in: the customer signs in to the source from the Bedrock console, Bedrock creates the token secret, and the KB role refreshes it. It is the customer’s step, never the agent’s (kb-managed-3lo-setup (opens in a new tab) lists the console user’s permissions).
• AWS publishes a sample that sets up Microsoft, Google and Atlassian connectors end to end (aws-samples/sample-managed-kb-connector-setup (opens in a new tab)). Point the customer to it as a sample, not as part of this migration: ask before suggesting any change on the Microsoft, Google or Atlassian side, refer to secrets by ARN only, prefer the least privilege the source supports (for SharePoint, Sites.Selected), and do not copy its code into the migration.

Common wrapper: deletionProtectionConfiguration (deletionProtectionStatus) and mediaExtractionConfiguration are siblings of connectorParameters; aclEnabled is a flat boolean inside connectorParameters.

SharePoint (connectorParameters.type = SHAREPOINT)

dataEntityConfiguration: siteUrls (JSON array; each path begins /sites/, /teams/, or /personal/), crawlFiles (default true), crawlPages (default true). filterConfiguration (optional): modifiedDateBefore, modifiedDateAfter, inclusionItemPaths. Secret keys — ENTRA_ID_APP_ONLY: clientId + certificatePassword (or privateKey for PEM); OAUTH2_APP: clientId + clientSecret + userName + password. aclEnabled (shown as true above) is a required, explicit customer choice per data source — never a silent default. Disclose what each value means (ACL-aware filtering on vs off; see §3b) and that it is immutable after create, then set the value the customer chose — true to enforce ACL filtering (as in the example) or false when the customer accepts no document-level filtering. The choice by itself is not a blocker — either value is a valid migration. It becomes a blocker only when the selected mode lacks its required auth/ACL configuration (e.g. ACLs on for SharePoint forces ENTRA_ID_APP_ONLY and a certificateS3Path); in that case say what is missing rather than silently flipping the flag. The siteUrls value https://contoso.sharepoint.com/sites/engineering is an example only (contoso.sharepoint.com is a placeholder domain) — replace it with the customer’s real site URL(s).

Confluence (connectorParameters.type = CONFLUENCE)

dataEntityConfiguration: crawlPage, crawlBlog, crawlPageAttachment, crawlBlogAttachment, crawlArchivedSpace, crawlArchivedPage, crawlPersonalSpace. The connector page lists the block as optional, but live creates without it were rejected with Value at 'dataEntityConfiguration' failed to satisfy constraint: Member must not be null. Always send it, with the entity types the source crawled (the page’s own example sets the four crawl* flags shown above). Also send hostUrl with no trailing slash; a carried-over trailing slash was rejected on the same call. filterConfiguration (optional): inclusionSpaceKeys, inclusionSpaceUrls, inclusionMimeTypes, exclusionMimeTypes, maxFileSizeInMegaBytes (numeric string; default on the connector page). aclEnabled has a documented default that depends on authType (BASIC→true, OAUTH2→false) and is permanent after create. Do not rely on that default silently: make it an explicit customer choice, disclose the meaning (§3b) and the immutability, then set it. The choice alone is not a blocker; it blocks only when the selected mode lacks its required auth/ACL configuration. Secret keys — BASIC: username (email) + password (Atlassian API token) + hostUrl (+ adminApiKey, organizationId, directoryId when aclEnabled); OAUTH2: per the Confluence OAuth2 setup page.

OneDrive (connectorParameters.type = ONEDRIVE)

dataEntityConfiguration: crawlPersonalDrives, crawlSharedWithMe (OAUTH2 only). crawlPersonalDrives is optional — do not set it to true by default. Enabling it (as the example shows for completeness) pulls in individual users’ personal OneDrive content, which frequently contains PII; set it deliberately with the customer, not automatically. Note that with Microsoft Entra ID App authentication only personal drives can be crawled — so on that auth type this is the crawl scope, and the PII consideration applies directly. filterConfiguration (optional): inclusionUserEmailAddresses, exclusionUserEmailAddresses, userFilterPath, inclusionDriveItems, exclusionDriveItems, includeMimeTypes, excludeMimeTypes, absoluteDateBefore, absoluteDateAfter. aclEnabled (shown as true above, which is why the example includes the required certificateS3Path) is a required, explicit customer choice — never a silent default; disclose its meaning (§3b) and that it is immutable after create, then set the chosen value (true to enforce ACL filtering, or false to accept none — with false the certificateS3Path is not required). The choice alone is not a blocker; it blocks only if the selected mode lacks its required auth/ACL configuration (ACLs on requires the Entra app-id auth type and the certificate). Secret keys — ENTRA_APP_ID: clientId + clientSecret (+ certificatePassword when aclEnabled); OAUTH2: per the OneDrive OAuth2 setup page.

S3 and Web Crawler (no secret)

• S3 — connectionConfiguration: { bucketName, bucketOwnerAccountId }; optional filterConfiguration: { inclusionPrefixes, exclusionPrefixes, inclusionPatterns, exclusionPatterns, maxFileSizeInMegaBytes } (key-prefix scoping + regex patterns). See §2. Optional top-level connectorParameters fields: metadataFilesPrefix (where .metadata.json sidecar files live), aclEnabled (an explicit choice, immutable after create — disclose its meaning per §3b and set the customer’s decision, don’t default it silently), and aclConfiguration: { globalAccessControlListS3Uri } — required when aclEnabled is true, ignored when false. Note the bucket is named by bucketName, not an ARN: a source bucketArn must be reduced to the bare name. There is no universal default — pick the value with the customer.

  ACL-enabled S3 (the aclConfiguration is mandatory here):

  jsonCopy

  { "type": "MANAGED_KNOWLEDGE_BASE_CONNECTOR", "managedKnowledgeBaseConnectorConfiguration": {
    "connectorParameters": {
      "type": "S3", "version": "1", "aclEnabled": true,
      "connectionConfiguration": { "bucketName": "<BUCKET>", "bucketOwnerAccountId": "<account-id>" },
      "aclConfiguration": { "globalAccessControlListS3Uri": "s3://<BUCKET>/<acl-config>.json" },
      "filterConfiguration": { "inclusionPrefixes": ["published/en/"] } } } }

  When the customer chooses no document-level filtering, set "aclEnabled": false and omit aclConfiguration entirely (it is ignored when false) — the rest of the shape is unchanged.

• WEB — full shape below. GOOGLEDRIVE is secret-based like the others. (The managed connector names are WEB/GOOGLEDRIVE — WEB_CRAWLER/GOOGLE_DRIVE are rejected; see the enum conflict note.)

--generate-cli-skeleton does NOT reveal connector fields. It returns "connectorParameters": {}. The field is free-form in the API model, the CloudFormation schema and the Terraform provider, so no skeleton, describe-type, cfn-lint or terraform validate will ever list or check its contents. The skeleton remains useful for the wrappers (deletionProtectionConfiguration, mediaExtractionConfiguration). For the connector body, this file plus the per-connector doc page (§2c) are the only authority. Re-verify against the docs.

WEB (connectorParameters.type = WEB)

Source: kb-managed-ds-webcrawler.md. The self-managed web crawler’s crawlerConfiguration splits into two managed objects: crawlConfiguration (behaviour) and filterConfiguration (URL patterns).

Add crawlDepth, maxLinksPerUrl and maxCrawledUrlsPerMinute to crawlConfiguration only when the source sets them, carrying the source’s values; omitted, the service defaults apply.

There is no crawlScope, rateLimit, crawlerConfiguration or crawlerLimits on the managed connector — those are the self-managed names and are silently accepted into the free-form blob, then ignored or rejected by the service. The managed connector also has no page cap: a self-managed crawlerLimits.maxPages has nowhere to go, so the new crawl can reach more pages than the source did. Flag a dropped maxPages in the plan and offer the managed controls that narrow a crawl (inclusionPatterns / exclusionPatterns, syncScope, crawlDepth).

authType is required and never inferred. Do not default a web data source to NO_AUTH. Resolve it with the customer: NO_AUTH only once they confirm the site is public; otherwise BASIC_AUTH / FORM / SAML with a Secrets Manager secretArn (by ARN only). A generic example uses <AUTH_TYPE>, not a concrete value. The web crawler has no ACL support — there is no aclEnabled on this connector (web content has no permission model; see §3b), so never add one to a WEB data source.

Connector-name enum conflict (resolved). kb-managed-connect-ds.md lists the supported types as S3, ONEDRIVE, CONFLUENCE, SHAREPOINT, WEB_CRAWLER, GOOGLE_DRIVE, but the per-connector page (kb-managed-ds-webcrawler.md) says “specify WEB as the connector type”, and live testing gets Invalid connector type for WEB_CRAWLER/GOOGLE_DRIVE. The per-connector page and live testing win: use WEB and GOOGLEDRIVE. The overview page’s enum is stale — expect to see it while reading the docs, and do not “correct” a working WEB to WEB_CRAWLER on the strength of it.

Secrets Manager secret rules (auth connectors)

• The secret must exist before create-data-source, in the KB’s Region. Pass only its ARN in connectionConfiguration.secretArn (never the value). The managed-connector docs do not require an AmazonBedrock- name prefix; only require it if the KB role’s policy scopes secret access to AmazonBedrock-*.
• Key/value contents depend on connector + authType (tables above; full detail on the connector’s “Set up … authentication” doc page). Do not guess key names.
• The KB execution role needs secretsmanager:GetSecretValue on the ARN (+ kms:Decrypt for a CMK), and for the certificate methods s3:GetObject/s3:ListBucket on the .p12 object in certificateS3Path (+ kms:Decrypt if SSE-KMS).

Precondition gate — do not submit before auth is confirmed; do not loop on FAILED

Before calling create-data-source (or syncing) for an auth connector, confirm ALL of these:

1. A secret exists at the ARN, in the KB’s Region, with keys matching the managed connector + authType.
2. For SharePoint ENTRA_ID_APP_ONLY (and OneDrive ENTRA_APP_ID with ACLs), the .p12 certificate is in S3 at certificateS3Path and the role can read it.
3. The KB role can read the secret (secretsmanager:GetSecretValue, + kms:Decrypt for a CMK).
4. siteUrls (array) / hostUrl / tenantId / aclEnabled are present and correctly shaped.

If any precondition is unmet or unknown, stop and ask the user (or hand off the secret-creation as a user step) — do NOT submit the call to the live service to “see if it works.” On a FAILED data source, run one diagnosis pass against this checklist and the error, report the specific missing item, and stop. Never resubmit the same call or try random variations — auth failures are config/permission problems that re-running cannot fix.

§2c — Doc sources

Re-verify these pages before building an auth-connector call; read them per safety-and-iam (opens in a new tab).

• Connect a data source (wrapper fields, S3 example; its type enum is stale — see the conflict note in §2b): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-connect-ds.html (opens in a new tab)
• Amazon S3 connector (filter + ACL + metadata fields): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-ds-s3.html (opens in a new tab)
• Web Crawler connector (WEB — connection/crawl/filter fields): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-ds-webcrawler.html (opens in a new tab)
• SharePoint connector + connect (JSON): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-ds-sharepoint-connect.html (opens in a new tab)
• SharePoint Entra setup (secret keys, certificate): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-sharepoint-entra-setup.html (opens in a new tab)
• SharePoint OAuth2 setup (secret keys): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-sharepoint-oauth2-setup.html (opens in a new tab)
• Confluence connect (JSON) + Basic setup: https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-ds-confluence-connect.html (opens in a new tab)
• OneDrive connect (JSON) + Entra setup: https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-ds-onedrive-connect.html (opens in a new tab)

Most common FAILED-status causes for these connectors

In rough frequency order: a self-managed field (credentialsSecretArn, accessControlConfiguration.crawlAcl, hostType, domain) or connector name (WEB_CRAWLER/GOOGLE_DRIVE) used instead of the managed shape above; a missing/wrong connectionConfiguration.secretArn, or secret keys that don’t match the managed authType; SharePoint ENTRA_ID_APP_ONLY created without certificateS3Path; a KB role lacking secretsmanager:GetSecretValue/kms:Decrypt or S3 read on the certificate; SharePoint siteUrls passed as a string rather than a JSON array; and a wrong authType for the connector (e.g. the self-managed OAUTH2_CLIENT_CREDENTIALS instead of managed ENTRA_ID_APP_ONLY/OAUTH2_APP), or a Confluence hostUrl not ending .atlassian.net. Each maps to a fix in §6.

2d. CUSTOM connector (direct ingestion) — no crawl; documents are pushed in

A MANAGED KB does support a custom data source. Not via the self-managed top-level dataSourceConfiguration.type: CUSTOM (that is rejected on managed — §6), but as a connector: type: MANAGED_KNOWLEDGE_BASE_CONNECTOR with connectorParameters.type: CUSTOM. This is the managed replacement for a self-managed CUSTOM source: documents are pushed directly into the data source instead of being staged to S3 for a crawl. There is no secret and no connectionConfiguration — it is a push target, not a crawl. A self-managed Lambda customTransformationConfiguration has no managed equivalent — do not present this connector as a substitute for it; direct the customer to AWS Support (see mapping (opens in a new tab)).

Create (the data source reaches AVAILABLE directly). Set aclEnabled explicitly — it is a required customer choice for CUSTOM too, not a silent default:

The service normalizes connectorParameters to its defaults (a filterConfiguration with the default maxFileSizeInMegaBytes, aclEnabled: false, version: "1") — and defaults mediaExtractionConfiguration.imageExtractionConfiguration.imageExtractionStatus to ENABLED. mediaExtractionConfiguration remains an optional sibling of connectorParameters.

CUSTOM supports ACLs, set through aclEnabled — make it an explicit customer choice. Per the Custom data source ACL docs (opens in a new tab), aclEnabled: true turns on document-level access-control filtering for a CUSTOM source; the example above sets it explicitly rather than relying on the false default. Disclose the meaning (§3b) and set the value the customer chose (true to enforce ACL filtering, false to accept none). Do not call the CUSTOM aclEnabled immutable — that page states it can be set on create or update. This provisioning workflow still sets it explicitly at create and makes no update call, so it is fixed at create by this workflow, but it is not immutable at the API level for CUSTOM. When aclEnabled is true, each IngestKnowledgeBaseDocuments push (a user-run step) must supply the document’s ACL metadata (allowed / denied principals) — a document pushed without it is not access-controlled. Deletion protection still does not apply to the CUSTOM connector — it is a direct-push target, not a crawl, so do not add a deletionProtectionConfiguration block to a CUSTOM data source (the secure ENABLED default in §2 is for the connectors that support it).

Filling it is a user-run step, and this file gives no interface for it. A CUSTOM source is never synced: the user pushes documents straight in, and they become part of both the data source and the KB with no sync step at all. The agent creates the data source and stops there. What the agent should tell the user about the model, without handing them a call:

• Push, don’t sync. Never run a sync against a CUSTOM data source — pushing and syncing the same source is a conflict, not a belt-and-braces approach.
• Documents can be sent inline or referenced in S3, including multimodal content, and each carries a caller-chosen identifier. Re-pushing the same identifier overwrites that document, which is how updates work here.
• Metadata travels with the document and is what retrieval filters act on later (§3).
• Pushes are batched and rate-limited, so a bulk load is a script with pacing, not a loop of one-off commands (mapping (opens in a new tab) carries the current batch size and rate).
• Listing, fetching and deleting pushed documents is available directly — no console round-trip needed when the user wants to check or clean up what they sent.

Retrieval is unchanged (§3). The create-data-source shape above reaches AVAILABLE; the document-push behavior described here comes from the public direct-ingestion docs, which is where the user should get the request shapes.

Doc sources:

• Connect a custom data source: https://docs.aws.amazon.com/bedrock/latest/userguide/custom-data-source-connector.html (opens in a new tab)
• Custom data source access control (aclEnabled, ACL metadata on ingest, set on create or update): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-ds-custom-acl.html (opens in a new tab)
• Ingest changes directly (custom needs no sync; S3 does): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-direct-ingestion.html (opens in a new tab)
• Ingest documents directly (request bodies / examples): https://docs.aws.amazon.com/bedrock/latest/userguide/kb-direct-ingestion-add.html (opens in a new tab)
• IngestKnowledgeBaseDocuments API: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_IngestKnowledgeBaseDocuments.html (opens in a new tab)

3. Retrieval surfaces (runtime) — user-run; what they are and when each fits

The agent never queries a knowledge base. Both surfaces below return document text, so running them is the user’s step — during their own validation of the new KB, and in their application code. This section exists so the agent can explain the surfaces (the Explore mode), reason about gap coverage, and report caller impact in a plan. It deliberately carries no request shapes, parameter tables or CLI invocations: the user takes those from the API reference linked at the end, or generates a skeleton from their own SDK. For applied configuration the agent uses the §4 read-only probes, which return configuration only, never document text.

A content-returning read needs the customer’s explicit yes first — the rule is in safety-and-iam (opens in a new tab) → “Content-returning reads”.

A managed KB has two query surfaces, and the choice between them is made per question shape, not per knowledge base.

Retrieve — one similarity search

One search, one round trip. Lowest cost and lowest latency, ranked chunks with relevance scores in the results, and the caller keeps full control over how — or whether — an answer is generated. This is the surface a self-managed KB already exposes, so it is the one existing callers are migrating.

AgenticRetrieveStream — an FM planning loop, MANAGED-only

Instead of a single search, a foundation model drives a loop: decompose the question into sub-queries → retrieve for each → judge whether the evidence is sufficient → iterate if not → return deduplicated chunks, plus a grounded answer unless the caller asks for chunks only. When passage-level context is not enough it can expand to a whole document, which is what makes summarization and “list every X” questions work. The response is always a stream, and the planning steps are visible as trace events.

It also routes across several knowledge bases: register a few, give each a natural-language description, and the planner chooses per sub-query, tagging each result with the KB that answered. Those descriptions are the routing contract — a specific one-sentence pitch per KB routes well, “internal docs” does not. This is what keeps a data-sources-per-KB split invisible to the caller (mapping (opens in a new tab) → “Gap coverage”). How many knowledge bases one call may route across is a quota — read it from kb-managed-quotas before quoting it, not a fixed law.

This surface does not exist on a self-managed (VECTOR) KB at all. It is the single largest capability the migration gains, and three rows of the mapping’s “Gap coverage” table lean on it. The agent should note the agentic surface as an adoption opportunity whenever it explains retrieval — net-new value, not a like-for-like port.

Choosing the surface

Reranking is optional on both. Start with Retrieve for direct lookups; reach for the agentic surface when questions are multi-part or the evidence spans several knowledge bases.

What changes for existing Retrieve callers — report this as a caller impact, every time

The operation names are unchanged, which makes repointing at the new knowledge base id look sufficient. It is not: the request body differs, and so does the meaning of a score. Report all of the following on every plan that changes the target KB, and in any answer about whether callers keep working. Give each item’s concrete before and after value as written here (the old and new URI form, the old and new key names, the zero-result behaviour), not only that something changes:

• The new knowledge base id. Callers must repoint at the owned KB’s id; the source id keeps working against the untouched source.
• The search-configuration wrapper changes. A self-managed call carries vectorSearchConfiguration; a managed call carries managedSearchConfiguration. Sending the self-managed wrapper to a managed KB passes client-side validation and is rejected by the service.
• Semantic-only search cannot be requested at all. overrideSearchType is a member of the self-managed wrapper only. The managed wrapper has no such member, so a semantic-only call is not “refused by the service” — it is structurally inexpressible, and fails inside the caller’s own SDK before a request is sent (§6 carries the exact message). Managed search is hybrid, always on and not configurable; the constraint and the feature are the same fact.
• Score thresholds need re-tuning. Scores are on a different scale on the managed knowledge base, and the scale also depends on the reranking mode, so a ported threshold silently changes how much it admits. Re-tune per reranking mode; compare ranking and content, not score magnitude.
• Reranking defaults by embedding type, and is a caller option. managedSearchConfiguration takes rerankingModelType. Omitted, it means MANAGED on a managed-embedding KB and behaves as NONE on a CUSTOM-embedding KB; an explicit MANAGED on a CUSTOM KB returns ValidationException: Managed reranking is not supported for knowledge bases with custom embedding models.
• The result location changes form. location.s3Location.uri changes from s3://<bucket>/<key> to https://<bucket>.s3.amazonaws.com/<key>, and a new documentId field carries the s3:// URI (or the page URL). Code that splits on s3:// gets no error, just a wrong value.
• The system metadata keys change. x-amz-bedrock-kb-* keys (for example x-amz-bedrock-kb-data-source-id) become _-prefixed keys (_data_source_id, _chunk_id, _source_uri, _document_title, _file_type, _language_code, _created_at, _last_updated_at, _data_source_type). User metadata keys are unchanged. Code reading the old key raises KeyError.
• Some filter operators are not supported. startsWith returns STARTS_WITH operation type is not supported for managed store. and stringContains returns STRING_CONTAINS operation type is not supported for managed store.; implicitFilterConfiguration is not a member of managedSearchConfiguration. Other operators keep their syntax inside the new wrapper.
• An ACL knowledge base returns nothing without a user. With aclEnabled, a call with no userContext returns 0 results and no error; a non-email userId also returns 0 results. Matching on the email ignores case and surrounding spaces.
• Overlapping data sources return duplicates. Two data sources over the same content return each chunk twice (different _chunk_ids).

Several of these return empty or wrong results rather than errors, so a caller cannot rely on an exception to find them. In the handoff, compare Retrieve against Retrieve with the reranking mode held constant, and on an ACL KB query as a known in-ACL user.

• A threshold does not port between the two query surfaces either. Retrieve returns scores in the results; the agentic surface exposes them only in trace events, so validation built on thresholds has to read the trace.

Filter syntax carries over unchanged, and metadata filtering keeps working.

If the user plans to adopt the agentic surface

• Cost has a different shape. It bills the agentic call plus the underlying retrieval calls it issues, times the iteration count, so an estimate from Retrieve volume alone understates it; the planner model sets the rate. Fetch current rates (cost-analysis (opens in a new tab) rules apply: fetched rates only, never recalled).
• It needs permissions beyond plain retrieval, including one for fetching whole documents; without that last one, retrieval still works and only document-expansion fails (weak summarization answers, not an error). Take the current action list from the API reference at adoption time.
• The intermediate sub-queries are an audit surface the planner invents — log the full trace, not just the returned results.
• Iterations drive both cost and latency, so the iteration cap is the main tuning knob.

Doc sources — the authority for request shapes, enums and bounds (this section deliberately carries none). Check the API reference for the current fields and limits before a call — it governs the shape, while the user guide governs behavior and defaults:

• Retrieve API reference: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html (opens in a new tab)
• AgenticRetrieveStream API reference: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html (opens in a new tab)
• Quotas and limits (knowledge bases per agentic call, iteration default and maximum — quota, not contract): https://docs.aws.amazon.com/bedrock/latest/userguide/quotas.html (opens in a new tab)

3b. ACL-aware retrieval (managed) — capability and its boundary

Source docs: kb-managed-acl and kb-test-retrieve-acl (re-verify against the docs). Enabled per data source via connectorParameters.aclEnabled (§2).

ACL awareness is NOT authorization — say this whenever the feature comes up. Per the AWS docs it is ACL-aware filtering, not a security boundary. The service does not authenticate end users: your application authenticates them and passes verified identity context, and because the service cannot verify that context’s authenticity, it must not be the sole access-control mechanism without upstream authentication. Describing it as “managed handles authorization” is a security misrepresentation.

Two stages. Pre-retrieval filtering — permissions (allowed/denied users, allowed/denied groups) are crawled during ingestion and results are filtered against the user context at query time. Real-time ACL verification — for connectors that support it, a live call to the source confirms the user still has access to each returned document, catching changes made since the last sync. Both stages use the same logic and deny always overrides allow. The pipeline fails closed: group-resolution failure, verification timeout or internal error withholds the documents.

Identity model — the sharp edge. The user is always identified by email, used as the universal identifier, and it must match the email on that user in every connected source (the match ignores case and surrounding spaces). There is no alias resolution and no cross-identity-provider mapping. Groups, by contrast, are identified however each connector represents them (name, id, other) and are matched against crawled memberships, which are resolved automatically at query time but are only as fresh as the last sync unless real-time verification covers that connector.

Connector support — not uniform, and it constrains authType:

Two planning consequences: enabling ACLs can force an authType (a SharePoint source needing real-time ACL cannot use OAUTH2_APP), and aclEnabled is immutable after create on S3 and permanent on Confluence (§2) — so the ACL decision is a create-time decision, not something to defer.

4. Read / status commands (pre-approved read-only probes)

• KB readiness: knowledgeBase.status → wait for ACTIVE.
• Data source readiness: dataSource.status → wait for AVAILABLE. These reads take no --client-token.

5. StartIngestionJob — a user-run handoff step

Ingestion is not an agent action, and this file gives no interface for running one. Once the agent confirms KB ACTIVE and all data sources AVAILABLE, the user starts ingestion on each new (owned) data source — never the original — and waits for COMPLETE. The agent’s part is to sequence the handoff and say what to expect, not to issue the call; the user takes the command from the AWS documentation.

Two things worth telling them up front, so a normal result is not read as a failure:

• The ingestion job’s numberOfMetadataDocumentsScanned count is not a health signal: do not tell the customer to expect a particular value; metadata filtering works either way.
• An ingestion that ends FAILED having scanned 0 documents is an environment or pipeline issue, not a configuration problem — re-check access to the source before touching the config the agent created.

6. API error → cause → fix

7. Client tokens (idempotency) — attach to mutating calls

Every resource-creating call the agent issues (create-knowledge-base, create-data-source) accepts a --client-token idempotency token. Attach one to each such call so a safe retry of an interrupted/uncertain call cannot create a duplicate resource — AWS returns the original result when it sees the same token with the same parameters.

--client-token is an idempotency value, not authentication and not a credential or secret. It is safe to log, record, and reuse for a retry — it grants no access and unlocks nothing. It is also independent of --profile. The two answer different questions: the ephemeral profile or assumed-role credentials authenticate the caller — that is what a call needs to be allowed at all; --client-token makes a create idempotent so a retry does not duplicate the resource. You use both together on a create: the credentials authenticate, the client token de-duplicates. Supplying AWS credentials does not remove the need for a client token, and a client token never authenticates a call. (Read/poll calls need only credentials — no client token; see below.) It is optional to the API on both CreateKnowledgeBase and CreateDataSource (§1/§2) — the current API references mark it optional on each — but required by this workflow, which attaches a stable per-operation token to every create for resume safety. Never call it API-required; either way it is an API idempotency input, never a secret.

• One token per logical operation, derived from the plan, never random at run time — not one shared across calls. Use the form in implement-kb (opens in a new tab) (“Use stable idempotency tokens”): mig-<prefix>-<hash>-<seq>, minted at plan time from the migration id, resource type and planned name, so a re-run sends the same token. A client token must be at least 33 characters.
• Reuse a token only for a deliberate retry of the same operation (same params); changed params require a new token.
• Read/poll calls carry NO client token. get-knowledge-base, list-knowledge-bases, get-data-source, list-data-sources, get-ingestion-job and sts get-caller-identity do not accept one. Never invent a correlation token for a read.
• Record the client token alongside the operation and the resulting resource ID so the user can correlate a logged mutating call with the exact resource and safely re-issue it. The token is an input only — it never appears in a get-* response, so capture it at call time.

clientToken field reference (confirm the current requirement and constraints before a call):

• CreateKnowledgeBase API reference (opens in a new tab)
• CreateDataSource API reference (opens in a new tab)

9. Rate limits & batching (build with a script, not rapid one-by-one CLI)

The build-time control-plane operations used here (CreateKnowledgeBase, CreateDataSource, StartIngestionJob, and the Get*/List* pollers) are throttled per-account, per-Region, and most limits are adjustable. Issuing many creates back-to-back on the CLI is the usual way to hit ThrottlingException, which is why the Implement phase generates a Python provisioning script that creates resources in rate-limit-aware batches (spec in implement-kb (opens in a new tab)).

What the script does to stay under the limits

• Throttles control-plane calls to a conservative requests-per-second (CONTROL_PLANE_RPS).
• Batches create-data-source calls (DATA_SOURCE_BATCH_SIZE) with an INTER_BATCH_PAUSE_SECONDS cool-down between batches.
• Backs off on ThrottlingException/429 with exponential delay + full jitter, on top of boto3's adaptive retry mode (Config(retries={"mode": "adaptive"})).
• Attaches a unique --client-token to every create (§7) so a retry after a throttle or timeout can’t duplicate a resource.

Hard limit to design around

Data sources per KB (quota L-F02D918A, read live). The first CreateDataSource past it returns ServiceQuotaExceededException. Split a larger source set across multiple KBs — the script’s KNOWLEDGE_BASES is a list for exactly this.

Verify, don’t hardcode

The script’s defaults (CONTROL_PLANE_RPS, batch size, pause, concurrency) are conservative starting points, not authoritative numbers. Re-check kb-managed-quotas and the current per-Region values for the user’s account in the Service Quotas console (https://console.aws.amazon.com/servicequotas/home/services/bedrock/quotas; search the relevant CreateDataSource / StartIngestionJob / CreateKnowledgeBase “requests per second” quotas) and lower the rate if throttling appears. Never assert a quota you have not verified.

Running the script is gated

Writing the script is fine; running it requires explicit approval of that run. It defaults to DRY_RUN = True (prints intended calls, mutates nothing); a real run needs --execute. It mutates owned resources only, never the original KB, and provisions only — it does not ingest, so it manages no ingestion-job concurrency. See implement-kb (opens in a new tab) for the build → review → preview → approve → execute → confirm-AVAILABLE flow.