Adding Web Search to an AI App Without Building Your Own Search Service

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

public class BedrockSearchService
{
    private readonly HttpClient _httpClient;
    private readonly IConfiguration _configuration;

    public BedrockSearchService(
        HttpClient httpClient,
        IConfiguration configuration)
    {
        _httpClient = httpClient;
        _configuration = configuration;
    }

    public async Task<string> AskAsync(
        string question,
        CancellationToken cancellationToken)
    {
        var apiKey = Environment.GetEnvironmentVariable(
            "BEDROCK_API_KEY");

        if (string.IsNullOrWhiteSpace(apiKey))
        {
            throw new InvalidOperationException(
                "Bedrock API key is missing.");
        }

        var baseUrl = _configuration["Bedrock:BaseUrl"];
        var model = _configuration["Bedrock:Model"];

        if (string.IsNullOrWhiteSpace(baseUrl) ||
            string.IsNullOrWhiteSpace(model))
        {
            throw new InvalidOperationException(
                "Bedrock configuration is incomplete.");
        }

        var endpoint = $"{baseUrl.TrimEnd('/')}/responses";

        using var request = new HttpRequestMessage(
            HttpMethod.Post,
            endpoint);

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", apiKey);

        request.Content = JsonContent.Create(new
        {
            model,
            input = question,
            tools = new[]
            {
                new
                {
                    type = "web_search",
                    search_context_size = "medium",
                    external_web_access = false
                }
            }
        });

        using var response = await _httpClient.SendAsync(
            request,
            cancellationToken);

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

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

        using var document = JsonDocument.Parse(responseBody);

        var output = document.RootElement.GetProperty("output");

        var answer = new System.Text.StringBuilder();

        foreach (var item in output.EnumerateArray())
        {
            if (!item.TryGetProperty("type", out var type) ||
                type.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" &&
                    block.TryGetProperty("text", out var text))
                {
                    answer.AppendLine(text.GetString());
                }
            }
        }

        return answer.ToString();
    }
}

This service sends the user question and enables Web Search through the tools array.

Notice the following configuration:

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

The model can decide when it needs to search. The application does not have to make a separate search-provider request or manually execute the search-and-fetch sequence.

We explicitly set external_web_access to false. This allows Search and cached Fetch operations while keeping retrieval within the AWS boundary.

Expose the Service Through an API Endpoint

The next step is to expose the functionality to application clients.

Create a controller named AIController.cs:

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/ai")]
public class AIController : ControllerBase
{
    private readonly BedrockSearchService _searchService;

    public AIController(BedrockSearchService searchService)
    {
        _searchService = searchService;
    }

    [HttpPost("ask")]
    public async Task<IActionResult> Ask(
        [FromBody] AskRequest request,
        CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(request.Question))
        {
            return BadRequest(
                "Question is required.");
        }

        var answer = await _searchService.AskAsync(
            request.Question,
            cancellationToken);

        return Ok(new
        {
            Question = request.Question,
            Answer = answer
        });
    }
}

public class AskRequest
{
    public string Question { get; set; } = string.Empty;
}

The application now has a simple endpoint:

POST /api/ai/ask
Content-Type: application/json

Request:

{
  "question": "What are the latest developments in .NET?"
}

The application sends the question to Amazon Bedrock. If the model determines that current information is required, it can use Web Search before generating the response.

For a production API, the response model should also preserve citation annotations rather than returning only the generated text.

Display Source Citations to Users

An AI application should not present search-grounded answers without making their sources available.

Amazon Bedrock returns URL citation annotations with the generated text. These annotations include information such as:

• Source title.
• Source URL.
• Start position in the answer.
• End position in the answer.

The application should extract and retain these annotations when processing the response.

For example, the client response could follow this structure:

{
  "answer": "The latest documentation describes several changes...",
  "sources": [
    {
      "title": "Official .NET Documentation",
      "url": "https://example.com/documentation"
    }
  ]
}

The URL in this example is illustrative. The application should use the actual citation values returned by Amazon Bedrock.

Preserving citations makes the application more transparent and allows users to verify the information independently.

Amazon's Web Search acceptable-use requirements also require applications to retain and display source citations and links when presenting outputs that incorporate Search Results to end users.

Security and Data Governance Considerations

Adding web search to an AI application introduces an important question: where does the retrieval process access information?

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

When it is false, Search uses the Amazon Bedrock web index and Fetch uses the Amazon Bedrock cache.

When it is true, Fetch can retrieve live external content after checking the cache, provided the calling identity has the required bedrock-websearch permission.

For applications that process sensitive business information, start with external_web_access set to false unless live external retrieval is an explicit requirement.

Also consider the following practices:

• Use IAM policies with only the permissions required by the application.
• Store credentials in AWS Secrets Manager or another secure configuration provider.
• Avoid logging API keys and sensitive user prompts.
• Configure request timeouts and cancellation.
• Handle throttling and service errors.
• Preserve source citations.
• Monitor Web Search activity through the appropriate AWS logging configuration.
• Review the latest Amazon Bedrock pricing before enabling the feature for a large user base.

Remember that the model's ability to search does not make every result accurate or authoritative. Applications should still validate important information, particularly when answers affect security, financial decisions, or production infrastructure.

When a Managed Search Service Is Not Enough

Amazon Bedrock Web Search is useful when an application needs general web information without managing its own search infrastructure.

However, it is not a replacement for every search architecture.

A custom search service may still be appropriate when an application requires:

• Searching private enterprise documents.
• Searching internal databases or knowledge bases.
• Custom ranking and relevance algorithms.
• Organization-specific content filtering.
• Specialized crawling and indexing.
• Full control over the retrieval pipeline.
• Custom search analytics and query processing.

For example, an application that searches internal engineering documentation should not assume that public web search can replace its private document retrieval system.

In such cases, a hybrid architecture can be useful. The application can retrieve internal information through its own retrieval service and use Web Search for relevant public information.

Summary

Adding web search to an AI application does not always require building a separate search service. Amazon Bedrock Web Search provides a managed capability that supported models can use through the Responses API.

By adding the Web Search tool to an existing model request, developers can avoid maintaining crawlers, search indexes, and custom search orchestration. The application can focus on its business logic, user experience, security, and response handling.

However, the integration still requires careful decisions about model and Region availability, IAM permissions, external web access, citations, and cost.

For applications that need current public information, managed Web Search can simplify the architecture significantly. For private enterprise data or specialized retrieval requirements, a custom search service may still be the better choice.