Using Amazon Bedrock Web Search From a Normal Application

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var apiKey = Environment.GetEnvironmentVariable(
    "BEDROCK_API_KEY");

if (string.IsNullOrWhiteSpace(apiKey))
{
    throw new InvalidOperationException(
        "BEDROCK_API_KEY is not configured.");
}

var endpoint =
    "https://bedrock-mantle.us-west-2.api.aws/openai/v1/responses";

using var httpClient = new HttpClient();

httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var request = new
{
    model = "openai.gpt-5.6-terra",

    input = "What are the latest developments in .NET?",

    tools = new[]
    {
        new
        {
            type = "web_search",
            external_web_access = false,
            search_context_size = "medium"
        }
    }
};

using var response = await httpClient.PostAsJsonAsync(
    endpoint,
    request);

var responseBody = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Bedrock request failed: {(int)response.StatusCode} " +
        $"{response.ReasonPhrase}. Response: {responseBody}");
}

using var document = JsonDocument.Parse(responseBody);

var root = document.RootElement;

Console.WriteLine("Generated Answer:");

foreach (var item in root.GetProperty("output").EnumerateArray())
{
    if (!item.TryGetProperty("type", out var itemType) ||
        itemType.GetString() != "message")
    {
        continue;
    }

    if (!item.TryGetProperty("content", out var content))
    {
        continue;
    }

    foreach (var block in content.EnumerateArray())
    {
        if (!block.TryGetProperty("type", out var blockType) ||
            blockType.GetString() != "output_text")
        {
            continue;
        }

        if (block.TryGetProperty("text", out var text))
        {
            Console.WriteLine(text.GetString());
        }

        if (!block.TryGetProperty("annotations", out var annotations))
        {
            continue;
        }

        foreach (var annotation in annotations.EnumerateArray())
        {
            if (annotation.TryGetProperty("type", out var type) &&
                type.GetString() == "url_citation")
            {
                var title = annotation.GetProperty("title").GetString();
                var url = annotation.GetProperty("url").GetString();

                Console.WriteLine();
                Console.WriteLine($"Source: {title}");
                Console.WriteLine($"URL: {url}");
            }
        }
    }
}

Let's understand the important parts.

First, the application reads the API key from the environment. This prevents credentials from being exposed in the source code.

Next, it creates an HTTP request with the model name, user prompt, and Web Search tool configuration.

The following section enables Web Search:

tools = new[]
{
    new
    {
        type = "web_search",
        external_web_access = false,
        search_context_size = "medium"
    }
}

The search context size controls how much search-result context can be returned to the model for each search call.

The available values are:

A larger context can provide more information, but it can also increase input-token usage and associated inference costs.

Finally, the application reads the response and extracts both the generated text and its source citations.

6. Read and Display Source Citations

One of the most useful parts of Web Search is that the response contains citations.

A normal AI-generated answer might provide information without showing where it came from. This makes it difficult for users to verify the information.

Amazon Bedrock Web Search provides URL citation annotations with details such as:

• Source title.
• Source URL.
• Start position in the generated text.
• End position in the generated text.

For example, the response contains annotations similar to this:

{
  "type": "url_citation",
  "title": "Latest .NET Platform Updates",
  "url": "https://example.com/dotnet-updates",
  "start_index": 120,
  "end_index": 245
}

The application should retain these citations and display them alongside the generated answer.

Do not simply discard the annotations after extracting the response text. They are important for transparency and allow users to verify the information.

Also, a citation does not necessarily mean that Fetch retrieved the complete page. A citation can be based on a Search observation.

7. Control External Web Access

One important consideration when integrating search into an enterprise application is data governance.

Amazon Bedrock provides the external_web_access setting to control whether Fetch can retrieve live content from the external web.

There are two main configurations.

For applications that process confidential business information, explicitly setting external_web_access to false is a sensible starting point.

When external access is enabled, the application must also have the bedrock-websearch permission.

This is an important security distinction. Enabling external access can allow request-related information to leave the AWS boundary during retrieval.

Do not assume that an HTTP 200 response means every Fetch operation succeeded. AWS documents that a request can complete using Search observations even when Fetch attempts are denied.

For production applications, review IAM permissions, enable appropriate CloudTrail data-event monitoring, and decide whether external retrieval is acceptable for the information being processed.

8. Production Considerations

A working API integration is only the beginning. Before introducing Web Search into a production application, consider the following areas.

Authentication and secrets management: Store API credentials in a secure configuration provider such as AWS Secrets Manager. Avoid committing keys to Git repositories or writing them into application logs.

Timeouts and cancellation: Configure appropriate request timeouts and pass cancellation tokens through the HTTP request. Search-enabled requests can take longer than ordinary model requests.

Error handling: Handle authentication failures, permission errors, throttling, service errors, and invalid model or Region configurations.

Citation handling: Preserve source titles and URLs. Display citations to users rather than presenting search-grounded information as an unsupported statement.

Cost management: Search context size affects the amount of information passed to the model. Review current Amazon Bedrock pricing and measure token usage for your application's workload.

Monitoring: Use application logs and CloudTrail to investigate request failures and Web Search activity. Avoid logging API keys or sensitive user prompts.

Testing: Test questions that require current information, questions that do not require search, and questions where reliable search results are unavailable.

Summary

Amazon Bedrock Web Search makes it easier to build AI applications that need current information. Instead of creating a custom search engine or managing a separate retrieval workflow, developers can enable the built-in Web Search tool through the Responses API.

In this example, we connected a C# application using HttpClient, configured the model and search tool, and extracted the generated answer with its source citations.

The most important implementation details are selecting a supported model and Region, using the Bedrock Mantle endpoint, configuring IAM permissions, and deciding whether external web access is appropriate.

For production applications, treat citations, security, error handling, and cost management as part of the integration rather than adding them later.