> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.