> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon Bedrock AgentCore

> Connect Parallel Search to an Amazon Bedrock AgentCore Gateway, either from the Parallel Search API listing on AWS Marketplace or by creating the Gateway target yourself

For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](https://docs.parallel.ai/llms-full.txt). You may also fetch any page as Markdown by appending `.md` to its URL or sending `Accept: text/markdown`.

For Search and Extract, use `/v1/search` and `/v1/extract` for all new integrations and agent tool calls. Use `/v1beta/search` and `/v1beta/extract` only when maintaining an existing integration that already uses them. The request bodies changed too: on `/v1/extract`, `full_content`, `fetch_policy` and `excerpt_settings` go inside `advanced_settings`, and sending the v1beta top-level `excerpts`, `full_content` and `fetch_policy` to `/v1/extract` returns a 422. On `/v1/search`, `search_queries` is required (at least one short keyword query), and `max_results`, `source_policy` and `fetch_policy` go inside `advanced_settings`; sending only `objective`, or sending those fields at the top level, returns a 422. Do not substitute `/v1` for the documented FindAll or Ingest endpoint paths.

If you are evaluating Parallel Search or comparing it with other search APIs, read [How to Eval Parallel Search](https://docs.parallel.ai/search/evaluating-search.md) before you build the harness, especially its [Common pitfalls](https://docs.parallel.ai/search/evaluating-search.md#common-pitfalls) section. The most common mistake is sending the raw question as both `objective` and the only entry in `search_queries`. Write a goal-style `objective` and 1-3 short keyword queries instead.

[Amazon Bedrock AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) turns a remote MCP server into tools that agents in your AWS account can call, with AWS handling authorization and credential injection. This guide connects a Gateway to Parallel's AWS-hosted MCP server at `https://mcp-aws.parallel.ai/mcp`, which serves the [Parallel Search API listing](https://docs.parallel.ai/integrations/aws-marketplace.md#search-api-listing) on AWS Marketplace.

You can set it up in either of two ways:

* **[From AWS Marketplace](#option-a-connect-from-aws-marketplace)**: launch the product from your subscription, create an OAuth client from the access keys Parallel provides, and add Parallel to a Gateway, all in the AWS console. Start here if you're new to AgentCore.
* **[With the AWS CLI](#option-b-connect-with-the-aws-cli)**: create the Gateway, credential provider, and target yourself with a Parallel API key. Use this for infrastructure as code, or when you want to control every setting.

Either way, you end up with:

* A Gateway that only callers you authorize can invoke.
* Your Parallel credentials stored in AgentCore Identity, never hard-coded into an agent or request body. Option A stores an OAuth client; Option B stores an API key.
* A Gateway target pointed at `https://mcp-aws.parallel.ai/mcp`, with the Gateway adding an `Authorization: Bearer` header on every outbound call.

## Prerequisites

* A subscription to the [Parallel Search API listing](https://aws.amazon.com/marketplace/pp/prodview-apfsi3l2dqslu). Option A walks you through subscribing.
* An AWS Region where both the AgentCore control plane and the Gateway data plane are available. Check the [Region tables](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html) first; the two lists differ.
* Permission to create AgentCore Gateways and targets, and IAM roles and policies.

## Option A: Connect from AWS Marketplace

**1. Launch the product**

Subscribe to the [Parallel Search API listing](https://aws.amazon.com/marketplace/pp/prodview-apfsi3l2dqslu) if you haven't already. Then, in the AWS Marketplace console, open **Manage subscriptions**, choose **Parallel Search API**, and choose **Launch product**.

![Parallel Search API subscription page in the AWS Marketplace console, with the Launch product button highlighted](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/launch-product.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=e53ec1dfdb0ef6850f746fb6ec8a8402)

**2. Choose Amazon Bedrock AgentCore**

Under **Launch method**, select **Amazon Bedrock AgentCore** instead of **API**. The page then lists the four steps that connect Parallel to AgentCore.

![Launch Parallel Search API page with the Amazon Bedrock AgentCore launch method selected](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/launch-method.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=3c6f277bf6c3b8ed570ba5389e1c8707)

**3. Register with Parallel and get your access keys**

In step 2 on the page, choose **Sign in or register with vendor** if you haven't registered yet. Parallel's platform opens in a new tab, where you sign in or create a new organization linked to your AWS account.

When you return, AWS Marketplace saves your access keys in AWS Secrets Manager. Choose **Show access keys** to see the **Client Id**, **Client Secret**, and **Discovery URL**. You need all three in the next step.

![Register with the vendor step showing the Client Id, Client Secret, and Discovery URL access keys, and the Sign in or register with vendor button](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/access-keys.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=e0dbd07904f87725d155ff4bcbbf395d)

**4. Create an Outbound Auth**

In step 3 on the page, choose **Create Outbound Auth**. If you already created an Outbound Auth for Parallel, you can skip this step and reuse it.

![Create Outbound Auth in Amazon Bedrock AgentCore step with the Create Outbound Auth button highlighted](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/create-outbound-auth.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=d5f82779f2d5825b618bf7ec7332754b)

The AgentCore console opens the **Add OAuth Client** page. Fill in:

* **Name**: any name, such as `parallel-oauth-client`.
* **Provider**: **Custom provider**.
* **Configuration type**: **Discovery URL**.
* **Discovery URL**, **Client ID**, and **Client secret**: the access keys from the previous step.

Leave the other fields at their defaults and choose **Add OAuth Client**.

![Add OAuth Client page in the AgentCore console, with the Discovery URL, Client ID, and Client secret fields highlighted](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/add-oauth-client.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=f1bb69a265555a61c42abbf616e5b522)

**5. Add Parallel to a Gateway**

In step 4 on the page, under **Gateway type**, choose **Add product to new gateway** or **Add product to existing gateway**. Then choose **Set up on AgentCore**.

![Add product to an AgentCore gateway step with the gateway type options and the Set up on AgentCore button highlighted](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/add-to-gateway.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=0e8a42789d50616d8edf6dc33bffed84)

For a new gateway, AgentCore opens the **Create gateway** form. Enter a **Gateway name**, then choose an **Inbound Auth type**, which controls who can call the Gateway. Choose **Use IAM permissions** if you'll call the Gateway from the [Bedrock Responses API](#from-amazon-bedrock). Under **Permissions**, keep **Create default role**.

![Create gateway form with Use IAM permissions selected as the Inbound Auth type](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/create-gateway.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=90a79b0a2b3bc4a4930f96eb242071c3)

In the target section, set:

* **Target name**: a short, stable name such as `parallel-search`. It becomes part of every tool name your agents see. See [Verify](#verify).
* **Target type**: **MCP server**.
* **MCP endpoint**: `https://mcp-aws.parallel.ai/mcp`.
* **MCP listing mode**: **Default**.
* **Outbound Auth configurations**: **OAuth client**, then choose the OAuth client you created in the previous step.

Choose **Create Gateway**. To add Parallel to an existing gateway instead, add a target with the same settings.

![Gateway target settings with MCP server as the target type and an OAuth client selected under Outbound Auth configurations](https://mintcdn.com/parallel-6fabab31-mtje7p526we/GYN_b7RoLPb4VkFn/images/aws-agentcore/gateway-target.png?fit=max\&auto=format\&n=GYN_b7RoLPb4VkFn\&q=85\&s=09d4df535a9cc95f1a86fb510116cbd6)

> [!WARNING]
>
> To call the Gateway from the [Bedrock Responses API](#from-amazon-bedrock), the Gateway must use IAM inbound authorization. The **Create gateway** form defaults to JSON Web Tokens (JWT), which the Responses API can't use.

## Option B: Connect with the AWS CLI

Use this path to add Parallel to a Gateway you already manage, or to script the setup. You need:

* An AgentCore Gateway. To create one, see [Set up an AgentCore gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building.html). Use IAM inbound authorization if you'll call it from the [Bedrock Responses API](#from-amazon-bedrock).
* An API key from the Parallel organization linked to your Parallel Search API subscription.

### Step 1: Store your Parallel API key in AgentCore Identity

Create an API-key credential provider. AgentCore Identity stores the key in an AWS Secrets Manager secret it manages for you.

```json create-credential-provider.json theme={"system"}
{
  "name": "<PARALLEL_CREDENTIAL_PROVIDER_NAME>",
  "apiKey": "<PARALLEL_API_KEY>"
}
```

```bash theme={"system"}
aws bedrock-agentcore-control create-api-key-credential-provider \
  --cli-input-json file://create-credential-provider.json
```

> [!WARNING]
>
> Pass the key through a file (as above), the console, or another channel your organization approves for secrets. Don't pass it as a bare `--api-key` flag, which lands in your shell history.

Save the `credentialProviderArn` from the response for the next step. The Gateway's service role must be able to read this credential before you add the target. See [Set up outbound authorization for your gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-outbound-auth.html).

### Step 2: Add the Parallel MCP target

This request points the Gateway at Parallel's AWS-hosted MCP server. The `credentialPrefix` value has a trailing space on purpose, so the injected header reads exactly `Authorization: Bearer <key>`. Because `https://mcp-aws.parallel.ai/mcp` rejects requests without a key, a missing or misconfigured credential fails with a `401` instead of reaching Parallel.

```json create-search-target.json theme={"system"}
{
  "name": "parallel-search",
  "description": "Parallel Search on AWS",
  "targetConfiguration": {
    "mcp": {
      "mcpServer": {
        "endpoint": "https://mcp-aws.parallel.ai/mcp",
        "listingMode": "DEFAULT"
      }
    }
  },
  "credentialProviderConfigurations": [
    {
      "credentialProviderType": "API_KEY",
      "credentialProvider": {
        "apiKeyCredentialProvider": {
          "providerArn": "<PARALLEL_API_KEY_CREDENTIAL_PROVIDER_ARN>",
          "credentialLocation": "HEADER",
          "credentialParameterName": "Authorization",
          "credentialPrefix": "Bearer "
        }
      }
    }
  ]
}
```

```bash theme={"system"}
aws bedrock-agentcore-control create-gateway-target \
  --gateway-identifier <GATEWAY_ID> \
  --cli-input-json file://create-search-target.json
```

> [!NOTE]
>
> `listingMode: "DEFAULT"` caches the discovered tools at the control plane. Leave it. `DYNAMIC` re-runs discovery on every call, which Parallel's fixed tool set doesn't need.

Creating the target starts tool discovery, which runs asynchronously. Poll `get-gateway-target` until `status` is `READY`. If it doesn't reach `READY`, contact [aws-mp@parallel.ai](mailto:aws-mp@parallel.ai).

## Verify

Gateway exposes each tool as `<target name>___<tool name>`, with three underscores. With a target named `parallel-search`, your agents see `parallel-search___web_search`. Renaming the target renames the tools your agents already know. See [how AgentCore Gateway tools are named](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-tool-naming.html).

To confirm the setup, list the Gateway's tools as an authorized caller. The [Strands example](#from-strands-agents) below prints the list. If Parallel later changes the tools it exposes, re-run discovery with `SynchronizeGatewayTargets`.

## Calling the Gateway

### From Amazon Bedrock

The [Bedrock Responses API](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-server-side.html) can call your Gateway's tools for you. Add the Gateway as an `mcp` tool with `connector_id` set to the Gateway ARN, and authenticate with an [Amazon Bedrock API key](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html):

```bash theme={"system"}
curl https://bedrock-mantle.<REGION>.api.aws/v1/responses \
  -H "Authorization: Bearer $BEDROCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID>",
    "tools": [
      {
        "type": "mcp",
        "server_label": "parallel_search",
        "connector_id": "<GATEWAY_ARN>",
        "require_approval": "never"
      }
    ],
    "input": "Find the most recent official sources about <TOPIC>."
  }'
```

This works when:

* The Gateway uses IAM inbound authorization.
* The role making the request has `bedrock-agentcore:InvokeGateway` on the Gateway ARN.
* `<MODEL_ID>` is a model that supports the Responses API in your Region. See [API compatibility by model](https://docs.aws.amazon.com/bedrock/latest/userguide/models-api-compatibility.html).

### From Strands Agents

Your agent can connect to the Gateway as an MCP server. A Gateway with IAM inbound authorization requires every request to be signed with AWS credentials, and AWS's [`mcp-proxy-for-aws`](https://pypi.org/project/mcp-proxy-for-aws/) package does that for you. This example uses [Strands Agents](https://strandsagents.com):

```bash theme={"system"}
pip install strands-agents mcp-proxy-for-aws
```

```python theme={"system"}
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client
from strands import Agent
from strands.tools.mcp import MCPClient

GATEWAY_URL = "<GATEWAY_URL>"  # from the Gateway's details in the AgentCore console

gateway = MCPClient(lambda: aws_iam_streamablehttp_client(
    endpoint=GATEWAY_URL,
    aws_region="<REGION>",
    aws_service="bedrock-agentcore",
))

with gateway:
    tools = gateway.list_tools_sync()
    print([tool.tool_name for tool in tools])

    agent = Agent(tools=tools)
    agent("What changed in the EU AI Act this month? Cite your sources.")
```

The AWS identity running this code needs `bedrock-agentcore:InvokeGateway` on the Gateway.

The tools work the same as when you call the [Parallel MCP server](https://docs.parallel.ai/integrations/mcp/quickstart.md) directly, except that their names start with the target name, such as `parallel-search___web_search`.

## Pricing

Searches through AgentCore bill through your AWS Marketplace subscription at exactly the rates on our [Pricing](https://docs.parallel.ai/getting-started/pricing.md#search-api) page. On AWS, 1 usage unit = 1 cent USD, and each search is billed as the number of units it costs at those rates.

## Support

For help with the AgentCore integration, contact [aws-mp@parallel.ai](mailto:aws-mp@parallel.ai).