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

# You.com Search

> Built-in You.com search tools for AI agents - web search, news, content extraction, and images

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, search_web

agent = Agent(name="Researcher", tools=[search_web])
agent.start("Compare cloud GPU pricing for fine-tuning")
```

The user asks a research question; the agent uses You.com-backed search and returns a concise answer.

```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
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as You.com Search

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

<Note>
  **Prerequisites**

  * Python 3.10 or higher
  * PraisonAI Agents package installed
  * `youdotcom` package installed
  * `YDC_API_KEY` environment variable set
</Note>

You.com provides AI-powered search capabilities optimized for LLM applications. PraisonAI includes **built-in You.com tools** for easy integration.

## Quick Start

<Steps>
  <Step title="Install and set key">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonaiagents youdotcom
    export YDC_API_KEY=your_ydc_api_key
    ```
  </Step>

  <Step title="Search with agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, search_web

    agent = Agent(
        name="YouAgent",
        instructions="Search the web for the latest information.",
        tools=[search_web],
    )

    agent.start("Find recent news about space exploration")
    ```
  </Step>
</Steps>

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents youdotcom
```

## Setup

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export YDC_API_KEY=your_ydc_api_key
export OPENAI_API_KEY=your_openai_api_key
```

## Built-in You.com Tool

PraisonAI provides a built-in `ydc` tool that you can import directly:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import ydc

agent = Agent(
    name="SearchAgent",
    role="Web Researcher",
    goal="Find information on the web",
    tools=[ydc]
)

result = agent.start("What are the latest AI trends in 2025?")
print(result)
```

## Available Functions

| Function       | Description                         |
| -------------- | ----------------------------------- |
| `ydc`          | Web search (alias for `ydc_search`) |
| `ydc_search`   | Unified web + news search           |
| `ydc_contents` | Extract content from URLs           |
| `ydc_news`     | Live news search                    |
| `ydc_images`   | Image search                        |

## Basic Usage

### Simple Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ydc

# Simple search
results = ydc("Python programming best practices")
print(results)
```

### Search with Options

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ydc_search

results = ydc_search(
    query="AI trends 2025",
    count=10,                    # Max results per section
    freshness="week",            # "day", "week", "month", "year"
    country="US",                # ISO country code
    safesearch="moderate",       # "off", "moderate", "strict"
    livecrawl="web",             # "web", "news", "all"
    livecrawl_formats="markdown" # "html" or "markdown"
)

# Access web results
for r in results.get("results", {}).get("web", []):
    print(f"- {r['title']}: {r['url']}")

# Access news results
for r in results.get("results", {}).get("news", []):
    print(f"- {r['title']}: {r['url']}")
```

### Extract Content from URLs

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ydc_contents

content = ydc_contents(
    urls=["https://praison.ai/docs", "https://example.com"],
    format="markdown"  # "html" or "markdown"
)

for result in content.get("results", []):
    print(f"URL: {result['url']}")
    print(f"Content: {result.get('markdown', '')[:500]}...")
```

### Live News Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ydc_news

news = ydc_news(
    query="artificial intelligence",
    count=10
)

for article in news.get("news", {}).get("results", []):
    print(f"- {article['title']}")
    print(f"  Source: {article.get('source_name', 'Unknown')}")
```

### Image Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ydc_images

images = ydc_images(query="AI robots")

for img in images.get("images", {}).get("results", []):
    print(f"- {img['title']}: {img['image_url']}")
```

## With PraisonAI Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import ydc

agent = Agent(
    name="SearchAgent",
    role="Web Researcher",
    goal="Find and analyze information from the web",
    tools=[ydc]
)

result = agent.start("Research the latest developments in quantum computing")
print(result)
```

## Using YouTools Class

For more control, use the `YouTools` class directly:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import YouTools

# Initialize with custom API key (optional)
tools = YouTools(api_key="your_api_key")  # or uses YDC_API_KEY env var

# Search
results = tools.search("AI news", count=5)

# Get contents
content = tools.get_contents(["https://example.com"], format="markdown")

# Live news
news = tools.live_news("technology trends")

# Images
images = tools.images("AI robots")
```

## Search Parameters

| Parameter           | Type | Description                                   |
| ------------------- | ---- | --------------------------------------------- |
| `query`             | str  | Search query (supports operators)             |
| `count`             | int  | Max results per section (default 10, max 100) |
| `freshness`         | str  | "day", "week", "month", "year" or date range  |
| `country`           | str  | ISO country code (e.g., "US", "GB")           |
| `language`          | str  | BCP 47 language code (e.g., "EN", "JP")       |
| `offset`            | int  | Pagination offset (0-9)                       |
| `safesearch`        | str  | "off", "moderate", "strict"                   |
| `livecrawl`         | str  | "web", "news", or "all"                       |
| `livecrawl_formats` | str  | "html" or "markdown"                          |

## Search Operators

You.com supports advanced search operators:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ydc_search

# Site-specific search
results = ydc_search("site:github.com python AI")

# File type filter
results = ydc_search("machine learning filetype:pdf")

# Include/exclude terms
results = ydc_search("AI +ethics -bias")

# Boolean operators
results = ydc_search("(Python OR JavaScript) AND machine learning")
```

## Key Points

* **Simple function signature**: Tool accepts `query: str` and returns dict
* **Environment variable**: Set `YDC_API_KEY` before running
* **Unified results**: Web and news results in single response
* **LLM-ready snippets**: Pre-extracted relevant text excerpts

## Best Practices

<AccordionGroup>
  <Accordion title="Use AI snippets for summarized answers">
    You.com AI snippets provide pre-summarized answers - use them for quick, concise responses.
  </Accordion>

  <Accordion title="Set YDC_API_KEY for production">
    The free tier has low rate limits - set `YDC_API_KEY` for production workloads.
  </Accordion>

  <Accordion title="Combine with web search fallback">
    Use `search_web` with `providers=['you.com', 'duckduckgo']` for automatic fallback.
  </Accordion>

  <Accordion title="Use news mode for current events">
    Set `search_type='news'` for current events queries to get fresher results.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Custom Tools" icon="wrench" href="/docs/tools/custom">
    Build your own agent tools
  </Card>

  <Card title="Tools Overview" icon="toolbox" href="/docs/tools/tools">
    Browse PraisonAI tool documentation
  </Card>
</CardGroup>