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

# Sofya

> Search the web for full page content, fetch pages and documents as clean markdown, and run cited multi-source research with SofyaTools.

**SofyaTools** enable an Agent to search the web, extract page content, and run deep research using the [Sofya](https://sofya.co) API. Search returns extracted page content instead of snippets, extract fetches URLs as clean markdown (including PDF and DOCX), and research returns a cited multi-source report.

## Prerequisites

The example requires Agno, the `openai` and `requests` packages, an OpenAI API key, and an API key from [Sofya](https://sofya.co).

```shell theme={null}
uv pip install -U agno openai requests
```

```shell theme={null}
export OPENAI_API_KEY=***
export SOFYA_API_KEY=***
```

## Example

The following agent will search the web with Sofya and print the response.

```python cookbook/91_tools/sofya_tools.py theme={null}
from agno.agent import Agent
from agno.tools.sofya import SofyaTools

agent = Agent(tools=[SofyaTools()])
agent.print_response("Search for recent developments in the Model Context Protocol", markdown=True)
```

Search is enabled by default. To also enable extraction and research, pass `all=True`, or turn on the individual tools with `enable_extract` and `enable_research`.

```python theme={null}
from agno.agent import Agent
from agno.tools.sofya import SofyaTools

agent = Agent(tools=[SofyaTools(all=True)])
agent.print_response("Write a short report on how AI agents use web search tools", markdown=True)
```

## Toolkit Params

| Parameter         | Type                           | Default      | Description                                                                                                |
| ----------------- | ------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------- |
| `api_key`         | `Optional[str]`                | `None`       | Sofya API key. If not provided, uses the `SOFYA_API_KEY` environment variable.                             |
| `base_url`        | `Optional[str]`                | `None`       | Sofya API base URL. If not provided, uses `SOFYA_BASE_URL` when set, otherwise `https://sofya.co`.         |
| `enable_search`   | `bool`                         | `True`       | Enable the `search_web` tool.                                                                              |
| `enable_extract`  | `bool`                         | `False`      | Enable the `extract_url_content` tool.                                                                     |
| `enable_research` | `bool`                         | `False`      | Enable the `research` tool.                                                                                |
| `all`             | `bool`                         | `False`      | Enable all available tools in the toolkit.                                                                 |
| `max_results`     | `int`                          | `5`          | Maximum number of search results to return. Clamped to the API range of 1-20.                              |
| `search_depth`    | `Literal['snippets', 'basic']` | `'basic'`    | Search depth. `snippets` returns result snippets, `basic` returns full page content.                       |
| `include_answer`  | `bool`                         | `True`       | Include an AI-generated answer summary in search results.                                                  |
| `format`          | `Literal['json', 'markdown']`  | `'markdown'` | Output format for search and research results. `json` returns raw data, `markdown` returns formatted text. |
| `timeout`         | `int`                          | `180`        | Request timeout in seconds.                                                                                |

## Toolkit Functions

| Function              | Description                                                                                                                                                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_web`          | Search the web for a `query` and return extracted page content. Takes an optional `max_results` that overrides the toolkit default for a single call.                                                                |
| `extract_url_content` | Fetch `urls` as clean markdown regardless of `format`, one section per URL. Accepts a single URL or a comma-separated list and keeps the first 10. Handles web pages, PDF, and DOCX. Calls Sofya's `fetch` endpoint. |
| `research`            | Decompose a `query` into sub-queries, read up to 20 sources, and return a report with citations.                                                                                                                     |

## Developer Resources

* [Tools](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/sofya.py)
* [Cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/sofya_tools.py)