Skip to main content
Best for: building Valyu into your product / agents. Add real-time search to an OpenAI app via Valyu’s provider.
The OpenAIProvider exposes Valyu search as a tool through OpenAI’s Responses API, so your agents can pull real-time information from academic papers, news, financial data, and authoritative sources.

Paste into your AI assistant to wire Valyu search into an OpenAI app.

Open in Cursor

​
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"

Free Credits

Get your API key with $10 free credits ($20 with a work email) from the Valyu Platform.

​
Basic Usage

The OpenAI provider handles the integration with the Responses API: 
from openai import OpenAI
from valyu import OpenAIProvider
from dotenv import load_dotenv

load_dotenv()

# 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:
    updated_messages = provider.build_conversation(messages, response, tool_results)
    final_response = openai_client.responses.create(
        model="gpt-5",
        input=updated_messages,
        tools=tools,
    )
    print(final_response.output_text)
else:
    print(response.output_text)

​
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.
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.
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 work email)