Hosted Tools in OpenAI Agents SDK: Web Search, Code Interpreter, and File Search

What Are Hosted Tools?

The OpenAI Agents SDK ships with a set of hosted tools — capabilities that run on OpenAI's infrastructure rather than in your local Python process. This means your agent can search the web, execute code, parse files, and generate images without you writing any implementation logic. You simply attach the tool and the SDK handles the rest.

There are four hosted tools available:

• WebSearchTool — real-time internet search
• CodeInterpreterTool — sandboxed Python code execution
• FileSearchTool — semantic search across uploaded documents
• ImageGenerationTool — generate images from text descriptions

Let's walk through each one with working code examples.

WebSearchTool: Real-Time Internet Access

The WebSearchTool gives your agent the ability to search the internet and retrieve current information. This is essential for agents that need up-to-date data — stock prices, weather, recent news, or documentation that changes frequently.

flowchart LR
    INPUT(["User input"])
    AGENT["Agent<br/>name plus instructions"]
    HAND{"Handoff to<br/>another agent?"}
    SUB["Sub-agent<br/>specialist"]
    GUARD{"Guardrail<br/>passed?"}
    TOOL["Tool call"]
    SDK[("Tracing<br/>OpenAI dashboard")]
    OUT(["Final output"])
    INPUT --> AGENT --> HAND
    HAND -->|Yes| SUB --> GUARD
    HAND -->|No| GUARD
    GUARD -->|Yes| TOOL --> AGENT
    GUARD -->|Block| OUT
    AGENT --> OUT
    AGENT --> SDK
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style SDK fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff

from agents import Agent, Runner, WebSearchTool

agent = Agent(
    name="Research Assistant",
    instructions="You are a research assistant. Use web search to find current, accurate information. Always cite your sources.",
    tools=[WebSearchTool()],
)

result = Runner.run_sync(agent, "What were the top AI announcements this week?")
print(result.final_output)

You can customize the search behavior with parameters:

web_tool = WebSearchTool(
    search_context_size="high",  # "low", "medium", or "high"
    user_location={
        "type": "approximate",
        "city": "San Francisco",
        "region": "California",
        "country": "US",
    },
)

agent = Agent(
    name="Local Guide",
    instructions="You help users find local events and restaurants.",
    tools=[web_tool],
)

The search_context_size parameter controls how much context the model receives from search results. Use "high" when the agent needs detailed information and "low" when you want faster, more concise responses.

CodeInterpreterTool: Sandboxed Code Execution

The CodeInterpreterTool lets your agent write and execute Python code in a secure sandbox on OpenAI's servers. This is powerful for data analysis, math, chart generation, and any task that benefits from computation.

from agents import Agent, Runner, CodeInterpreterTool

agent = Agent(
    name="Data Analyst",
    instructions="You are a data analyst. Use the code interpreter to perform calculations, analyze data, and generate charts when helpful.",
    tools=[CodeInterpreterTool()],
)

result = Runner.run_sync(
    agent,
    "Calculate the compound interest on $10,000 at 7% annually over 20 years. Show the growth year by year.",
)
print(result.final_output)

The sandbox comes with common Python libraries pre-installed (numpy, pandas, matplotlib, etc.), so your agent can do serious data work without any setup on your end.

FileSearchTool: Semantic Document Search

The FileSearchTool enables your agent to search through uploaded documents using semantic similarity. It requires a vector store — a collection of files that OpenAI indexes for retrieval.

from agents import Agent, Runner, FileSearchTool

agent = Agent(
    name="Document Assistant",
    instructions="You answer questions based on the uploaded documents. Always reference the specific document and section where you found the information.",
    tools=[
        FileSearchTool(
            vector_store_ids=["vs_abc123"],  # your vector store ID
            max_num_results=5,
        )
    ],
)

result = Runner.run_sync(agent, "What does the Q4 report say about revenue growth?")
print(result.final_output)

You create vector stores through the OpenAI API:

from openai import OpenAI

client = OpenAI()

# Create a vector store
vector_store = client.vector_stores.create(name="Company Documents")

# Upload files to it
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id="file-abc123",  # previously uploaded file ID
)

The max_num_results parameter controls how many document chunks the agent receives. More results give better coverage but increase token usage.

ImageGenerationTool: Text-to-Image

The ImageGenerationTool lets your agent generate images from text descriptions using DALL-E or other OpenAI image models.

from agents import Agent, Runner, ImageGenerationTool

agent = Agent(
    name="Creative Assistant",
    instructions="You help users create visual content. Generate images when the user describes what they want to see.",
    tools=[ImageGenerationTool()],
)

result = Runner.run_sync(
    agent,
    "Create an illustration of a robot reading a book in a cozy library.",
)
print(result.final_output)

Combining Multiple Hosted Tools

The real power comes from combining tools. An agent can search the web, analyze data with code, and reference documents — all in a single conversation:

agent = Agent(
    name="Full-Stack Researcher",
    instructions="You are an advanced research assistant with access to web search, code execution, and document analysis. Use the right tool for each subtask.",
    tools=[
        WebSearchTool(),
        CodeInterpreterTool(),
        FileSearchTool(vector_store_ids=["vs_abc123"]),
    ],
)

The agent's model decides which tool to call based on the user's request and the instructions you provide. You do not need to write routing logic — the LLM handles tool selection automatically.

When to Use Hosted vs. Custom Tools

Use hosted tools when the built-in capability matches your needs. They are maintained by OpenAI, require zero implementation, and run on scalable infrastructure. Use custom function tools (covered in the next post) when you need to call your own APIs, query your database, or implement domain-specific logic that hosted tools cannot cover.