Hosted Tools

Use provider-hosted tools — web search, code interpreter, file search, hosted MCP — on any Agent.

Provider-hosted tools run on the provider (OpenAI, etc.) rather than in your process. Attach them to any Agent like a regular tool.

Quick Start

1. Simple: web search

   from praisonaiagents import Agent
   from praisonaiagents.tools import WebSearchTool
   
   agent = Agent(
       instructions="Research assistant",
       tools=[WebSearchTool()],
   )
   agent.start("What are the latest AI trends this year?")

2. With a vector store

   from praisonaiagents import Agent
   from praisonaiagents.tools import FileSearchTool
   
   agent = Agent(
       instructions="Research assistant",
       tools=[FileSearchTool(vector_store_ids=["vs_123"])],
   )
   agent.start("Summarise our internal design docs on retrieval.")

3. Combine hosted and local tools

   from praisonaiagents import Agent
   from praisonaiagents.tools import WebSearchTool
   
   def word_count(text: str) -> int:
       return len(text.split())
   
   agent = Agent(
       instructions="Research assistant",
       tools=[WebSearchTool(), word_count],
   )
   agent.start("Search for the latest LLM releases and count the words in your summary.")

How It Works

A hosted tool has no local callable — the provider executes it and returns the result.

Available Hosted Tools

Four factories, all re-exported from praisonaiagents.tools.

from praisonaiagents import Agent
from praisonaiagents.tools import (
    WebSearchTool,
    CodeInterpreterTool,
    FileSearchTool,
    HostedMCPTool,
)

agent = Agent(
    instructions="Research assistant",
    tools=[
        WebSearchTool(),
        CodeInterpreterTool(),
        FileSearchTool(vector_store_ids=["vs_123"]),
        HostedMCPTool(server_url="https://mcp.example.com"),
    ],
)
agent.start("Research the topic, run any calculations, and cite our internal docs.")

Configuration Options

All parameters are keyword-only.

WebSearchTool

CodeInterpreterTool

FileSearchTool

HostedMCPTool

When to Pick Which

Common Patterns

Mix a hosted tool with your own Python function in one Agent.

from praisonaiagents import Agent
from praisonaiagents.tools import WebSearchTool

def to_upper(text: str) -> str:
    return text.upper()

agent = Agent(
    instructions="Assistant",
    tools=[WebSearchTool(), to_upper],
)
agent.start("Search the news and shout the headline back at me.")

Search across multiple vector stores at once.

from praisonaiagents import Agent
from praisonaiagents.tools import FileSearchTool

agent = Agent(
    instructions="Assistant",
    tools=[FileSearchTool(vector_store_ids=["vs_docs", "vs_specs"], max_num_results=5)],
)
agent.start("Find the retention policy across both stores.")

Point a hosted MCP tool at a server the provider can reach.

from praisonaiagents import Agent
from praisonaiagents.tools import HostedMCPTool

agent = Agent(
    instructions="Assistant",
    tools=[HostedMCPTool(server_url="https://mcp.example.com", server_label="docs")],
)
agent.start("Use the connected MCP server to answer.")

Best Practices

Related