Amazon Bedrock Managed Knowledge Bases as Connector Target

Amazon Bedrock Managed Knowledge Bases provides fully managed retrieval-augmented generation (RAG): Amazon Bedrock handles the vector store, data ingestion, and retrieval optimization, so there is no retrieval infrastructure for you to provision or operate. Amazon Bedrock AgentCore exposes a managed knowledge base as a native Gateway connector — you attach it to your AgentCore Gateway and your agents discover and query it with standard Model Context Protocol (MCP) calls, with no custom retrieval integration to build. For details on creating and managing a managed knowledge base, see Knowledge bases for Amazon Bedrock in the Amazon Bedrock User Guide.

The connector exposes two tools. The first one is AgenticRetrieveStream. Instead of a single lookup, it plans a retrieval strategy, runs multiple retrieval steps across your managed knowledge bases, optionally expands to full documents, and streams back both the supporting results and a synthesized, citation-backed answer. Retrieve performs a single hybrid search and returns the most relevant passages.

The following sections walk through how the connector works, agentic retrieval in depth, common use cases, how to set up a target, and the input and response schemas for both tools.

How it works

Amazon Bedrock AgentCore provides a built-in connector to Amazon Bedrock Managed Knowledge Bases. The Gateway handles schema management, endpoint resolution, and service authentication. The connector exposes two tools, which your agent discovers with tools/list:

A single Retrieve invocation follows this flow:

For the agentic retrieval flow, see Agentic retrieval.

Agentic retrieval

AgenticRetrieveStream treats a question as a task: instead of the single hybrid search that Retrieve runs for one query, it plans a retrieval strategy, runs multiple retrieval steps across your managed knowledge bases, and streams back the supporting results and a synthesized, citation-backed answer — all in one tool call. The synthesized answer is returned by default; set generateResponse to false to return results only.

Your agent invokes it with a conversation (messages). The retrievers it queries — each pointing at a managed knowledge base — are configured by the administrator on the target, not supplied by the agent. Planning and retrieval progress streams over MCP as notifications/message, and the results and answer are returned in the tool result.

For more about how agentic retrieval works, see Knowledge bases for Amazon Bedrock in the Amazon Bedrock User Guide.

For the request and event schema, see AgenticRetrieveStream input schema and AgenticRetrieveStream response format.

Use cases

Set up a managed knowledge base

For instructions on how to create a Gateway Target with the Amazon Bedrock Managed Knowledge Bases connector configuration, including setup examples using the Python SDK and CLI, see Set up a managed knowledge base in the target configuration guide.

Configure the Gateway Service Role

The Gateway needs a service role that allows the AgentCore service to perform retrieval actions on the managed knowledge base on your behalf. For the required IAM permissions and policy configuration, see Configure the Gateway Service Role in the target configuration guide.

Invoke the tools

After you create the target, your agent discovers the tools with tools/list and calls them with tools/call. Each tool name is prefixed with the target name, in the form <target-name>_<tool-name>_AgenticRetrieveStream or managed-kb___Retrieve).

For AgenticRetrieveStream, your agent passes only the conversation. The retrievers are configured on the target by the administrator, so the agent does not send knowledge base IDs:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "managed-kb___AgenticRetrieveStream",
    "arguments": {
      "messages": [
        { "role": "user", "content": { "text": "How do I configure a knowledge base target?" } }
      ]
    }
  }
}

For Retrieve, the managed knowledge base identifier is bound to the target, so your agent passes only the query:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "managed-kb___Retrieve",
    "arguments": {
      "retrievalQuery": { "text": "What is Amazon Bedrock AgentCore?" }
    }
  }
}

If you exposed retrieval parameters to the agent (see Control which parameters the agent can set), the agent can override the administrator-configured defaults at call time:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "managed-kb___Retrieve",
    "arguments": {
      "retrievalQuery": { "text": "insurance benefits" },
      "retrievalConfiguration": {
        "managedSearchConfiguration": { "numberOfResults": 2 }
      }
    }
  }
}

AgenticRetrieveStream input schema

The schema returned by tools/list is the set of fields your agent can set when it calls AgenticRetrieveStream. By default, the only agent-visible field is messages. The retrievers to query and all retrieval configuration are administrator-set on the target — see Set up a managed knowledge base. To expose more fields to the agent, configure parameterOverrides on the target — see Control which parameters the agent can set.

{
  "type": "object",
  "properties": {
    "messages": {
      "description": "The messages for the agentic retrieval conversation. Contains the user query and conversation history.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "description": "The role of the message sender (user or assistant).",
            "type": "string",
            "enum": ["user", "assistant"]
          },
          "content": {
            "description": "The content of the message.",
            "type": "object",
            "properties": {
              "text": {
                "description": "The text content of the message.",
                "type": "string"
              }
            }
          }
        },
        "required": ["content", "role"]
      }
    }
  },
  "required": ["messages"]
}

For the administrator-set fields — retrievers, agenticRetrieveConfiguration (foundation model, reranking, maxAgentIteration, and guardrails through policyConfiguration), and generateResponse — see Set up a managed knowledge base and Configuration reference.

AgenticRetrieveStream response format

AgenticRetrieveStream streams a sequence of events. Over MCP, trace events are delivered as notifications/message for real-time progress, and the retrieval results and synthesized answer are delivered in the tool result. The stream emits the following event types:

A result event has the following structure:

{
  "result": {
    "results": [
      {
        "content": {
          "text": "Amazon Bedrock AgentCore manages the storage, indexing, and retrieval infrastructure for a managed knowledge base...",
          "mimeType": "text/plain"
        },
        "sourceRetriever": { "identifier": "kb-retriever-1" },
        "metadata": { "x-amz-bedrock-kb-source-uri": "s3://example-bucket/docs/overview.pdf" }
      }
    ],
    "generatedResponse": {
      "answer": "A managed knowledge base lets Amazon Bedrock AgentCore handle the vector store, ingestion, and retrieval for you.",
      "citations": [
        {
          "startIndex": 0,
          "endIndex": 98,
          "references": [ { "..." : "references to supporting results" } ]
        }
      ]
    }
  }
}

Retrieve input schema

The schema returned by tools/list is the set of fields your agent can set when it calls Retrieve. By default, the only agent-visible field is retrievalQuery.text. The managed knowledge base identifier and all retrieval settings are administrator-set on the target. To expose retrieval settings such as numberOfResults or a metadata filter to the agent, configure parameterOverrides on the target — see Control which parameters the agent can set.

{
  "type": "object",
  "properties": {
    "retrievalQuery": {
      "description": "Contains the query to send the managed knowledge base.",
      "type": "object",
      "properties": {
        "text": {
          "description": "The text of the query made to the managed knowledge base.",
          "type": "string"
        }
      }
    }
  },
  "required": ["retrievalQuery"]
}

For the administrator-set and overridable fields — numberOfResults, a metadata filter, overrideSearchType, reranking, and multimodal image queries — see Configuration reference.

Retrieve response format

The Retrieve tool returns an MCP tools/call result wrapped in a JSON-RPC envelope. The isError and content fields are inside result, and the text field contains the serialized retrievalResults payload:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "{\"retrievalResults\":[{\"content\":{\"type\":\"TEXT\",\"text\":\"Amazon Bedrock AgentCore manages the storage, indexing, and retrieval infrastructure for a managed knowledge base...\"},\"location\":{\"type\":\"S3\",\"s3Location\":{\"uri\":\"s3://example-bucket/docs/overview.pdf\"}},\"score\":0.87,\"metadata\":{\"x-amz-bedrock-kb-source-uri\":\"s3://example-bucket/docs/overview.pdf\"}}]}"
      }
    ]
  }
}

Each item in retrievalResults has the following structure:

Configuration reference

The following fields are set by the administrator in parameterValues, or exposed to the agent with parameterOverrides, when you create the target. For where to set them, see Set up a managed knowledge base and Control which parameters the agent can set.

AgenticRetrieveStream — agenticRetrieveConfiguration

Retrieve — managedSearchConfiguration

Access control filtering

If your managed knowledge base uses access control to filter results per user or group, the calling application must pass a userContext with the request. The Gateway passes userContext through to the knowledge base, which applies access-control filtering based on it. The Gateway does not populate userContext from the caller’s IAM identity — your application must supply it explicitly.

To use it:

{
  "arguments": {
    "retrievalQuery": { "text": "insurance benefits" },
    "userContext": {
      "userId": "user@example.com"
    }
  }
}