aws-samples / aws-samples/sample-multi-agent-orchestration-chat-on-agentcore
Add optional AgentCore Gateway Web Search built-in connector as a web search provider (region-gated; keep Tavily default)
- Dominant language
- TypeScript
- Stars
- 128
- Forks
- 12
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 4
Description
## Summary
Add the **Amazon Bedrock AgentCore Gateway "Web Search" built-in connector** (announced GA at AWS Summit New York 2026) as an optional, fully managed, MCP-based web search provider — an alternative to the existing Tavily-based web search tool.
Because the `web-search` connector is currently offered **only in `us-east-1`**, this is an opt-in enhancement. The existing Tavily tool stays the default, especially for deployments in other regions (e.g. `ap-northeast-1`).
## Background / Motivation
- The agent today performs web search through **Tavily**, wired as a Gateway target:
- Tool implementation: `packages/lambda-tools/tools/tavily-tools/` (`tavily-search`, `tavily-extract`, `tavily-crawl`)
- Target wiring: `packages/cdk/lib/agentcore-gateway-target-stack.ts`
- Config: `packages/cdk/config/environment-types.ts`, `packages/cdk/config/environments.ts`
- This requires managing a third-party API key, quotas, and outbound data flow to an external provider.
- **AgentCore Web Search Tool** is a managed, MCP-compliant connector attached to an AgentCore Gateway. The agent discovers it via `tools/list` and invokes it via `tools/call` with a natural-language query (≤ 200 characters). Queries are served entirely within AWS (no third-party search API, no outbound credentials to manage), and results include source titles, URLs, and publication dates.
- Benefits: removes API-key/quota management and keeps query data inside the AWS boundary, while reusing the same MCP plumbing the agent already uses.
## Constraints / Known limitations
- **Region**: the `web-search` connector is currently available **only in `us-east-1`**. The Gateway must reside in a region where the connector is offered; for `ap-northeast-1` it is not yet usable directly.
- **Acceptable use**: source citations/links returned with each result MUST be retained and displayed in any output surfaced to end users. Bulk extraction or building a competing index is prohibited.
## Requirements (EARS)
- The system shall provide a configuration option to select the active web search provider (`tavily` | `agentcore`), defaulting to `tavily`.
- Where the AgentCore Web Search provider is enabled, the agent shall expose a web search capability backed by the Gateway `web-search` built-in connector via MCP.
- When the agent invokes web search, the system shall send a natural-language query of at most 200 characters and shall return results that retain source titles, URLs, and publication dates.
- While the AgentCore Web Search provider is enabled, the system shall preserve and surface source citations in the agent's response.
- Where both Tavily and AgentCore Web Search are configured, the system shall activate exactly one provider so that no duplicate web search tools are exposed to the agent.
- If the deployment region does not offer the `web-search` connector, then the system shall fail deployment fast with an actionable message (or fall back to Tavily, per configuration) and shall not silently disable web search.
## Proposed approach (non-binding)
- **CDK**: in `packages/cdk/lib/agentcore-gateway-target-stack.ts`, add a Gateway target for the built-in connector (`connectorId: "web-search"`) using the L1 `AWS::BedrockAgentCore::GatewayTarget` (`CfnGatewayTarget`) resource. Add an opt-in config flag (e.g. `webSearchProvider`) in `packages/cdk/config/environment-types.ts` / `environments.ts`. Support an optional domain denylist.
- **IAM**: grant the Gateway Service Role the permissions required by the connector; ensure the CDK deploy role has `iam:CreateServiceLinkedRole` for AgentCore service-linked roles.
- **Agent**: the existing MCP path (`packages/agent/src/runtime/agent/mcp-clients-builder.ts` → `tools/list` discovery → `packages/agent/src/runtime/tools/mcp-converter.ts` → `packages/agent/src/runtime/agent/tools-builder.ts`) should surface the tool automatically. Verify tool naming in `packages/libs/tool-definitions/src/tool-names.ts`; expect minimal/no agent code change beyond config/tool-name wiring.
## Acceptance criteria
- [ ] A config option selects the web search provider, with `tavily` as the default.
- [ ] When AgentCore Web Search is enabled in a supported region, the agent performs a web search end-to-end and returns cited results.
- [ ] Citations (title / URL / publication date) are surfaced in the agent response.
- [ ] Exactly one web search tool is active at a time (no duplicate tool names exposed).
- [ ] Deploying with AgentCore Web Search enabled in an unsupported region fails fast with an actionable error (or falls back to Tavily per config).
- [ ] README / docs updated to describe the option and its region limitation.
## Out of scope
- Removing or replacing Tavily as the default provider.
- Amazon Bedrock Managed Knowledge Base integration (tracked in #55).
## References
- Announcing Web Search on Amazon Bedrock AgentCore (AWS News Blog): https://aws.amazon.com/blogs/aws/announcing-web-search-on-amazon-bedrock-agentcore-ground-your-ai-agents-in-current-accurate-web-knowledge/
- AgentCore Gateway — built-in connectors as targets (Developer Guide): https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connectors.html
- CloudFormation `AWS::BedrockAgentCore::GatewayTarget`: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-bedrockagentcore-gatewaytarget.html
Contributor guide
Research direction
Start with packages/cdk/lib/agentcore-gateway-target-stack.ts and the configuration files in packages/cdk/config/, then trace the existing MCP flow through mcp-clients-builder.ts, mcp-converter.ts, tools-builder.ts, and tool-names.ts. Done means selecting one provider with Tavily as the default, preserving citations, handling unsupported regions explicitly, and documenting the option and limitation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- ai, backend-api-design, cloud, infrastructure
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100