Add Perplexity provider example via OpenAI-compatible Agent API

- examples/model_providers/perplexity_provider.py: routes Agent API calls
  to https://api.perplexity.ai using AsyncOpenAI + OpenAIChatCompletionsModel
  via a ModelProvider, with the default sonar-pro model.
- examples/tools/perplexity_search.py: wraps Perplexity's Search API as a
  function tool using httpx.
- examples/model_providers/README.md: documents the new Perplexity entry point.

Both examples send the X-Pplx-Integration: openai-agents/<version> attribution
header on every outgoing request.

Signed-off-by: James Liounis <james.liounis@perplexity.ai>

Author: jliounis

examples/model_providers/README.md

@@ -22,3 +22,17 @@ Direct-model examples let you override the target model:
 uv run examples/model_providers/any_llm_provider.py --model openrouter/openai/gpt-5.4-mini
 uv run examples/model_providers/litellm_provider.py --model openrouter/openai/gpt-5.4-mini
 ```
+
+## Perplexity
+
+Perplexity exposes an OpenAI-compatible chat completions endpoint, so you can route
+requests through an `AsyncOpenAI` client by overriding `base_url`:
+
+```bash
+export PERPLEXITY_API_KEY="..."
+uv run examples/model_providers/perplexity_provider.py
+```
+
+See [`perplexity_provider.py`](perplexity_provider.py) for the full setup. A search-tool
+example using Perplexity's Search API is at
+[`examples/tools/perplexity_search.py`](../tools/perplexity_search.py).

examples/model_providers/perplexity_provider.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import os
+
+from openai import AsyncOpenAI
+
+from agents import (
+    Agent,
+    Model,
+    ModelProvider,
+    OpenAIChatCompletionsModel,
+    RunConfig,
+    Runner,
+    function_tool,
+    set_tracing_disabled,
+)
+
+"""Use Perplexity's Agent API (OpenAI-compatible chat completions) with the Agents SDK.
+
+Perplexity's chat completions endpoint is OpenAI-compatible, so the simplest path is to
+point an `AsyncOpenAI` client at `https://api.perplexity.ai` and wrap it in a
+`ModelProvider` that returns an `OpenAIChatCompletionsModel`.
+
+Set `PERPLEXITY_API_KEY` in your environment before running:
+
+    export PERPLEXITY_API_KEY="..."
+    uv run examples/model_providers/perplexity_provider.py
+
+Docs: https://docs.perplexity.ai/api-reference/chat-completions-post
+"""
+
+PERPLEXITY_BASE_URL = "https://api.perplexity.ai"
+DEFAULT_MODEL = "sonar-pro"
+INTEGRATION_SLUG = "openai-agents"
+
+
+def _attribution_header() -> str:
+    try:
+        version = importlib.metadata.version("openai-agents")
+    except importlib.metadata.PackageNotFoundError:
+        version = "unknown"
+    return f"{INTEGRATION_SLUG}/{version}"
+
+
+API_KEY = os.environ.get("PERPLEXITY_API_KEY", "")
+if not API_KEY:
+    raise ValueError("Please set PERPLEXITY_API_KEY in your environment.")
+
+
+client = AsyncOpenAI(
+    base_url=PERPLEXITY_BASE_URL,
+    api_key=API_KEY,
+    default_headers={"X-Pplx-Integration": _attribution_header()},
+)
+set_tracing_disabled(disabled=True)
+
+
+class PerplexityProvider(ModelProvider):
+    def get_model(self, model_name: str | None) -> Model:
+        return OpenAIChatCompletionsModel(
+            model=model_name or DEFAULT_MODEL,
+            openai_client=client,
+        )
+
+
+PERPLEXITY_PROVIDER = PerplexityProvider()
+
+
+@function_tool
+def get_weather(city: str) -> str:
+    print(f"[debug] getting weather for {city}")
+    return f"The weather in {city} is sunny."
+
+
+async def main() -> None:
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a helpful research assistant. Cite sources when useful.",
+        tools=[get_weather],
+    )
+
+    result = await Runner.run(
+        agent,
+        "What are the latest developments in quantum computing this week?",
+        run_config=RunConfig(model_provider=PERPLEXITY_PROVIDER),
+    )
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/tools/perplexity_search.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import os
+
+import httpx
+
+from agents import Agent, Runner, function_tool, set_tracing_disabled
+
+"""Expose Perplexity's Search API as a function tool.
+
+This shows how to wrap a direct HTTP call to `https://api.perplexity.ai/search` as a
+`@function_tool` so any agent can use it. The Search API returns ranked web results
+with titles, URLs, snippets, and dates — useful when you want raw search hits rather
+than a model-summarised answer.
+
+Set `PERPLEXITY_API_KEY` in your environment before running:
+
+    export PERPLEXITY_API_KEY="..."
+    uv run examples/tools/perplexity_search.py
+
+Docs: https://docs.perplexity.ai/api-reference/search-post
+"""
+
+PERPLEXITY_SEARCH_URL = "https://api.perplexity.ai/search"
+INTEGRATION_SLUG = "openai-agents"
+
+
+def _attribution_header() -> str:
+    try:
+        version = importlib.metadata.version("openai-agents")
+    except importlib.metadata.PackageNotFoundError:
+        version = "unknown"
+    return f"{INTEGRATION_SLUG}/{version}"
+
+
+@function_tool
+async def perplexity_search(query: str, max_results: int = 5) -> str:
+    """Search the web with Perplexity's Search API.
+
+    Args:
+        query: The search query.
+        max_results: Number of results to return (1-20).
+    """
+    api_key = os.environ.get("PERPLEXITY_API_KEY")
+    if not api_key:
+        return "Error: PERPLEXITY_API_KEY is not set."
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "X-Pplx-Integration": _attribution_header(),
+    }
+    body = {"query": query, "max_results": max_results}
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.post(PERPLEXITY_SEARCH_URL, headers=headers, json=body)
+        response.raise_for_status()
+        data = response.json()
+
+    results = data.get("results", [])
+    if not results:
+        return "No results found."
+
+    formatted = []
+    for i, item in enumerate(results, 1):
+        title = item.get("title", "")
+        url = item.get("url", "")
+        snippet = item.get("snippet", "")
+        formatted.append(f"{i}. {title}\n   {url}\n   {snippet}")
+    return "\n\n".join(formatted)
+
+
+async def main() -> None:
+    set_tracing_disabled(disabled=True)
+    agent = Agent(
+        name="Researcher",
+        instructions=(
+            "You are a research assistant. Use the perplexity_search tool to find current "
+            "information, then summarise the findings and cite the source URLs."
+        ),
+        tools=[perplexity_search],
+    )
+
+    result = await Runner.run(
+        agent,
+        "What were the headline announcements from the latest major AI developer conference?",
+    )
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())