{"id":47566447,"url":"https://github.com/valyuAI/valyu-agentcore","last_synced_at":"2026-04-14T01:00:33.032Z","repository":{"id":327566669,"uuid":"1109477736","full_name":"valyuAI/valyu-agentcore","owner":"valyuAI","description":"Valyu search tools for AWS Bedrock AgentCore and Strands Agents.","archived":false,"fork":false,"pushed_at":"2026-04-09T14:33:46.000Z","size":3279,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T16:25:52.844Z","etag":null,"topics":["agentcore","aws","aws-agentcore","search","valyu","web-search"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/valyu-agentcore/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valyuAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-03T21:28:23.000Z","updated_at":"2026-03-01T18:38:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/valyuAI/valyu-agentcore","commit_stats":null,"previous_names":["valyu-network/valyu-agentcore","valyuai/valyu-agentcore"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/valyuAI/valyu-agentcore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyuAI%2Fvalyu-agentcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyuAI%2Fvalyu-agentcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyuAI%2Fvalyu-agentcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyuAI%2Fvalyu-agentcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valyuAI","download_url":"https://codeload.github.com/valyuAI/valyu-agentcore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valyuAI%2Fvalyu-agentcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31777348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T00:11:49.126Z","status":"ssl_error","status_checked_at":"2026-04-14T00:10:29.837Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentcore","aws","aws-agentcore","search","valyu","web-search"],"created_at":"2026-03-30T06:00:24.600Z","updated_at":"2026-04-14T01:00:33.023Z","avatar_url":"https://github.com/valyuAI.png","language":"Python","funding_links":[],"categories":["Community Projects"],"sub_categories":["For PyPI Packages"],"readme":"# valyu-agentcore\n\n**Valyu search tools for AWS Bedrock AgentCore and Strands Agents.**\n\nAdd 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.\n\nValyu is the [leading search API for AI agents](https://www.valyu.ai/blogs/benchmarking-search-apis-for-ai-agents).\n\n![Valyu AgentCore Demo](assets/valyu-agentcore-demo.png)\n\n## Architecture\n\n![Architecture](assets/architecture/valyu-strands.png)\n\nThe 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.\n\n## Installation\n\n```bash\nuv init\n```\n\n```bash\nuv add valyu-agentcore\n```\n\nFor AgentCore Gateway support:\n```bash\nuv add valyu-agentcore[agentcore]\n```\n\n\n## Watch it in action!  \n\nHave a look at our Strands agent implementation live at [\"AWS Let's Build a Startup\" on YouTube](https://www.youtube.com/watch?v=tqQEGSay9aE\u0026t=30s). \n\u003ca href=\"https://www.youtube.com/watch?v=tqQEGSay9aE\u0026t=30s\" target=\"_blank\"\u003e![AWS Live Show](assets/letsbuildastartup-valyu.png)\u003c/a\u003e\n\n## Quick Start\n\n### Local Development\n\nUse Valyu tools directly with Strands Agents:\n\n```python\nfrom valyu_agentcore import webSearch, financeSearch, secSearch\nfrom strands import Agent\nfrom strands.models import BedrockModel\n\nagent = Agent(\n    model=BedrockModel(model_id=\"us.anthropic.claude-sonnet-4-20250514-v1:0\"),\n    tools=[webSearch(), financeSearch(), secSearch()],\n)\n\nresponse = agent(\"Summarize Tesla's latest 10-K risk factors\")\n```\n\nGet your API key at [platform.valyu.ai](https://platform.valyu.ai).  \n![Get your API Keys at platform.valyu.ai](assets/valyu-api.png)\n\n### Production: AgentCore Gateway + Runtime\n\n![Valyu AgentCore Architecture](architecture/valyu-agentcore-architecture.png)\n**Architecture Flow:**\n1. **Local Development**: Developers can build and tests agent locally with direct API calls to Valyu\n2. **Deploy Runtime**: Agent can be deployed to AgentCore Runtime via `agentcore launch`\n3. **Configure Gateway**: Developers can set up Gateway with Valyu MCP target\n4. **Authentication**: Runtime requests access token from Cognito\n5. **Token Response**: Cognito returns JWT access token\n6. **Tool Invocation**: Runtime calls Gateway with Bearer token\n7. **Request Forward**: Gateway forwards request to Valyu MCP target\n8. **API Query**: MCP target makes search query to Valyu API\n9. **Search Results**: Valyu API returns search results\n10. **MCP Response**: MCP target formats response back to Gateway\n11. **Final Results**: Gateway returns tool results to Runtime agent\n\n\n\nFor production, deploy to AWS with centralized tool access:\n\n```\nUser → AgentCore Runtime → AgentCore Gateway → Valyu MCP\n```\n\n```bash\n# 1. Set up Gateway with Valyu tools\ncd examples/gateway\nexport VALYU_API_KEY=your-key\npython setup_gateway.py\n\n# 2. Deploy agent to Runtime\ncp valyu_gateway_config.json ../runtime/\ncd ../runtime\nagentcore configure --entrypoint agent.py --non-interactive --name myagent\nagentcore launch\n\n# 3. Test it\nagentcore invoke '{\"prompt\": \"What is NVIDIA stock price?\"}'\n```\n\n**Why this architecture?**\n- Centralized secrets (API key in Gateway, not in code)\n- CloudTrail audit logging\n- OAuth authentication\n- Serverless scaling\n\nSee [examples/runtime/](examples/runtime/) for complete walkthrough.\n\n## Demo UI\n\nTry the interactive Streamlit demo to explore all features:\n\n```bash\n# Set your API key\nexport VALYU_API_KEY=your-key\n\n# Run the demo\nstreamlit run examples/app.py\n```\n\n**Features:**\n- **Local Mode** - Direct API calls to Valyu\n- **Gateway Mode** - Route through AWS AgentCore Gateway\n- **Runtime Mode** - Serverless execution on AWS\n\n**Agents:**\n- Single-tool agents: Web, Finance, SEC, Academic, Patents, Biomedical, Economics\n- Multi-tool agents: Financial Analyst, Research Assistant, Due Diligence\n\n**Views:**\n- **Chat** - Standard chat interface\n- **Compare** - Side-by-side comparison: with Valyu search vs without\n\n## Available Tools\n\n| Tool | Description | Best For |\n|------|-------------|----------|\n| `webSearch` | Web search with full page content | News, current events, general info |\n| `financeSearch` | Stock prices, earnings, market data | Financial analysis, market research |\n| `paperSearch` | Academic papers (arXiv, PubMed, journals) | Literature review, research |\n| `bioSearch` | Clinical trials, FDA labels, biomedical | Medical research, drug info |\n| `patentSearch` | USPTO patents and IP | Prior art, IP research |\n| `secSearch` | SEC filings (10-K, 10-Q, 8-K) | Company analysis, due diligence |\n| `economicsSearch` | BLS, FRED, World Bank data | Economic indicators, policy research |\n\n## Use Case Examples\n\nReal-world agent examples in [examples/use_cases/](examples/use_cases/):\n\n| Example | Description | Tools Used |\n|---------|-------------|------------|\n| [Financial Analyst](examples/use_cases/financial_analyst.py) | Investment research and analysis | SEC, finance, web |\n| [Research Assistant](examples/use_cases/research_assistant.py) | Academic literature review | papers, patents, web |\n| [Due Diligence](examples/use_cases/due_diligence.py) | M\u0026A and investment evaluation | All tools |\n\n```bash\n# Run financial analyst\npython examples/use_cases/financial_analyst.py \"Analyze NVIDIA's competitive position\"\n\n# Run research assistant\npython examples/use_cases/research_assistant.py \"transformer architecture improvements\"\n\n# Run due diligence\npython examples/use_cases/due_diligence.py \"Stripe\"\n```\n\nSee [examples/local/](examples/local/) for individual tool examples.\n\n## Tool Examples\n\n### webSearch\n\n```python\nfrom valyu_agentcore import webSearch\n\nagent = Agent(\n    model=BedrockModel(model_id=\"us.anthropic.claude-sonnet-4-20250514-v1:0\"),\n    tools=[webSearch()],\n)\nresponse = agent(\"Latest news on quantum computing breakthroughs\")\n```\n\n### financeSearch\n\n```python\nfrom valyu_agentcore import financeSearch\n\nagent = Agent(\n    model=BedrockModel(model_id=\"us.anthropic.claude-sonnet-4-20250514-v1:0\"),\n    tools=[financeSearch()],\n)\nresponse = agent(\"What is NVIDIA's current stock price and P/E ratio?\")\n```\n\n### secSearch\n\n```python\nfrom valyu_agentcore import secSearch\n\nagent = Agent(\n    model=BedrockModel(model_id=\"us.anthropic.claude-sonnet-4-20250514-v1:0\"),\n    tools=[secSearch()],\n)\nresponse = agent(\"Summarize the risk factors from Apple's latest 10-K\")\n```\n\n\n## Use All Tools\n\n```python\nfrom valyu_agentcore import ValyuTools\n\ntools = ValyuTools(max_num_results=5)\n\nagent = Agent(\n    model=BedrockModel(model_id=\"us.anthropic.claude-sonnet-4-20250514-v1:0\"),\n    tools=tools.all(),  # All 7 tools\n)\n\n# Or use tool groups:\n# tools.search_tools()     - All search tools\n# tools.financial_tools()  - finance, SEC, economics, company research\n# tools.research_tools()   - papers, bio, patents\n```\n\n## Configuration\n\nAll tools accept these options:\n\n```python\nfrom valyu_agentcore import webSearch\n\ntool = webSearch(\n    api_key=\"your-key\",           # Or use VALYU_API_KEY env var\n    max_num_results=10,           # Number of results (default: 5)\n    max_price=0.50,               # Max cost per query in dollars\n    relevance_threshold=0.7,      # Filter by quality (0-1)\n    excluded_sources=[\"reddit.com\"],  # Exclude specific domains\n)\n```\n\n## AgentCore Gateway\n\n### Add to Existing Gateway\n\nIf you already have an AgentCore Gateway:\n\n```python\nfrom valyu_agentcore.gateway import add_valyu_target\n\n# Add Valyu tools to your gateway\nresult = add_valyu_target(\n    gateway_id=\"your-gateway-id\",\n    region=\"us-east-1\",  # optional\n)\nprint(f\"Added target: {result['target_id']}\")\n```\n\nYour existing agents will now have access to all Valyu tools through the gateway.\n\n### Create New Gateway\n\nFor testing or new deployments:\n\n```python\nfrom valyu_agentcore.gateway import setup_valyu_gateway, GatewayAgent\n\n# Create gateway with Cognito auth (one-time)\nconfig = setup_valyu_gateway()\n\n# Use the agent\nwith GatewayAgent.from_config() as agent:\n    response = agent(\"Search for NVIDIA SEC filings\")\n    print(response)\n```\n\n### CloudFormation Deployment\n\nDeploy authentication infrastructure via CloudFormation:\n\n```bash\naws cloudformation create-stack \\\n  --stack-name valyu-gateway \\\n  --template-body file://cloudformation/valyu-gateway.yaml \\\n  --parameters ParameterKey=ValyuApiKey,ParameterValue=YOUR_KEY \\\n  --capabilities CAPABILITY_NAMED_IAM\n```\n\nThis creates Cognito, IAM, and logging infrastructure. Then create your gateway and add Valyu as a target. See [cloudformation/](cloudformation/) for full instructions.\n\n### IAM Policies\n\nReady-to-use IAM policies in [iam-policies/](iam-policies/):\n\n- **agentcore-user-policy.json** - Full gateway management access\n- **agentcore-invoke-only-policy.json** - Minimal invoke-only access\n\n### Manual Console Setup\n\nYou can also add Valyu via AWS Console:\n\n1. Go to **Amazon Bedrock** \u003e **AgentCore** \u003e **Gateways**\n2. Select your gateway \u003e **Add target**\n3. Configure:\n   - Name: `valyu-search`\n   - Type: MCP server\n   - Endpoint: `https://mcp.valyu.ai/mcp?valyuApiKey=YOUR_KEY`\n\n### Gateway Tools\n\nTools available through the gateway:\n\n| Gateway Tool | Description |\n|--------------|-------------|\n| `valyu_search` | Web search |\n| `valyu_academic_search` | Academic papers |\n| `valyu_financial_search` | Financial data |\n| `valyu_sec_search` | SEC filings |\n| `valyu_patents` | Patent search |\n| `valyu_contents` | URL content extraction |\n\nSee [examples/gateway/README.md](examples/gateway/README.md) for complete documentation.\n\n## Project Structure\n\n```\nvalyu-agentcore/\n├── valyu_agentcore/         # Core package\n│   ├── tools.py             # Strands Agent tools\n│   └── gateway.py           # AgentCore Gateway integration\n├── examples/\n│   ├── app.py               # Streamlit demo UI\n│   ├── local/               # Direct Strands usage\n│   ├── runtime/             # AgentCore Runtime deployment\n│   ├── gateway/             # AgentCore Gateway setup\n│   └── use_cases/           # Real-world agent examples\n├── assets/                  # Images and diagrams\n├── cloudformation/          # AWS CloudFormation templates\n└── iam-policies/            # IAM policy templates\n```\n\n## Create Custom Tools\n\nBuild your own tool using the Valyu API:\n\n```python\nimport os\nimport httpx\nfrom strands.tools import tool\n\n@tool\ndef my_custom_search(query: str) -\u003e dict:\n    \"\"\"Search for specific content.\"\"\"\n    response = httpx.post(\n        \"https://api.valyu.ai/v1/deepsearch\",\n        headers={\"x-api-key\": os.environ[\"VALYU_API_KEY\"]},\n        json={\n            \"query\": query,\n            \"search_type\": \"all\",\n            \"included_sources\": [\"your-sources\"],\n        },\n    )\n    return response.json()\n```\n\n## Links\n\n- [Valyu Platform](https://platform.valyu.ai) - Get API keys ($10 free credits)\n- [Valyu Documentation](https://docs.valyu.ai) - API docs\n- [Strands Agents](https://strandsagents.com) - Agent framework\n- [AWS Bedrock AgentCore](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore.html) - AWS docs\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FvalyuAI%2Fvalyu-agentcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FvalyuAI%2Fvalyu-agentcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FvalyuAI%2Fvalyu-agentcore/lists"}