OpenAI

Add Valyu search to an OpenAI Responses API app with OpenAIProvider. Your app runs the model and tool loop; Valyu returns content and source URLs to cite.

Add Valyu Search to an application using OpenAI’s Responses API with OpenAIProvider. Your application runs the model and tool loop; Valyu returns content and source URLs. To use Valyu inside ChatGPT, connect via MCP.

Installation

Install the Valyu and OpenAI packages:

pip install valyu openai

Set your API keys as environment variables:

export VALYU_API_KEY="your-valyu-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Basic usage

The OpenAI provider handles the integration with the Responses API:

from openai import OpenAI
from valyu import OpenAIProvider
# Initialize clients
openai_client = OpenAI()
provider = OpenAIProvider()

# Get Valyu tools
tools = provider.get_tools()

# Create a research request
messages = [
    {
        "role": "user",
        "content": "What are the latest developments in quantum computing? Write a summary of your findings."
    }
]

# Step 1: Call OpenAI Responses API with tools
response = openai_client.responses.create(
    model="gpt-5",
    input=messages,
    tools=tools,
)

# Step 2: Execute tool calls
tool_results = provider.execute_tool_calls(response)

# Step 3: Get final response with search results
if tool_results:
    final_response = openai_client.responses.create(
        model="gpt-5",
        previous_response_id=response.id,
        input=[{
            "type": "function_call_output",
            "call_id": result["tool_call_id"],
            "output": result["output"],
        } for result in tool_results],
    )
    print(final_response.output_text)
else:
    print(response.output_text)

This example performs one round of search and then asks the model to write a response. For an agent that can search repeatedly, add a bounded tool loop and handle tool errors explicitly. Model-provider charges are separate from Valyu usage.

How it works

The OpenAIProvider handles tool registration, execution, and conversation flow for you. The model decides when to search; the provider runs the call and feeds results back.

This uses OpenAI’s Responses API (responses.create()), not Chat Completions.

Search parameters the model can set

The model chooses these per query based on context:

• max_num_results - 1-20 for standard keys, up to 100 with a special API key
• included_sources / excluded_sources - target or exclude datasets
• category - guide search to a topic
• start_date / end_date - time-bounded searches
• relevance_threshold - filter by relevance (0-1)

Steer behaviour with a system prompt: cite sources, use natural-language queries (not operators). See the Prompting Guide.

OpenAIProvider reference

class OpenAIProvider:
    def __init__(self, valyu_api_key: Optional[str] = None): ...
    def get_tools(self) -> List[Dict]: ...
    def execute_tool_calls(self, response) -> List[Dict]: ...
    def build_conversation(self, input_messages, response, tool_results) -> List[Dict]: ...

Additional resources

OpenAI Responses API

Official OpenAI Responses API documentation

Valyu API Reference

Complete Valyu API documentation

Python SDK

Full Python SDK documentation

Get API Key

Sign up for $10 free credits ($20 with a company email)