Implementation:Openai Openai agents python WebSearchTool Filters Pattern

Knowledge Sources	Openai_Openai_agents_python
Domains	Tool_Integration, Web_Search, Information_Retrieval
Last Updated	2026-02-11 00:00 GMT

Overview

Demonstrates advanced WebSearchTool configuration with domain filtering, search context size control, reasoning effort tuning, and extraction of source URLs from web search results.

Description

This implementation shows how to configure the WebSearchTool with fine-grained control over search behavior. The Filters class from openai.types.responses.web_search_tool allows restricting search results to specific domains via the allowed_domains parameter. In this example, searches are scoped to openai.com, developer.openai.com, platform.openai.com, and help.openai.com. The search_context_size parameter controls how much context from search results is passed to the model, set to "medium" in this example.

The agent's ModelSettings is configured with Reasoning(effort="low") to reduce reasoning token usage and verbosity="low" for concise responses. The response_include parameter is set to ["web_search_call.action.sources"] to ensure that source information is included in the response items, enabling downstream extraction of the URLs that informed the agent's answer.

Source URL extraction is performed by iterating over result.new_items, filtering for items with type == "tool_call_item" and raw item type "web_search_call", then accessing the action.sources list. Each source object has a url attribute. A helper function _get_field provides compatibility with both dict-like and attribute-based access patterns.

Usage

Use this pattern when building agents that need to search the web with domain restrictions, such as knowledge base assistants scoped to specific documentation sites, brand-safe search implementations, or research assistants that should only cite authoritative sources. The source extraction capability is useful for building citations, references, or audit trails.

Code Reference

Source Location

• Repository: Openai_Openai_agents_python
• File: examples/tools/web_search_filters.py
• Lines: 1-84

Signature

WebSearchTool(
    filters=Filters(
        allowed_domains=[
            "openai.com",
            "developer.openai.com",
            "platform.openai.com",
            "help.openai.com",
        ],
    ),
    search_context_size="medium",
)

Import

from openai.types.responses.web_search_tool import Filters
from openai.types.shared.reasoning import Reasoning

from agents import Agent, ModelSettings, Runner, WebSearchTool, trace

I/O Contract

Inputs

Name	Type	Required	Description
filters	Filters	No	Domain filtering configuration with allowed_domains list to restrict search scope.
search_context_size	str	No	Amount of search context passed to the model; one of "low", "medium", or "high".
model_settings.reasoning	Reasoning	No	Reasoning configuration with effort level to control token usage.
model_settings.verbosity	str	No	Response verbosity setting (e.g., "low").
model_settings.response_include	list[str]	No	List of response components to include; set to ["web_search_call.action.sources"] to enable source extraction.
prompt	str	Yes (at Runner.run)	The search query passed to the agent.

Outputs

Name	Type	Description
result.final_output	str	The agent's text response summarizing the search results.
result.new_items	list[RunItem]	Run items including web_search_call items with source information.
source.url	str	URL of each source that contributed to the search results.

Usage Examples

Domain-Filtered Web Search with Source Extraction

import asyncio
from collections.abc import Mapping
from datetime import datetime
from typing import Any

from openai.types.responses.web_search_tool import Filters
from openai.types.shared.reasoning import Reasoning

from agents import Agent, ModelSettings, Runner, WebSearchTool, trace


def _get_field(obj: Any, key: str) -> Any:
    if isinstance(obj, Mapping):
        return obj.get(key)
    return getattr(obj, key, None)


async def main():
    agent = Agent(
        name="WebOAI website searcher",
        model="gpt-5-nano",
        instructions="You are a helpful agent that can search openai.com resources.",
        tools=[
            WebSearchTool(
                filters=Filters(
                    allowed_domains=[
                        "openai.com",
                        "developer.openai.com",
                        "platform.openai.com",
                        "help.openai.com",
                    ],
                ),
                search_context_size="medium",
            )
        ],
        model_settings=ModelSettings(
            reasoning=Reasoning(effort="low"),
            verbosity="low",
            response_include=["web_search_call.action.sources"],
        ),
    )

    with trace("Web search example"):
        today = datetime.now().strftime("%Y-%m-%d")
        query = f"Summarize the latest OpenAI Platform updates (today is {today})."
        result = await Runner.run(agent, query)

        # Extract source URLs
        for item in result.new_items:
            if item.type != "tool_call_item":
                continue
            raw_call = item.raw_item
            if _get_field(raw_call, "type") != "web_search_call":
                continue
            action = _get_field(raw_call, "action")
            sources = _get_field(action, "sources") if action else None
            if sources:
                for source in sources:
                    url = getattr(source, "url", None)
                    if url is None and isinstance(source, Mapping):
                        url = source.get("url")
                    if url:
                        print(f"Source: {url}")

        print(result.final_output)

asyncio.run(main())

Related Pages

• Environment:Openai_Openai_agents_python_OpenAI_API_Credentials