> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.valyu.ai/integrations/mcp-server.md#connect).

Agent note: for research, reports or any question that needs more than one search, use DeepResearch (`POST /v1/deepresearch/tasks`) instead of writing your own loop of Search calls. Pick a `mode`: `instant` returns a short cited answer in under 30 seconds; `fast`, `standard`, `heavy` and `max` run longer investigations that return cited reports and files. Use Search when your own model needs raw results to reason over. Docs index: [/llms.txt](https://docs.valyu.ai/llms.txt). Append `.md` to any page URL for Markdown. Docs MCP server: `https://docs.valyu.ai/mcp`. Integration guide for coding agents: [/AGENTS.md](https://docs.valyu.ai/AGENTS.md).

## Installation

Install the Valyu and OpenAI packages:

```bash theme={null}
pip install valyu openai
```

Set your API keys as environment variables:

```bash theme={null}
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**:

```python theme={null}
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.

> [!WARNING]
>
> This uses OpenAI's **Responses API** (`responses.create()`), not Chat Completions.

> [accordion] 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](https://platform.valyu.ai/user/account/apikeys?req=increase_results)
> * `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](https://docs.valyu.ai/search/prompting.md).

> [accordion] OpenAIProvider reference
>
> ```python theme={null}
> 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

> [card] [OpenAI Responses API](https://platform.openai.com/docs/guides/responses)
>
> Official OpenAI Responses API documentation

> [card] [Valyu API Reference](https://docs.valyu.ai/api-reference/endpoint/search.md)
>
> Complete Valyu API documentation

> [card] [Python SDK](https://docs.valyu.ai/sdk/python-sdk.md)
>
> Full Python SDK documentation

> [card] [Get API Key](https://platform.valyu.ai)
>
> Get 2,000 free credits a month with a work email (1,000 with a personal email; add a card after your first month to keep them coming)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.