AgentCore Web Answer: cited web search for AI agents

mkdir library-web-answer && cd library-web-answer
npm init -y
npm pkg set type=module
npm pkg set scripts.typecheck="tsc -p ." scripts.test="node --import tsx --test test/*.test.ts" scripts.ask="tsx scripts/ask.ts"
npm i @smithy/signature-v4 @aws-crypto/sha256-js @aws-sdk/credential-provider-node
npm i -D typescript tsx @types/node @types/aws-lambda
mkdir src test scripts

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "types": ["node", "aws-lambda"]
  },
  "include": ["src", "test", "scripts"]
}

# serverless.yml
service: library-web-answer
frameworkVersion: '4'

provider:
  name: aws
  runtime: nodejs22.x
  architecture: arm64
  region: us-east-1 # At launch, Web Answer is only available in N. Virginia
  memorySize: 512
  timeout: 28 # HTTP API waits at most 30 seconds
  environment:
    GATEWAY_URL: !GetAtt WebAnswerGateway.GatewayUrl
  iam:
    role:
      statements:
        - Effect: Allow
          Action: bedrock-agentcore:InvokeGateway
          Resource: !GetAtt WebAnswerGateway.GatewayArn

functions:
  ask:
    handler: src/handler.handler
    events:
      - httpApi:
          method: POST
          path: /ask

resources:
  Resources:
    # Role the Gateway uses to call Web Answer
    WebAnswerGatewayRole:
      Type: AWS::IAM::Role
      Properties:
        AssumeRolePolicyDocument:
          Version: '2012-10-17'
          Statement:
            - Effect: Allow
              Principal:
                Service: bedrock-agentcore.amazonaws.com
              Action: sts:AssumeRole
              Condition:
                StringEquals:
                  aws:SourceAccount: !Ref AWS::AccountId
                ArnLike:
                  aws:SourceArn: !Sub arn:aws:bedrock-agentcore:${AWS::Region}:${AWS::AccountId}:gateway/library-web-answer-*
        Policies:
          - PolicyName: invoke-web-answer
            PolicyDocument:
              Version: '2012-10-17'
              Statement:
                - Effect: Allow
                  Action: bedrock-agentcore:InvokeWebAnswer
                  Resource: !Sub arn:aws:bedrock-agentcore:${AWS::Region}:aws:tool/web-answer.v1

    WebAnswerGateway:
      Type: AWS::BedrockAgentCore::Gateway
      Properties:
        Name: library-web-answer
        ProtocolType: MCP
        AuthorizerType: AWS_IAM
        RoleArn: !GetAtt WebAnswerGatewayRole.Arn
        Description: Research assistant for the city library

    WebAnswerTarget:
      Type: AWS::BedrockAgentCore::GatewayTarget
      Properties:
        GatewayIdentifier: !GetAtt WebAnswerGateway.GatewayIdentifier
        Name: answers
        CredentialProviderConfigurations:
          - CredentialProviderType: GATEWAY_IAM_ROLE
        TargetConfiguration:
          Mcp:
            Connector:
              Source:
                ConnectorId: web-answer
              Configurations:
                - Name: WebAnswer
                  ParameterValues:
                    domainFilter:
                      include:
                        - wikipedia.org
                        - loc.gov
                        - britannica.com
                        - gutenberg.org

  Outputs:
    GatewayUrl:
      Value: !GetAtt WebAnswerGateway.GatewayUrl

// src/gateway-client.ts
// Minimal MCP client for an AgentCore Gateway with IAM authentication (SigV4).
import { SignatureV4 } from '@smithy/signature-v4';
import { Sha256 } from '@aws-crypto/sha256-js';
import { defaultProvider } from '@aws-sdk/credential-provider-node';

export class GatewayClient {
  private nextId = 1;
  private readonly signer: SignatureV4;

  constructor(private readonly gatewayUrl: string, region = process.env.AWS_REGION ?? 'us-east-1') {
    this.signer = new SignatureV4({ service: 'bedrock-agentcore', region, credentials: defaultProvider(), sha256: Sha256 });
  }

  async rpc<T = any>(method: string, params: Record<string, unknown> = {}): Promise<T> {
    const url = new URL(this.gatewayUrl);
    const body = JSON.stringify({ jsonrpc: '2.0', id: this.nextId++, method, params });
    const signed = await this.signer.sign({
      method: 'POST',
      protocol: url.protocol,
      hostname: url.hostname,
      path: url.pathname,
      headers: { host: url.hostname, 'content-type': 'application/json' },
      body,
    });
    const res = await fetch(url, { method: 'POST', headers: signed.headers, body, signal: AbortSignal.timeout(25_000) });
    if (!res.ok) throw new Error(`${method}: HTTP ${res.status} ${await res.text()}`);
    const json: any = await res.json();
    if (json.error) throw new Error(`${method}: ${JSON.stringify(json.error)}`);
    return json.result as T;
  }

  async listTools() {
    const result = await this.rpc<{ tools: { name: string; inputSchema?: any }[] }>('tools/list');
    return result.tools;
  }

  callTool(name: string, args: Record<string, unknown>) {
    return this.rpc('tools/call', { name, arguments: args });
  }
}

// src/web-answer.ts
// Pure functions around the Web Answer tool: build arguments, find the tool, parse the answer.

export interface AskOptions {
  includeDomains?: string[];
  excludeDomains?: string[];
  from?: string; // YYYY-MM-DD
  to?: string; // YYYY-MM-DD
  country?: string; // ISO 3166-1 alpha-2, e.g. "DE"
}

export interface McpTool {
  name: string;
  inputSchema?: { properties?: Record<string, unknown> };
}

export interface Source {
  number: number;
  url: string;
  domain?: string;
}

export interface WebAnswer {
  text: string;
  sources: Source[];
  latencyMs?: number;
}

const DATE = /^\d{4}-\d{2}-\d{2}$/;
const MAX_DOMAINS = 50;

function checkDomains(label: string, list?: string[]): string[] | undefined {
  if (!list || list.length === 0) return undefined;
  if (list.length > MAX_DOMAINS) throw new Error(`${label}: at most ${MAX_DOMAINS} domains allowed`);
  return list.map((d) => d.trim().toLowerCase());
}

export function buildArguments(question: string, options: AskOptions = {}): Record<string, unknown> {
  const query = question.trim();
  if (query.length === 0 || query.length > 30_000) {
    throw new Error('The question must be between 1 and 30,000 characters long');
  }
  const args: Record<string, unknown> = { query };

  const include = checkDomains('includeDomains', options.includeDomains);
  const exclude = checkDomains('excludeDomains', options.excludeDomains);
  const filters: Record<string, unknown> = {};
  if (include || exclude) {
    filters.domainFilter = { ...(include && { include }), ...(exclude && { exclude }) };
  }

  if (options.from || options.to) {
    for (const d of [options.from, options.to]) {
      if (d && !DATE.test(d)) throw new Error(`Please use YYYY-MM-DD for date ${d}`);
    }
    if (options.from && options.to && options.from > options.to) {
      throw new Error('from is after to');
    }
    filters.publishedDateFilter = {
      ...(options.from && { from: options.from }),
      ...(options.to && { to: options.to }),
    };
  }
  if (Object.keys(filters).length > 0) args.filters = filters;

  if (options.country) {
    if (!/^[A-Za-z]{2}$/.test(options.country)) throw new Error('country needs a country code such as DE');
    args.userLocation = { country: options.country.toUpperCase() };
  }
  return args;
}

// The tool name depends on the target name. The docs show two spellings,
// so we match the end of the name instead of the exact name.
export function findWebAnswerTool(tools: McpTool[]): McpTool {
  const tool = tools.find((t) => t.name.endsWith('WebAnswer'));
  if (!tool) throw new Error(`No Web Answer tool found. Available: ${tools.map((t) => t.name).join(', ')}`);
  return tool;
}

// Connector version 1.0.0 only knows "query". Filters need 1.1.0 or later.
export function supportsFilters(tool: McpTool): boolean {
  return Boolean(tool.inputSchema?.properties && 'filters' in tool.inputSchema.properties);
}

interface RawBlock {
  text: string;
  citations?: { url: string; domain?: string }[];
}

interface RawResult {
  isError?: boolean;
  content?: { type: string; text?: string }[];
  structuredContent?: { answer?: RawBlock[] };
  _meta?: { latencyMs?: number };
}

const MARKER = /\[\[(\d+)\]\(([^)\s]+)\)\]/g;

// Each block numbers its sources from 1. We merge all blocks,
// drop duplicate URLs and renumber the markers globally: [1], [2], ...
export function parseAnswer(result: RawResult): WebAnswer {
  if (result.isError) {
    throw new Error(`Web Answer returned an error: ${result.content?.[0]?.text ?? 'no text'}`);
  }
  const blocks = result.structuredContent?.answer;
  if (!blocks || blocks.length === 0) {
    return { text: result.content?.[0]?.text ?? '', sources: [], latencyMs: result._meta?.latencyMs };
  }

  const sources: Source[] = [];
  const numberFor = (url: string, domain?: string): number => {
    const known = sources.find((s) => s.url === url);
    if (known) return known.number;
    const source = { number: sources.length + 1, url, ...(domain && { domain }) };
    sources.push(source);
    return source.number;
  };

  const parts = blocks.map((block) =>
    block.text.replace(MARKER, (_match, n: string, url: string) => {
      const citation = block.citations?.[Number(n) - 1];
      return `[${numberFor(citation?.url ?? url, citation?.domain)}]`;
    }),
  );

  return { text: parts.join('\n\n'), sources, latencyMs: result._meta?.latencyMs };
}

export function formatWithSources(answer: WebAnswer): string {
  const list = answer.sources.map((s) => `[${s.number}] ${s.url}`).join('\n');
  return list ? `${answer.text}\n\nSources:\n${list}` : answer.text;
}

// src/handler.ts
// POST /ask { "question": "..." } -> answer with numbered sources
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { GatewayClient } from './gateway-client';
import { buildArguments, findWebAnswerTool, parseAnswer, supportsFilters, type McpTool } from './web-answer';

const client = new GatewayClient(process.env.GATEWAY_URL!);
let tool: McpTool | undefined; // looked up once per Lambda environment

const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
  statusCode,
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(body),
});

export async function handler(event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> {
  let question: string;
  try {
    question = JSON.parse(event.body ?? '{}').question ?? '';
  } catch {
    return json(400, { message: 'Body must be JSON' });
  }

  let args: Record<string, unknown>;
  try {
    // Per request: only sources from the last two years (the domain list lives on the target)
    const from = new Date(Date.now() - 2 * 365 * 24 * 3600 * 1000).toISOString().slice(0, 10);
    args = buildArguments(question, { from });
  } catch (err) {
    return json(400, { message: (err as Error).message });
  }

  try {
    tool ??= findWebAnswerTool(await client.listTools());
    if (!supportsFilters(tool)) delete args.filters; // Connector 1.0.0: query only
    const answer = parseAnswer(await client.callTool(tool.name, args));
    console.log(JSON.stringify({ msg: 'web-answer', latencyMs: answer.latencyMs, sources: answer.sources.length }));
    return json(200, answer);
  } catch (err) {
    console.error(err);
    return json(502, { message: 'Web Answer is currently unavailable' });
  }
}

// test/web-answer.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { buildArguments, findWebAnswerTool, parseAnswer, supportsFilters } from '../src/web-answer';

test('builds arguments with filters and country code', () => {
  const args = buildArguments('  What is Lambda SnapStart? ', {
    includeDomains: ['AWS.amazon.com'],
    from: '2026-01-01',
    country: 'de',
  });
  assert.deepEqual(args, {
    query: 'What is Lambda SnapStart?',
    filters: { domainFilter: { include: ['aws.amazon.com'] }, publishedDateFilter: { from: '2026-01-01' } },
    userLocation: { country: 'DE' },
  });
});

test('rejects empty questions and swapped dates', () => {
  assert.throws(() => buildArguments('   '), /between 1 and 30,000/);
  assert.throws(() => buildArguments('x', { from: '2026-05-01', to: '2026-01-01' }), /from is after to/);
  assert.throws(() => buildArguments('x', { from: '01.05.2026' }), /YYYY-MM-DD/);
});

test('finds the tool regardless of the name variant', () => {
  const search = { name: 'x_amz_bedrock_agentcore_search' };
  assert.equal(findWebAnswerTool([search, { name: 'answers___WebAnswer' }]).name, 'answers___WebAnswer');
  assert.equal(findWebAnswerTool([{ name: 'answers_WebAnswer_WebAnswer' }]).name, 'answers_WebAnswer_WebAnswer');
  assert.throws(() => findWebAnswerTool([search]), /No Web Answer tool/);
});

test('detects whether the connector supports filters', () => {
  assert.equal(supportsFilters({ name: 'a', inputSchema: { properties: { query: {}, filters: {} } } }), true);
  assert.equal(supportsFilters({ name: 'a', inputSchema: { properties: { query: {} } } }), false);
});

test('merges blocks and numbers sources globally', () => {
  const answer = parseAnswer({
    isError: false,
    structuredContent: {
      answer: [
        {
          text: 'Libraries lend books [[1](https://a.example/x)] and e-books [[2](https://b.example/y)].',
          citations: [{ url: 'https://a.example/x', domain: 'a.example' }, { url: 'https://b.example/y' }],
        },
        {
          text: 'Fees vary [[1](https://c.example/z)], see also [[2](https://a.example/x)].',
          citations: [{ url: 'https://c.example/z' }, { url: 'https://a.example/x' }],
        },
      ],
    },
    _meta: { latencyMs: 4800 },
  });
  assert.equal(answer.text, 'Libraries lend books [1] and e-books [2].\n\nFees vary [3], see also [1].');
  assert.deepEqual(answer.sources.map((s) => s.url), ['https://a.example/x', 'https://b.example/y', 'https://c.example/z']);
  assert.equal(answer.latencyMs, 4800);
});

test('throws on isError with the tool message', () => {
  assert.throws(
    () => parseAnswer({ isError: true, content: [{ type: 'text', text: 'ValidationException: include lists do not overlap' }] }),
    /include lists do not overlap/,
  );
});

# Tests and type check locally
npm test
npm run typecheck

# Deploy to us-east-1
serverless deploy

# Check the target status (IDs from the AWS console or via list-gateways/list-gateway-targets)
aws bedrock-agentcore-control list-gateways --region us-east-1
aws bedrock-agentcore-control list-gateway-targets --gateway-identifier <GATEWAY_ID> --region us-east-1

# First question through the HTTP API
curl -s -X POST https://<api-id>.execute-api.us-east-1.amazonaws.com/ask \
  -H 'content-type: application/json' \
  -d '{"question":"When did the Library of Congress start digitizing newspapers?"}'

// scripts/ask.ts
// Usage: GATEWAY_URL=... npx tsx scripts/ask.ts "What changed in the latest Node.js LTS release?"
import { GatewayClient } from '../src/gateway-client';
import { buildArguments, findWebAnswerTool, formatWithSources, parseAnswer, supportsFilters } from '../src/web-answer';

const url = process.env.GATEWAY_URL;
if (!url) throw new Error('Please set GATEWAY_URL (output after the deploy)');
const question = process.argv.slice(2).join(' ');

const client = new GatewayClient(url);
const tools = await client.listTools();
const tool = findWebAnswerTool(tools);
console.log(`Tool: ${tool.name} (filters ${supportsFilters(tool) ? 'available' : 'not available'})`);

const started = Date.now();
const answer = parseAnswer(await client.callTool(tool.name, buildArguments(question, { country: 'DE' })));
console.log(formatWithSources(answer));
console.log(`\nTotal time: ${Date.now() - started} ms, of which server-side: ${answer.latencyMs ?? '?'} ms`);