The browser tool allows gpt-oss models to search for phrases, open specific pages, and find content on a page.
Warning: The provided SimpleBrowserTool is for educational purposes only. For production, implement your own backend by extending YouComBackend or ExaBackend.
To enable the tool, you must include its definition in the system message of your Harmony-formatted prompt using either .with_browser_tool() or .with_tools(browser_tool.tool_config).
Implementation Details:
- Backends: Supports
YouComBackend (default, requires YDC_API_KEY) and ExaBackend (set BROWSER_BACKEND=exa and provide EXA_API_KEY). - Context Management: The tool uses a scrollable text window to manage context.
- Caching: The tool caches requests to allow revisiting page parts without reloading. Important: Create a new browser instance for every request to ensure proper behavior.
import datetime
import os
from gpt_oss.tools.simple_browser import SimpleBrowserTool
from gpt_oss.tools.simple_browser.backend import ExaBackend, YouComBackend
from openai_harmony import SystemContent, Message, Conversation, Role, load_harmony_encoding, HarmonyEncodingName
encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
# Configure backend via environment variables
tool_backend = os.getenv("BROWSER_BACKEND", "youcom")
if tool_backend == "youcom":
backend = YouComBackend(source="web")
elif tool_backend == "exa":
backend = ExaBackend(source="web")
else:
raise ValueError(f"Invalid tool backend: {tool_backend}")
browser_tool = SimpleBrowserTool(backend=backend)
# Setup system message with tool enabled
system_message_content = SystemContent.new().with_conversation_start_date(
datetime.datetime.now().strftime("%Y-%m-%d")
)
# Enable the tool in the prompt
system_message_content = system_message_content.with_browser_tool()
system_message = Message.from_role_and_content(Role.SYSTEM, system_message_content)
# Construct conversation
messages = [system_message, Message.from_role_and_content(Role.USER, "What's the weather in SF?")]
conversation = Conversation.from_messages(messages)
# Render for inference
token_ids = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)
# ... (perform inference) ...
# Handle tool call in the response
# Assuming 'output_tokens' is the result from inference
parsed_messages = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT)
last_message = parsed_messages[-1]
if last_message.recipient.startswith("browser"):
response_messages = await browser_tool.process(last_message)
parsed_messages.extend(response_messages)
