AWSAWS Certified Generative AI Developer - Professional2026-101.5 Design retrieval mechanisms for FM augmentation

Expose one retrieval contract across callers

Completed by the knowledge check

Learning objective

Expose retrieval through standardized APIs, function calling, and MCP client libraries.

Core idea

A retrieval interface should return authorized evidence under a stable contract, regardless of whether the caller is application code, a model requesting a function, or an agent using Model Context Protocol (MCP). These entry points differ in discovery and transport. They should not implement different permission rules or silently change evidence provenance.

For an architect integrating retrieval, separate three responsibilities: describe the operation, authorize and execute it, and preserve the result’s evidence identity. A model-selected function name is a proposed action. An MCP tool description is a discovery artifact. Neither establishes the caller’s right to retrieve a document.

How it works

Define the retrieval operation once

For Knowledge Bases, Retrieve supplies the AWS retrieval interface. 1.5.6 covers its request (knowledgeBaseId, retrievalQuery.text), its retrievalResults and nextToken, and the distinction from RetrieveAndGenerate; this Bite is about exposing that operation consistently to different callers.

An application-facing operation can wrap that interface with a narrower schema. For example, define a search operation that accepts a query and an allowed result-count request, then returns evidence records and explicit completion status. Those field names are your application contract, not additional Bedrock parameters. Keep Bedrock-specific search settings behind the server boundary when callers should not control them.

Validate inputs, bound query size and result count, and derive authorization from authenticated caller context. Apply the trusted filter and document checks from 1.4.6. Never accept an unverified tenant identifier from a tool argument as sufficient authority. If an input is unsupported, return a clear validation failure rather than silently ignoring it.

Preserve document identity, revision, content, and source location through the wrapper. A plain string response is convenient for a demonstration but loses the structure needed for permission review, deduplication, and citations. Give downstream context assembly enough information to identify which source supports a claim; see 1.5.11.

Adapt function calling to the contract

For a supported Bedrock model using Converse, supply the tool definition through toolConfig.tools. A custom toolSpec gives the tool a name, description, and inputSchema.json. Describe the retrieval operation narrowly enough that the model can choose it without treating it as a general-purpose execution tool.

In client-side tool use, Converse returns stopReason: tool_use and a toolUse content block containing the requested name, input, and toolUseId. Your application checks the name against its allowlist, validates the input, and invokes the retrieval operation under trusted caller context. Append the assistant’s tool request message, then send a user message containing the corresponding toolResult. Echo the same toolUseId so the model can associate the result with the request.

An execution error can be represented with toolResult.status: error, as in the AWS example. Distinguish that from a successful search that finds no authorized evidence. Otherwise, the generator can mistake service unavailability for proof that no policy exists. Bound the number of tool rounds at the application level instead of allowing indefinite repeated searches.

This execution responsibility is scoped to the client-side Converse integration described here. Keep the dispatcher explicit in your architecture: it validates the request, supplies trusted caller context, and records the retrieval outcome before returning evidence to the model. A tool definition alone does not implement those steps.

Adapt MCP discovery and invocation

Amazon Bedrock AgentCore Gateway acts as an MCP server that aggregates the tools of its MCP targets into one tools/list response. MCP targets include Lambda functions, API Gateway REST API stages, OpenAPI schemas, Smithy models, existing MCP servers, built-in templates from integration providers, and built-in connectors. For a custom retrieval wrapper, an OpenAPI schema or a Lambda function target describes the wrapper operation. The gateway is an interface and authentication boundary, not a replacement for the wrapper’s document authorization logic.

AWS documents tools/list for discovery and tools/call for invocation. Discovery returns tool names, descriptions, and parameter schemas. Invocation identifies the tool name and arguments and returns tool content with metadata. Use the discovered names rather than assuming a function name from another integration is identical.

For an Amazon Bedrock Managed Knowledge Base, a built-in connector target replaces the wrapper; it is supported only for managed knowledge bases. It exposes Retrieve, a single hybrid search, and AgenticRetrieveStream, a multi-step retrieval that can also return a synthesized answer with citations. The knowledge base identifier and retrieval settings are set on the target, so by default the agent supplies only retrievalQuery.text. Tool names carry the target name as a prefix, which is one more reason to call the discovered names. If the knowledge base filters results by access control, the calling application, not the model, must pass userContext in the tools/call arguments. The Gateway does not populate userContext from the caller’s IAM identity, so the trusted-identity rule above applies here too.

For client libraries, AWS examples use Python’s mcp.ClientSession with mcp.client.streamable_http.streamablehttp_client, and the Strands MCPClient adapter. The latter exposes list_tools_sync and call_tool_sync; discovery can require pagination. Select a client compatible with the gateway’s configured protocol versions, and test transport, authentication, and result handling together. A library import alone does not make an arbitrary REST endpoint an MCP server.

Gateway accepts only versions listed in protocolConfiguration.mcp.supportedVersions. Match the client’s MCP-Protocol-Version to that configuration and the version-specific request format documented by AWS. Do not copy one version’s raw request headers into another version without checking them. Keep credentials in the transport’s authentication handling, outside model-generated tool arguments.

Key distinctions and trade-offs

The following surfaces expose the same retrieval behavior differently:

Surface	Caller interaction	Application responsibility
Retrieval API	Explicit request and structured response	Validate, authorize, retrieve, and preserve evidence
Bedrock function calling	Model proposes a named tool with schema-shaped input	Dispatch approved requests and correlate `toolResult`
MCP client	Discover tools, then invoke the selected tool	Use compatible transport and trusted caller identity

A direct API is suitable when application code already knows what to retrieve. Function calling lets a model decide when retrieval is needed but adds a tool-use control loop. MCP offers a common discovery and invocation interface across tools, but introduces protocol and transport compatibility responsibilities.

All three surfaces reach the same retrieval operation; function calling and MCP each add a hop in front of it.

Keep the core retrieval semantics stable across all three. If the direct API returns only current revisions but the MCP adapter returns stale cached text, callers no longer share the same contract. Evaluate equivalent requests from each surface and compare authorized source identities, not only whether each returned readable text.

Architecture / decision scenario

An enterprise policy service has three consumers: a web assistant, a Bedrock conversational application, and an MCP-based engineering agent. The team defines one permission-enforcing retrieval operation backed by Retrieve. It returns source identity, revision, text, and location, and bounds requested result counts.

The web assistant calls the API directly. The Converse application defines a retrieval toolSpec, validates toolUse.input, and returns the structured evidence in a matching toolResult. The policy corpus sits in a custom knowledge base, which the managed connector does not support, so AgentCore Gateway exposes the operation from an OpenAPI target. The agent discovers and calls it using an MCP client.

The team tests the same user identity and query through all three paths. A caller cannot widen access by supplying another tenant in tool arguments. A successful empty search remains distinct from a failed invocation. When an MCP protocol configuration changes, the team verifies discovery and calls before rollout; it does not change the retrieval permission policy to accommodate a transport failure.

Common exam traps

Treating a tool schema as authorization or runtime input validation.
Claiming Converse automatically executes a custom client-side tool.
Returning a toolResult with the wrong toolUseId.
Treating MCP as a synonym for any JSON-over-HTTP API.
Omitting discovery pagination or protocol-version compatibility.
Dropping source metadata because the model only needs readable text.

What to remember

Expose one authorized evidence contract and adapt it to each calling surface. Use Retrieve for evidence, Converse tool blocks for client-side function calling, and an MCP-compatible gateway with compatible clients for discovery and invocation. Keep identity, validation, bounded execution, and provenance behind the interface rather than delegating them to model-generated arguments.