Web Tools

The WebToolProvider provides web fetching and search capabilities.

WebToolProvider

stirrup.tools.web.WebToolProvider

WebToolProvider(
    *,
    timeout: float = 60 * 3,
    brave_api_key: str | None = None,
)

Bases: ToolProvider

Provides web tools (web_fetch, web_search) with managed HTTP client lifecycle.

WebToolProvider implements the Tool lifecycle protocol (has_lifecycle=True), so it can be used directly in Agent's tools list. It creates an httpx.AsyncClient on aenter and returns the web tools.

Usage as Tool in Agent (preferred): from stirrup.clients.chat_completions_client import ChatCompletionsClient

client = ChatCompletionsClient(model="gpt-5")
agent = Agent(
    client=client,
    name="assistant",
    tools=[LocalCodeExecToolProvider(), WebToolProvider(), CALCULATOR_TOOL],
)

async with agent.session(output_dir="./output") as session:
    await session.run("Search the web and fetch a page")

Standalone usage

async with WebToolProvider() as provider: tools = provider.get_tools()

Initialize WebToolProvider.

Parameters:

Name	Type	Description	Default
timeout	float	HTTP timeout in seconds (default: 180)	60 * 3
brave_api_key	str | None	Brave Search API key for web_search tool. If None, uses BRAVE_API_KEY environment variable. Web search is only available if API key is provided.	None

Source code in src/stirrup/tools/web.py

def __init__(
    self,
    *,
    timeout: float = 60 * 3,
    brave_api_key: str | None = None,
) -> None:
    """Initialize WebToolProvider.

    Args:
        timeout: HTTP timeout in seconds (default: 180)
        brave_api_key: Brave Search API key for web_search tool.
                      If None, uses BRAVE_API_KEY environment variable.
                      Web search is only available if API key is provided.
    """
    self._timeout = timeout
    self._brave_api_key = brave_api_key or os.getenv("BRAVE_API_KEY")
    self._client: httpx.AsyncClient | None = None

__aenter__ async

__aenter__() -> list[Tool[Any, Any]]

Enter async context: create HTTP client and return web tools.

Returns:

Type	Description
list[Tool[Any, Any]]	List of Tool objects (web_fetch, and web_search if API key available).

Source code in src/stirrup/tools/web.py

async def __aenter__(self) -> list[Tool[Any, Any]]:
    """Enter async context: create HTTP client and return web tools.

    Returns:
        List of Tool objects (web_fetch, and web_search if API key available).
    """
    self._client = httpx.AsyncClient(
        timeout=self._timeout,
        follow_redirects=True,
    )
    await self._client.__aenter__()
    return self.get_tools()

__aexit__ async

__aexit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None

Exit async context: close HTTP client.

Source code in src/stirrup/tools/web.py

async def __aexit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None:
    """Exit async context: close HTTP client."""
    if self._client:
        await self._client.__aexit__(exc_type, exc_val, exc_tb)
        self._client = None

Web Fetch Tool

Fetches a web page and returns its content as markdown.

stirrup.tools.web.FetchWebPageParams

Bases: BaseModel

Parameters for web page fetch tool.

url instance-attribute

url: Annotated[
    str,
    Field(
        description="Full HTTP or HTTPS URL of the web page to fetch and extract"
    ),
]

Web Search Tool

Searches the web using the Brave Search API.

Note

Requires BRAVE_API_KEY environment variable.

stirrup.tools.web.WebSearchParams

Bases: BaseModel

Parameters for web search tool.

query instance-attribute

query: Annotated[
    str,
    Field(
        description="Natural language search query for Brave Search (similar to Google search syntax)"
    ),
]