> ## 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.

# Claude Agent SDK Integration

> Use Valyu with the Claude Agent SDK to build AI agents with real-time search capabilities

## Overview

<Note>
  This is a <strong>community-maintained</strong> integration developed by{" "}
  <a href="https://github.com/GhouI/valyu-claude-agent-sdk">GhouI</a>. For
  official integrations, see{" "}
  <a href="/integrations/vercel-ai-sdk">Vercel AI SDK</a> or use the{" "}
  <a href="/api-reference/endpoint/search">Valyu API</a> directly.
</Note>

The Valyu Claude Agent SDK integration enables AI agents built with Anthropic's Claude Agent SDK to access real-time web data and specialized knowledge bases through powerful search capabilities.

This integration provides domain-specific search tools using the Model Context Protocol (MCP), making it easy to build intelligent agents that can search academic papers, financial data, patents, and more.

The integration includes search tools for:

* **Web Search**: Real-time information, news, and current events
* **Finance Search**: Stock prices, earnings reports, SEC filings, and financial metrics
* **Paper Search**: Academic research from arXiv and scholarly databases
* **Bio Search**: Biomedical literature, PubMed articles, and clinical trials
* **Patent Search**: Patent databases and prior art research
* **SEC Search**: Regulatory documents (10-K, 10-Q, 8-K filings)
* **Economics Search**: Labor statistics, Federal Reserve data, World Bank indicators
* **Company Research**: Comprehensive intelligence reports with synthesized data

## Installation

Clone the community-maintained repository and install dependencies:

<CodeGroup>
  ```bash git clone theme={null}
  git clone https://github.com/GhouI/valyu-claude-agent-sdk.git
  cd valyu-claude-agent-sdk
  ```

  ```bash npm theme={null}
  npm install --legacy-peer-deps
  ```

  ```bash yarn theme={null}
  yarn install --legacy-peer-deps
  ```

  ```bash pnpm theme={null}
  pnpm install --legacy-peer-deps
  ```
</CodeGroup>

<Note>
  The `--legacy-peer-deps` flag is required due to Zod version compatibility requirements.
</Note>

Configure credentials by adding your Valyu API key to a `.env` file:

```bash theme={null}
VALYU_API_KEY=your-valyu-api-key-here
```

The package automatically reads this environment variable.

<Card title="Free Credits" icon="gift" href="https://platform.valyu.ai" horizontal>
  Get your API key with \$10 credit from the Valyu Platform.
</Card>

## Basic Usage

### Web Search Example

Search for real-time information, news, and current events:

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuWebSearchServer } from "./tools/index.js";

async function webSearchExample() {
  for await (const message of query({
    prompt: "What are the latest developments in AI technology?",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-web-search__web_search"],
      mcpServers: {
        "valyu-web-search": valyuWebSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await webSearchExample();
```

### Finance Search Example

Access stock prices, earnings reports, and financial data:

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuFinanceSearchServer } from "./tools/index.js";

async function financeSearchExample() {
  for await (const message of query({
    prompt: "What is the current stock price of NVIDIA and their recent earnings?",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-finance-search__finance_search"],
      mcpServers: {
        "valyu-finance-search": valyuFinanceSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await financeSearchExample();
```

### Academic Paper Search Example

Search for scholarly articles and research publications:

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuPaperSearchServer } from "./tools/index.js";

async function paperSearchExample() {
  for await (const message of query({
    prompt: "Find recent papers on transformer architecture improvements",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-paper-search__paper_search"],
      mcpServers: {
        "valyu-paper-search": valyuPaperSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await paperSearchExample();
```

### Company Research Example

Get comprehensive intelligence reports about companies:

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuCompanyResearchServer } from "./tools/index.js";

async function companyResearchExample() {
  for await (const message of query({
    prompt: "Give me a comprehensive report on OpenAI including leadership, products, and funding",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-company-research__company_research"],
      mcpServers: {
        "valyu-company-research": valyuCompanyResearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await companyResearchExample();
```

## Advanced Configuration

### Custom Bio Search Parameters

The bioSearch tool supports advanced configuration for specialized searches:

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
import { createBioSearchServer } from "./tools/index.js";

async function bioSearchWithParamsExample() {
  const customBioSearchServer = createBioSearchServer({
    searchType: "proprietary", // Focus on academic datasets
    maxNumResults: 10,
    includedSources: ["pubmed", "clinicaltrials.gov"],
    maxPrice: 30.0,
    relevanceThreshold: 0.7,
    category: "biomedical",
  });

  for await (const message of query({
    prompt: "Find clinical trials for CRISPR gene therapy",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-bio-search__bio_search"],
      mcpServers: {
        "valyu-bio-search": customBioSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await bioSearchWithParamsExample();
```

### Multi-Tool Agent

Combine multiple search tools in a single agent:

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
import {
  valyuWebSearchServer,
  valyuFinanceSearchServer,
  valyuPaperSearchServer,
} from "./tools/index.js";

async function multiToolAgent() {
  for await (const message of query({
    prompt: "Research the impact of AI on financial markets, including recent news and academic papers",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: [
        "mcp__valyu-web-search__web_search",
        "mcp__valyu-finance-search__finance_search",
        "mcp__valyu-paper-search__paper_search",
      ],
      mcpServers: {
        "valyu-web-search": valyuWebSearchServer,
        "valyu-finance-search": valyuFinanceSearchServer,
        "valyu-paper-search": valyuPaperSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await multiToolAgent();
```

## All Available Search Tools

### 1. Web Search

Real-time information, news, and current events from the web.

```typescript theme={null}
import { valyuWebSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-web-search__web_search"
// Server key: "valyu-web-search"
```

### 2. Finance Search

Stock prices, earnings reports, SEC filings, and financial metrics.

```typescript theme={null}
import { valyuFinanceSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-finance-search__finance_search"
// Server key: "valyu-finance-search"
```

### 3. Paper Search

Academic research from arXiv, bioRxiv, medRxiv, and PubMed.

```typescript theme={null}
import { valyuPaperSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-paper-search__paper_search"
// Server key: "valyu-paper-search"
```

### 4. Bio Search

Biomedical literature, PubMed articles, and clinical trials.

```typescript theme={null}
import { valyuBioSearchServer, createBioSearchServer } from "./tools/index.js";

// Default server
// Tool name: "mcp__valyu-bio-search__bio_search"
// Server key: "valyu-bio-search"

// Or create custom server with parameters
const customServer = createBioSearchServer({ /* options */ });
```

### 5. Patent Search

Patent databases and prior art research.

```typescript theme={null}
import { valyuPatentSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-patent-search__patent_search"
// Server key: "valyu-patent-search"
```

### 6. SEC Search

SEC regulatory documents including 10-K, 10-Q, and 8-K filings.

```typescript theme={null}
import { valyuSecSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-sec-search__sec_search"
// Server key: "valyu-sec-search"
```

### 7. Economics Search

Labor statistics (BLS), Federal Reserve (FRED), and World Bank data.

```typescript theme={null}
import { valyuEconomicsSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-economics-search__economics_search"
// Server key: "valyu-economics-search"
```

### 8. Company Research

Comprehensive intelligence reports with synthesized data from multiple sources.

```typescript theme={null}
import { valyuCompanyResearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-company-research__company_research"
// Server key: "valyu-company-research"
```

## Best Practices

### 1. **Choose the Right Search Tool**

Use specialized search tools for better results:

```typescript theme={null}
// ❌ Bad: Using web search for financial data
const webResults = await query({
  prompt: "What is Apple's stock price?",
  options: {
    allowedTools: ["mcp__valyu-web-search__web_search"],
    mcpServers: { "valyu-web-search": valyuWebSearchServer },
  },
});

// ✅ Good: Using finance search for financial data
const financeResults = await query({
  prompt: "What is Apple's stock price?",
  options: {
    allowedTools: ["mcp__valyu-finance-search__finance_search"],
    mcpServers: { "valyu-finance-search": valyuFinanceSearchServer },
  },
});
```

### 2. **Cost Optimization**

Control costs using custom parameters:

```typescript theme={null}
import { createBioSearchServer } from "./tools/index.js";

// For quick lookups, limit results and set max price
const quickSearch = createBioSearchServer({
  maxNumResults: 3,
  maxPrice: 15.0,
  relevanceThreshold: 0.6,
});

// For comprehensive research, allow more results
const deepSearch = createBioSearchServer({
  maxNumResults: 20,
  maxPrice: 50.0,
  relevanceThreshold: 0.5,
});
```

### 3. **Error Handling**

Always wrap queries in try-catch blocks:

```typescript theme={null}
async function safeSearch() {
  try {
    for await (const message of query({
      prompt: "Search query here",
      options: {
        model: "claude-sonnet-4-5",
        allowedTools: ["mcp__valyu-web-search__web_search"],
        mcpServers: { "valyu-web-search": valyuWebSearchServer },
      },
    })) {
      if (message.type === "assistant") {
        const textContent = message.content
          .filter((block) => block.type === "text")
          .map((block) => block.text)
          .join("\n");
        console.log(textContent);
      }
    }
  } catch (error) {
    console.error("Search failed:", error);
    // Handle fallback or retry logic
  }
}
```

### 4. **Source Filtering**

Use `includedSources` to focus on specific data sources:

```typescript theme={null}
const academicBioSearch = createBioSearchServer({
  searchType: "proprietary",
  includedSources: ["pubmed", "clinicaltrials.gov"],
  maxNumResults: 10,
  relevanceThreshold: 0.7,
});
```

### 5. **Combining Multiple Tools**

Allow agents to use multiple search tools for comprehensive research:

```typescript theme={null}
// Comprehensive research combining web, finance, and company data
for await (const message of query({
  prompt: "Analyze Nvidia's market position and competitive landscape",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: [
      "mcp__valyu-web-search__web_search",
      "mcp__valyu-finance-search__finance_search",
      "mcp__valyu-company-research__company_research",
    ],
    mcpServers: {
      "valyu-web-search": valyuWebSearchServer,
      "valyu-finance-search": valyuFinanceSearchServer,
      "valyu-company-research": valyuCompanyResearchServer,
    },
  },
})) {
  // Handle messages
}
```

## API Reference

### Bio Search Configuration Parameters

The `createBioSearchServer()` function accepts the following configuration options:

* **`searchType`**: `"proprietary"` or `"web"` - Type of search to perform (default: `"proprietary"`)
* **`maxNumResults`**: Number - Maximum number of results to return (default: `10`)
* **`includedSources`**: Array of strings - Specific data sources to include (e.g., `["pubmed", "clinicaltrials.gov"]`)
* **`maxPrice`**: Number - Maximum cost in dollars (CPM-based pricing, default: `30.0`)
* **`relevanceThreshold`**: Number - Minimum relevance score (0.0-1.0, default: `0.5`)
* **`category`**: String - Search category to focus on (e.g., `"biomedical"`)

### Query Options

All search examples use the Claude Agent SDK `query()` function with the following structure:

```typescript theme={null}
query({
  prompt: string,              // Natural language query
  options: {
    model: string,             // Claude model (e.g., "claude-sonnet-4-5")
    allowedTools: string[],    // MCP tool identifiers
    mcpServers: {              // MCP server configuration
      [key: string]: MCPServer
    },
    cwd?: string,              // Current working directory (optional)
  },
})
```

### MCP Tool Identifiers

Each search tool has a specific identifier format:

```
mcp__valyu-{tool-name}__{tool_name}
```

Examples:

* `mcp__valyu-web-search__web_search`
* `mcp__valyu-finance-search__finance_search`
* `mcp__valyu-paper-search__paper_search`
* `mcp__valyu-bio-search__bio_search`
* `mcp__valyu-patent-search__patent_search`
* `mcp__valyu-sec-search__sec_search`
* `mcp__valyu-economics-search__economics_search`
* `mcp__valyu-company-research__company_research`

## Additional Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/GhouI/valyu-claude-agent-sdk">
    Community-maintained Claude Agent SDK integration source code
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/search">
    Complete Valyu API documentation
  </Card>

  <Card title="Claude Agent SDK" icon="robot" href="https://github.com/anthropics/claude-agent-sdk">
    Official Anthropic Claude Agent SDK
  </Card>

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

## Support

This is a community-maintained integration. For issues or contributions:

* **GitHub Issues**: [Report issues or request features](https://github.com/GhouI/valyu-claude-agent-sdk/issues)