---
source_url: "https://github.com/valyuAI/valyu-agentcore"
title: "GitHub - valyuAI/valyu-agentcore: Valyu search tools for AWS Bedrock AgentCore and Strands Agents. · GitHub"
mirrored_at: 2026-08-11T01:00:58.665Z
host: github.com
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/github.com/valyuAI/valyu-agentcore"
---

> **Original source:** https://github.com/valyuAI/valyu-agentcore

**Valyu search tools for AWS Bedrock AgentCore and Strands Agents.**

Add web search, SEC filings, financial data, academic papers, patents, and biomedical research to your [AWS Bedrock AgentCore](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore.html) and [Strands](https://strandsagents.com/) agents.

Valyu is the [leading search API for AI agents](https://www.valyu.ai/blogs/benchmarking-search-apis-for-ai-agents).

## Architecture

The agent runs locally (or on AWS Runtime) and uses Valyu tools to search across web, finance, SEC filings, academic papers, patents, and biomedical data. LLM inference is powered by Amazon Bedrock.

## Installation

uv init

uv add valyu-agentcore

For AgentCore Gateway support:

uv add valyu-agentcore\[agentcore\]

## Watch it in action!

Have a look at our Strands agent implementation live at ["AWS Let's Build a Startup" on YouTube](https://www.youtube.com/watch?v=tqQEGSay9aE&t=30s). 

## Quick Start

### Local Development

Use Valyu tools directly with Strands Agents:

from valyu\_agentcore import webSearch, financeSearch, secSearch
from strands import Agent
from strands.models import BedrockModel

agent \= Agent(
    model\=BedrockModel(model\_id\="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools\=\[webSearch(), financeSearch(), secSearch()\],
)

response \= agent("Summarize Tesla's latest 10-K risk factors")

Get your API key at [platform.valyu.ai](https://platform.valyu.ai/).  

### Production: AgentCore Gateway + Runtime

 **Architecture Flow:**

1.  **Local Development**: Developers can build and tests agent locally with direct API calls to Valyu
2.  **Deploy Runtime**: Agent can be deployed to AgentCore Runtime via `agentcore launch`
3.  **Configure Gateway**: Developers can set up Gateway with Valyu MCP target
4.  **Authentication**: Runtime requests access token from Cognito
5.  **Token Response**: Cognito returns JWT access token
6.  **Tool Invocation**: Runtime calls Gateway with Bearer token
7.  **Request Forward**: Gateway forwards request to Valyu MCP target
8.  **API Query**: MCP target makes search query to Valyu API
9.  **Search Results**: Valyu API returns search results
10.  **MCP Response**: MCP target formats response back to Gateway
11.  **Final Results**: Gateway returns tool results to Runtime agent

For production, deploy to AWS with centralized tool access:

```
User → AgentCore Runtime → AgentCore Gateway → Valyu MCP
```

# 1. Set up Gateway with Valyu tools
cd examples/gateway
export VALYU\_API\_KEY=your-key
python setup\_gateway.py

# 2. Deploy agent to Runtime
cp valyu\_gateway\_config.json ../runtime/
cd ../runtime
agentcore configure --entrypoint agent.py --non-interactive --name myagent
agentcore launch

# 3. Test it
agentcore invoke '{"prompt": "What is NVIDIA stock price?"}'

**Why this architecture?**

-   Centralized secrets (API key in Gateway, not in code)
-   CloudTrail audit logging
-   OAuth authentication
-   Serverless scaling

See [examples/runtime/](https://github.com/valyuAI/valyu-agentcore/blob/main/examples/runtime) for complete walkthrough.

## Demo UI

Try the interactive Streamlit demo to explore all features:

# Set your API key
export VALYU\_API\_KEY=your-key

# Run the demo
streamlit run examples/app.py

**Features:**

-   **Local Mode** - Direct API calls to Valyu
-   **Gateway Mode** - Route through AWS AgentCore Gateway
-   **Runtime Mode** - Serverless execution on AWS

**Agents:**

-   Single-tool agents: Web, Finance, SEC, Academic, Patents, Biomedical, Economics
-   Multi-tool agents: Financial Analyst, Research Assistant, Due Diligence

**Views:**

-   **Chat** - Standard chat interface
-   **Compare** - Side-by-side comparison: with Valyu search vs without

## Available Tools

Tool

Description

Best For

`webSearch`

Web search with full page content

News, current events, general info

`financeSearch`

Stock prices, earnings, market data

Financial analysis, market research

`paperSearch`

Academic papers (arXiv, PubMed, journals)

Literature review, research

`bioSearch`

Clinical trials, FDA labels, biomedical

Medical research, drug info

`patentSearch`

USPTO patents and IP

Prior art, IP research

`secSearch`

SEC filings (10-K, 10-Q, 8-K)

Company analysis, due diligence

`economicsSearch`

BLS, FRED, World Bank data

Economic indicators, policy research

## Use Case Examples

Real-world agent examples in [examples/use\_cases/](https://github.com/valyuAI/valyu-agentcore/blob/main/examples/use_cases):

Example

Description

Tools Used

[Financial Analyst](https://github.com/valyuAI/valyu-agentcore/blob/main/examples/use_cases/financial_analyst.py)

Investment research and analysis

SEC, finance, web

[Research Assistant](https://github.com/valyuAI/valyu-agentcore/blob/main/examples/use_cases/research_assistant.py)

Academic literature review

papers, patents, web

[Due Diligence](https://github.com/valyuAI/valyu-agentcore/blob/main/examples/use_cases/due_diligence.py)

M&A and investment evaluation

All tools

# Run financial analyst
python examples/use\_cases/financial\_analyst.py "Analyze NVIDIA's competitive position"

# Run research assistant
python examples/use\_cases/research\_assistant.py "transformer architecture improvements"

# Run due diligence
python examples/use\_cases/due\_diligence.py "Stripe"

See [examples/local/](https://github.com/valyuAI/valyu-agentcore/blob/main/examples/local) for individual tool examples.

## Tool Examples

### webSearch

from valyu\_agentcore import webSearch

agent \= Agent(
    model\=BedrockModel(model\_id\="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools\=\[webSearch()\],
)
response \= agent("Latest news on quantum computing breakthroughs")

### financeSearch

from valyu\_agentcore import financeSearch

agent \= Agent(
    model\=BedrockModel(model\_id\="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools\=\[financeSearch()\],
)
response \= agent("What is NVIDIA's current stock price and P/E ratio?")

### secSearch

from valyu\_agentcore import secSearch

agent \= Agent(
    model\=BedrockModel(model\_id\="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools\=\[secSearch()\],
)
response \= agent("Summarize the risk factors from Apple's latest 10-K")

## Use All Tools

from valyu\_agentcore import ValyuTools

tools \= ValyuTools(max\_num\_results\=5)

agent \= Agent(
    model\=BedrockModel(model\_id\="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools\=tools.all(),  \# All 7 tools
)

\# Or use tool groups:
\# tools.search\_tools()     - All search tools
\# tools.financial\_tools()  - finance, SEC, economics, company research
\# tools.research\_tools()   - papers, bio, patents

## Configuration

All tools accept these options:

from valyu\_agentcore import webSearch

tool \= webSearch(
    api\_key\="your-key",           \# Or use VALYU\_API\_KEY env var
    max\_num\_results\=10,           \# Number of results (default: 5)
    max\_price\=0.50,               \# Max cost per query in dollars
    relevance\_threshold\=0.7,      \# Filter by quality (0-1)
    excluded\_sources\=\["reddit.com"\],  \# Exclude specific domains
)

## AgentCore Gateway

### Add to Existing Gateway

If you already have an AgentCore Gateway:

from valyu\_agentcore.gateway import add\_valyu\_target

\# Add Valyu tools to your gateway
result \= add\_valyu\_target(
    gateway\_id\="your-gateway-id",
    region\="us-east-1",  \# optional
)
print(f"Added target: {result\['target\_id'\]}")

Your existing agents will now have access to all Valyu tools through the gateway.

### Create New Gateway

For testing or new deployments:

from valyu\_agentcore.gateway import setup\_valyu\_gateway, GatewayAgent

\# Create gateway with Cognito auth (one-time)
config \= setup\_valyu\_gateway()

\# Use the agent
with GatewayAgent.from\_config() as agent:
    response \= agent("Search for NVIDIA SEC filings")
    print(response)

### CloudFormation Deployment

Deploy authentication infrastructure via CloudFormation:

aws cloudformation create-stack \\
  --stack-name valyu-gateway \\
  --template-body file://cloudformation/valyu-gateway.yaml \\
  --parameters ParameterKey=ValyuApiKey,ParameterValue=YOUR\_KEY \\
  --capabilities CAPABILITY\_NAMED\_IAM

This creates Cognito, IAM, and logging infrastructure. Then create your gateway and add Valyu as a target. See [cloudformation/](https://github.com/valyuAI/valyu-agentcore/blob/main/cloudformation) for full instructions.

### IAM Policies

Ready-to-use IAM policies in [iam-policies/](https://github.com/valyuAI/valyu-agentcore/blob/main/iam-policies):

-   **agentcore-user-policy.json** - Full gateway management access
-   **agentcore-invoke-only-policy.json** - Minimal invoke-only access

### Manual Console Setup

You can also add Valyu via AWS Console:

1.  Go to **Amazon Bedrock** > **AgentCore** > **Gateways**
2.  Select your gateway > **Add target**
3.  Configure:
    -   Name: `valyu-search`
    -   Type: MCP server
    -   Endpoint: `https://mcp.valyu.ai/mcp?valyuApiKey=YOUR_KEY`

### Gateway Tools

Tools available through the gateway:

Gateway Tool

Description

`valyu_search`

Web search

`valyu_academic_search`

Academic papers

`valyu_financial_search`

Financial data

`valyu_sec_search`

SEC filings

`valyu_patents`

Patent search

`valyu_contents`

URL content extraction

See [examples/gateway/README.md](https://github.com/valyuAI/valyu-agentcore/blob/main/examples/gateway/README.md) for complete documentation.

## Project Structure

```
valyu-agentcore/
├── valyu_agentcore/         # Core package
│   ├── tools.py             # Strands Agent tools
│   └── gateway.py           # AgentCore Gateway integration
├── examples/
│   ├── app.py               # Streamlit demo UI
│   ├── local/               # Direct Strands usage
│   ├── runtime/             # AgentCore Runtime deployment
│   ├── gateway/             # AgentCore Gateway setup
│   └── use_cases/           # Real-world agent examples
├── assets/                  # Images and diagrams
├── cloudformation/          # AWS CloudFormation templates
└── iam-policies/            # IAM policy templates
```

## Create Custom Tools

Build your own tool using the Valyu API:

import os
import httpx
from strands.tools import tool

@tool
def my\_custom\_search(query: str) \-> dict:
    """Search for specific content."""
    response \= httpx.post(
        "https://api.valyu.ai/v1/deepsearch",
        headers\={"x-api-key": os.environ\["VALYU\_API\_KEY"\]},
        json\={
            "query": query,
            "search\_type": "all",
            "included\_sources": \["your-sources"\],
        },
    )
    return response.json()

## Links

-   [Valyu Platform](https://platform.valyu.ai/) - Get API keys ($10 free credits)
-   [Valyu Documentation](https://docs.valyu.ai/) - API docs
-   [Strands Agents](https://strandsagents.com/) - Agent framework
-   [AWS Bedrock AgentCore](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore.html) - AWS docs

## License

MIT