> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Bedrock AgentCore

> Build production-ready AI agents with Valyu search tools on AWS infrastructure

<Info>
  **Enterprise-Ready AI Agents** — Combine Valyu's real-time search capabilities with AWS Bedrock AgentCore for secure, scalable, and auditable AI agent deployments.
</Info>

Build sophisticated AI agents that can search financial data, academic papers, SEC filings, patents, and more — all with enterprise-grade security, OAuth authentication, and CloudTrail audit logging.

<Frame>
  <img src="https://mintcdn.com/valyu/t__TplY33bNF1Xr1/images/valyu-agentcore-architecture.png?fit=max&auto=format&n=t__TplY33bNF1Xr1&q=85&s=ee9810786239029e5aadcb63faf86aff" alt="Valyu AgentCore Architecture" width="1636" height="1277" data-path="images/valyu-agentcore-architecture.png" />
</Frame>

## Why AWS Bedrock AgentCore + Valyu?

<CardGroup cols={2}>
  <Card title="7 Specialized Search Tools" icon="magnifying-glass">
    Financial data, SEC filings, academic papers, patents, biomedical research, web search, and economic indicators.
  </Card>

  <Card title="Enterprise Security" icon="shield-check">
    OAuth 2.0 authentication, Cognito integration, IAM policies, and CloudTrail audit logging.
  </Card>

  <Card title="Production Infrastructure" icon="server">
    Deploy to AWS with managed scaling, monitoring, and high availability.
  </Card>

  <Card title="Simple Integration" icon="plug">
    Works with Strands Agents out of the box. Add Valyu tools in one line of code.
  </Card>
</CardGroup>

<Card title="Get Started Free" icon="gift" href="https://platform.valyu.ai" horizontal>
  Sign up and get **\$10 free credits** — no credit card required. Start building in minutes.
</Card>

## Available Search Tools

| Tool                  | Best For                                  | Data Sources                                                 |
| --------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| **`webSearch`**       | News, current events, general information | Web pages, news sites                                        |
| **`financeSearch`**   | Stock prices, earnings, market analysis   | Stocks, forex, crypto, balance sheets                        |
| **`paperSearch`**     | Literature review, academic research      | arXiv, PubMed, bioRxiv, medRxiv                              |
| **`bioSearch`**       | Medical research, drug information        | PubMed, clinical trials, FDA labels                          |
| **`patentSearch`**    | Prior art, IP research                    | USPTO patents                                                |
| **`secSearch`**       | Company analysis, due diligence           | SEC filings (10-K, 10-Q, 8-K), insider transactions (Form 4) |
| **`economicsSearch`** | Economic indicators, policy research      | BLS, FRED, World Bank, US Spending                           |

## Quick Start

### Installation

```bash theme={null}
# For local development with Strands Agents
pip install "valyu-agentcore[strands]"

# For AWS AgentCore Gateway/Runtime deployment
pip install "valyu-agentcore[agentcore]"
```

### Environment Setup

```bash theme={null}
export VALYU_API_KEY="your-valyu-api-key"
export AWS_REGION="us-east-1"  # Optional, defaults to us-east-1
```

<Tip>
  Get your free API key at [platform.valyu.ai](https://platform.valyu.ai) — includes \$10 in credits with no credit card required.
</Tip>

### Your First Agent

Create an AI agent with web search capability in just a few lines:

```python theme={null}
from valyu_agentcore import webSearch
from strands import Agent
from strands.models import BedrockModel

# Create an agent with Valyu search
agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=[webSearch()],
)

# Ask anything
response = agent("What are the latest developments in quantum computing?")
print(response)
```

### Multi-Tool Agent

Combine multiple search tools for comprehensive research:

```python theme={null}
from valyu_agentcore import webSearch, financeSearch, secSearch, paperSearch
from strands import Agent
from strands.models import BedrockModel

# Financial research agent with multiple data sources
agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=[
        webSearch(),      # Current news and web content
        financeSearch(),  # Stock prices and financial data
        secSearch(),      # SEC filings and disclosures
        paperSearch(),    # Academic research
    ],
)

response = agent("Analyze NVIDIA's competitive position in the AI chip market")
print(response)
```

### Using Tool Groups

The `ValyuTools` wrapper provides convenient tool groupings:

```python theme={null}
from valyu_agentcore import ValyuTools
from strands import Agent
from strands.models import BedrockModel

tools = ValyuTools(max_num_results=5)

# Financial analysis agent
financial_agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=tools.financial_tools(),  # Includes: financeSearch, secSearch, economicsSearch
)

# Research agent
research_agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=tools.research_tools(),  # Includes: paperSearch, bioSearch, patentSearch
)

# All tools
complete_agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=tools.all(),  # All 7 search tools
)
```

## Deployment Options

Choose the deployment pattern that fits your needs:

<Frame>
  <img src="https://mintcdn.com/valyu/t__TplY33bNF1Xr1/images/valyu-strands.png?fit=max&auto=format&n=t__TplY33bNF1Xr1&q=85&s=4860d9fc49f13b812dfd28d7015b5866" alt="Valyu Strands Architecture" width="1870" height="1254" data-path="images/valyu-strands.png" />
</Frame>

### Option 1: Local Development

Best for prototyping and testing. Direct API calls with minimal setup.

```python theme={null}
from valyu_agentcore import webSearch
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()],
)
```

**Pros:** Fast setup, no AWS infrastructure needed
**Cons:** No centralized API key management, no audit logging

### Option 2: AgentCore Gateway (Recommended for Production)

Enterprise-grade deployment with OAuth authentication, centralized API key management, and CloudTrail logging.

```
Your Agent → AgentCore Gateway → Valyu MCP Server → Valyu API
                   ↓
             Cognito Auth
             CloudTrail Logs
             API Key Secrets
```

**Setup Gateway:**

```python theme={null}
from valyu_agentcore.gateway import setup_valyu_gateway, GatewayAgent

# One-time setup (creates Gateway + Cognito resources)
config = setup_valyu_gateway()
print(f"Gateway URL: {config.gateway_url}")

# Use the gateway-connected agent
with GatewayAgent.from_config() as agent:
    response = agent("Search for NVIDIA SEC filings")
    print(response)
```

**Add to Existing Gateway:**

```python theme={null}
from valyu_agentcore.gateway import add_valyu_target

# Add Valyu tools to your existing AgentCore Gateway
result = add_valyu_target(
    gateway_id="your-existing-gateway-id",
    region="us-east-1",
)
print(f"Target ID: {result['target_id']}")
```

**Pros:** Enterprise security, audit logging, centralized management
**Cons:** Requires AWS infrastructure setup

### Option 3: AgentCore Runtime

Full AWS-managed deployment with auto-scaling, streaming, and lifecycle management.

```bash theme={null}
# Deploy to AgentCore Runtime
cd examples/runtime
agentcore configure --entrypoint agent.py --non-interactive --name valyuagent
agentcore launch
agentcore invoke '{"prompt": "What is NVIDIA stock price?"}'
```

**Pros:** Fully managed, auto-scaling, production-ready
**Cons:** More complex setup, AWS costs

## Tool Configuration

All tools support these configuration options:

```python theme={null}
from valyu_agentcore import financeSearch

tool = financeSearch(
    api_key="val_xxx",           # Valyu API key (or use VALYU_API_KEY env var)
    search_type="all",           # "all", "web", "proprietary", or "news"
    max_num_results=10,          # Number of results (default: 5)
    max_price=0.50,              # Max cost per query in CPM
    relevance_threshold=0.7,     # Quality filter (0-1)
    excluded_sources=["example.com"],     # Domains to exclude
    included_sources=["sec.gov"],    # Restrict to specific domains
    category="quarterly earnings",       # Natural language search context
)
```

## Enterprise Use Cases

### Financial Analyst Agent

Build an investment research assistant that analyzes companies across multiple data sources:

```python theme={null}
from valyu_agentcore import financeSearch, secSearch, webSearch
from strands import Agent
from strands.models import BedrockModel

FINANCIAL_ANALYST_PROMPT = """You are a senior financial analyst at a top investment firm.

When analyzing a company:
1. Use financeSearch for stock prices, earnings, and financial metrics
2. Use secSearch for 10-K/10-Q filings, risk factors, and disclosures
3. Use webSearch for recent news and market sentiment

Structure your analysis with:
- Executive Summary
- Financial Performance
- Key Risks
- Competitive Position
- Investment Thesis

Be specific with numbers and cite your sources."""

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

response = agent("Analyze Apple's most recent quarterly earnings and outlook")
```

### Research Assistant Agent

Literature review and academic research across multiple databases:

```python theme={null}
from valyu_agentcore import paperSearch, patentSearch, webSearch
from strands import Agent
from strands.models import BedrockModel

RESEARCH_ASSISTANT_PROMPT = """You are a research assistant specializing in technical literature review.

When researching a topic:
1. Use paperSearch for peer-reviewed academic papers (arXiv, PubMed)
2. Use patentSearch for prior art and IP landscape
3. Use webSearch for recent developments and news

Organize findings by:
- Key Papers (with citations)
- State of the Art
- Patent Landscape
- Recent Developments

Always cite sources with URLs."""

agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    system_prompt=RESEARCH_ASSISTANT_PROMPT,
    tools=[paperSearch(), patentSearch(), webSearch()],
)

response = agent("Survey recent advances in transformer architecture efficiency")
```

### Due Diligence Agent

M\&A and investment due diligence across financial, legal, and market data:

```python theme={null}
from valyu_agentcore import secSearch, financeSearch, webSearch, patentSearch
from strands import Agent
from strands.models import BedrockModel

DUE_DILIGENCE_PROMPT = """You are conducting due diligence for a potential investment or acquisition.

Generate a comprehensive report covering:
1. Company Overview - Use webSearch for background
2. Financial Analysis - Use financeSearch for metrics
3. Regulatory Filings - Use secSearch for SEC documents
4. IP Portfolio - Use patentSearch for patents
5. Market Position - Use webSearch for competitive analysis
6. Risk Factors - Synthesize from all sources

Be thorough and flag any red flags or concerns."""

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

response = agent("Conduct due diligence on Anthropic for a potential investment")
```

## AWS Infrastructure

### CloudFormation Deployment

Deploy the complete infrastructure stack with one command:

```bash theme={null}
aws cloudformation create-stack \
  --stack-name valyu-agentcore \
  --template-body file://cloudformation/valyu-gateway.yaml \
  --parameters \
    ParameterKey=ValyuApiKey,ParameterValue=your-api-key \
    ParameterKey=GatewayName,ParameterValue=valyu-search-gateway \
  --capabilities CAPABILITY_IAM
```

**Resources Created:**

* IAM Role for Gateway
* Cognito User Pool with OAuth
* Cognito App Client (client\_credentials flow)
* Secrets Manager secret for API key
* CloudWatch Log Group (30-day retention)

### IAM Policies

**Full Access (for administrators):**

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:*",
        "cognito-idp:*"
      ],
      "Resource": "*"
    }
  ]
}
```

**Invoke-Only (for applications):**

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeGateway",
        "bedrock-agentcore:ListTools"
      ],
      "Resource": "*"
    }
  ]
}
```

## Security Best Practices

<Steps>
  <Step title="Use Environment Variables">
    Never hardcode API keys. Use `VALYU_API_KEY` environment variable or AWS Secrets Manager.
  </Step>

  <Step title="Enable CloudTrail">
    Monitor all API calls with CloudTrail for audit compliance and security monitoring.
  </Step>

  <Step title="Use OAuth for Production">
    Deploy with AgentCore Gateway for Cognito-based authentication in production environments.
  </Step>

  <Step title="Apply Least Privilege">
    Use invoke-only IAM policies for applications that only need to call the gateway.
  </Step>

  <Step title="Rotate Credentials">
    Regularly rotate Valyu API keys and Cognito client secrets.
  </Step>
</Steps>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named 'strands'">
    Install with Strands support:

    ```bash theme={null}
    pip install "valyu-agentcore[strands]"
    ```
  </Accordion>

  <Accordion title="Gateway target sync taking too long">
    Gateway targets take \~2 minutes to sync. The `add_valyu_target()` function waits automatically. If it times out, check the Gateway status in the AWS console.
  </Accordion>

  <Accordion title="OAuth token errors">
    Ensure your Cognito client has the correct scope (`gateway-name/invoke`) and the client\_credentials grant type is enabled.
  </Accordion>

  <Accordion title="Bedrock model access">
    Ensure you have access to the Bedrock model in your AWS account. Request access in the AWS Bedrock console if needed.
  </Accordion>
</AccordionGroup>

## API Reference

### Tool Functions

| Function            | Description                             |
| ------------------- | --------------------------------------- |
| `webSearch()`       | General web and news search             |
| `financeSearch()`   | Financial data, stocks, crypto, forex   |
| `paperSearch()`     | Academic papers (arXiv, PubMed)         |
| `bioSearch()`       | Biomedical research and clinical trials |
| `patentSearch()`    | USPTO patent search                     |
| `secSearch()`       | SEC filings and disclosures             |
| `economicsSearch()` | Economic indicators and data            |

### ValyuTools Class

| Method                         | Returns                                   |
| ------------------------------ | ----------------------------------------- |
| `ValyuTools.all()`             | All 7 search tools                        |
| `ValyuTools.financial_tools()` | financeSearch, secSearch, economicsSearch |
| `ValyuTools.research_tools()`  | paperSearch, bioSearch, patentSearch      |

### Gateway Functions

| Function                     | Description                            |
| ---------------------------- | -------------------------------------- |
| `setup_valyu_gateway()`      | Create new Gateway + Cognito resources |
| `add_valyu_target()`         | Add Valyu to existing Gateway          |
| `cleanup_valyu_gateway()`    | Remove all created resources           |
| `GatewayAgent.from_config()` | Create agent from saved config         |

## Additional Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/valyuAI/valyu-agentcore">
    Source code, examples, and CloudFormation templates
  </Card>

  <Card title="AWS Bedrock AgentCore" icon="aws" href="https://aws.amazon.com/bedrock/agentcore/">
    Official AWS Bedrock AgentCore documentation
  </Card>

  <Card title="Strands Agents" icon="robot" href="https://strandsagents.com">
    Learn more about the Strands Agents framework
  </Card>

  <Card title="Get API Key" icon="key" href="https://platform.valyu.ai">
    Sign up for free \$10 credit — no credit card required
  </Card>
</CardGroup>

## Pricing

Valyu charges per query based on the data sources accessed. With AWS AgentCore, you pay:

* **Valyu API costs** — Per-query pricing based on data sources (see [Pricing](/pricing))
* **AWS costs** — AgentCore Gateway, Cognito, CloudWatch (standard AWS rates)

<Card title="Start Building Today" icon="rocket" href="https://platform.valyu.ai" horizontal>
  Get **\$10 free credits** with no credit card required. Deploy production-ready AI agents in minutes.
</Card>