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

# Perplexity Search

> Real-time web search with advanced filtering powered by Perplexity

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[Input] --> A[Agent]
    A --> T[Tool]
    T --> O[Output]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class A agent
    class U,O tool
    class T tool
```

# Perplexity Search Tool

Perplexity Search provides real-time web search with advanced filtering including domain, language, date range, and recency filters.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
npm install @perplexity-ai/ai-sdk
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
PERPLEXITY_API_KEY=your-perplexity-api-key
```

Get your API key from [Perplexity API Keys](https://www.perplexity.ai/account/api/keys).

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { Agent } from 'praisonai';
    import { perplexitySearch } from 'praisonai/tools';

    const agent = new Agent({
      name: 'Researcher',
      instructions: 'Search for current information using Perplexity.',
      tools: [perplexitySearch()],
    });

    const result = await agent.run('What are the latest AI developments?');
    console.log(result.text);
    ```
  </Step>

  <Step title="With Configuration">
    Adjust agent instructions, tool options, and provider settings for production — see the Configuration section below.
  </Step>
</Steps>

## Configuration Options

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { perplexitySearch } from 'praisonai/tools';

const searchTool = perplexitySearch({
  // Domain filter
  searchDomainFilter: ['arxiv.org', 'github.com'],
  
  // Language filter (ISO 639-1)
  language: 'en',
  
  // Date range
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  
  // Recency filter
  recency: 'week', // day, week, month, year
  
  // Number of results
  numResults: 10,
});
```

## Using with AI SDK Directly

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { generateText, stepCountIs } from 'ai';
import { perplexitySearch } from '@perplexity-ai/ai-sdk';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What are the latest AI developments? Use search to find current information.',
  tools: {
    search: perplexitySearch(),
  },
  stopWhen: stepCountIs(3),
});

console.log(text);
```

## Filter Options

### Domain Filter

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
perplexitySearch({
  searchDomainFilter: ['arxiv.org', 'nature.com', 'science.org'],
});
```

### Language Filter

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
perplexitySearch({
  language: 'en', // English
  // language: 'de', // German
  // language: 'fr', // French
});
```

### Recency Filter

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
perplexitySearch({
  recency: 'day',   // Last 24 hours
  // recency: 'week',  // Last 7 days
  // recency: 'month', // Last 30 days
  // recency: 'year',  // Last year
});
```

## Advanced Example

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';
import { perplexitySearch } from 'praisonai/tools';

const agent = new Agent({
  name: 'NewsAnalyst',
  instructions: `You are a news analyst. 
    Search for recent news and provide analysis with sources.`,
  tools: [
    perplexitySearch({
      recency: 'day',
      numResults: 5,
      searchDomainFilter: ['reuters.com', 'bbc.com', 'nytimes.com'],
    }),
  ],
});

const result = await agent.run('What are today\'s top tech news stories?');
console.log(result.text);
```

## Response Format

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
interface PerplexitySearchResult {
  results: Array<{
    title: string;
    url: string;
    snippet: string;
    publishedDate?: string;
  }>;
  query: string;
}
```

## Multi-Query Search

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';
import { perplexitySearch } from 'praisonai/tools';

const agent = new Agent({
  name: 'MultiSearcher',
  instructions: 'Search for multiple topics and synthesize information.',
  tools: [perplexitySearch()],
});

const result = await agent.run(`
  Search for:
  1. Latest developments in quantum computing
  2. Recent breakthroughs in AI
  3. New space exploration missions
  
  Provide a summary of each topic.
`);
```

## Error Handling

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { perplexitySearch } from 'praisonai/tools';

const tool = perplexitySearch();

try {
  const result = await tool.execute({ query: 'AI news' });
  console.log(result);
} catch (error) {
  if (error.message.includes('PERPLEXITY_API_KEY')) {
    console.error('Missing API key');
  } else {
    console.error('Search failed:', error.message);
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Guidelines">
    1. **Use recency filters** - Get the most current information
    2. **Filter by domain** - Focus on authoritative sources
    3. **Set language** - Get results in the desired language
    4. **Limit results** - Start with fewer results for faster responses
  </Accordion>
</AccordionGroup>

## Related Tools

* [Exa](/docs/js/tools/exa) - Semantic web search
* [Tavily](/docs/js/tools/tavily) - Web search and extraction
* [Firecrawl](/docs/js/tools/firecrawl) - Web scraping