Sofya

SofyaTools enable an Agent to search the web, extract page content, and run deep research using the Sofya 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.

uv pip install -U agno openai requests

export OPENAI_API_KEY=***
export SOFYA_API_KEY=***

Example

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

cookbook/91_tools/sofya_tools.py

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.

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.

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Prerequisites

Example

Toolkit Params

Toolkit Functions

Developer Resources

​Prerequisites

​Example

​Toolkit Params

​Toolkit Functions

​Developer Resources

Prerequisites

Example

Toolkit Params

Toolkit Functions

Developer Resources