Agent API

The Agent API is a multi-provider, interoperable API specification for building LLM applications. Access models from multiple providers with integrated real-time web search, tool configuration, reasoning control, and token budgets—all through one unified interface.

Get your Perplexity API Key

Navigate to the API Keys tab in the API Portal and generate a new key.

Click here

Why Use the Agent API?

Multi-Provider Access

Access OpenAI, Anthropic, Google, xAI, and more through one unified API, no need to manage multiple API keys.

Transparent Pricing

See exact token counts and costs per request, no markup, just direct provider pricing.

Granular Control

Change models, reasoning, tokens, and tools with consistent syntax.

We recommend using our official SDKs for a more convenient and type-safe way to interact with the Agent API.

Installation

Install the SDK for your preferred language:

Python

pip install perplexityai

Authentication

Set your API key as an environment variable. The SDK will automatically read it:

macOS/Linux

export PERPLEXITY_API_KEY="your_api_key_here"

Windows

setx PERPLEXITY_API_KEY "your_api_key_here"

All SDK examples below automatically use the PERPLEXITY_API_KEY environment variable. You can also pass the key explicitly if needed.

Basic Usage

Convenience Property: Both Python and Typescript SDKs provide an output_text property that aggregates all text content from response outputs. Instead of iterating through response.output, simply use response.output_text for cleaner code.

Using a Third-Party Model

Use third-party models from OpenAI, Anthropic, Google, xAI, and other providers for specific capabilities:

Python

from perplexity import Perplexity

client = Perplexity()

# Using a third-party model
response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest developments in AI?",
    tools=[{"type": "web_search"}],
    instructions="You have access to a web_search tool. Use it for questions about current events, news, or recent developments. Use 1 query for simple questions. Keep queries brief: 2-5 words. NEVER ask permission to search - just search when appropriate",
)

print(f"Response ID: {response.id}")
print(response.output_text)

With Web Search Tool

Enable web search capabilities using the web_search tool:

Python

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What's the weather in San Francisco?",
    tools=[
        {
            "type": "web_search"
        }
    ],
    instructions="You have access to a web_search tool. Use it when you need current information.",
)

if response.status == "completed":
    print(response.output_text)

Using a Preset

Presets provide optimized defaults for specific use cases. Start with a preset for quick setup:

Python

from perplexity import Perplexity

client = Perplexity()

# Using a preset (e.g., pro-search)
response = client.responses.create(
    preset="pro-search",
    input="What are the latest developments in AI?",
)

print(f"Response ID: {response.id}")
print(response.output_text)

Input Formats

The input parameter accepts either a string or an array of message objects.

String Input

Simple string input for straightforward queries:

Python

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest AI developments?",
)

Message Array Input

Use message arrays for multi-turn conversations:

Python

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input=[
        {"type": "message", "role": "system", "content": "You are a helpful assistant."},
        {"type": "message", "role": "user", "content": "What are the latest AI developments?"},
    ],
    instructions="Provide detailed, well-researched answers.",
)

Instructions Parameter

The instructions parameter provides system instructions or guidelines for the model. This is particularly useful for:

• Tool usage instructions: Guide the model on when and how to use available tools
• Response style guidelines: Control the tone and format of responses
• Behavior constraints: Set boundaries and constraints for model behavior

Example with tool instructions:

Python

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest developments in AI?",
    instructions="You have access to a web_search tool. Use it for questions about current events, news, or recent developments. Use 1 query for simple questions. Keep queries brief: 2-5 words. NEVER ask permission to search - just search when appropriate",
    tools=[{"type": "web_search"}],
)

Tools

The Agent API provides two powerful tools for accessing real-time web information:

• web_search - Performs web searches to retrieve current information and news
• fetch_url - Fetches and extracts content from specific URLs

The web_search tool can optionally include user location for localized results:

Python

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest news in San Francisco?",
    tools=[
        {
            "type": "web_search",
            "user_location": {
                "latitude": 37.7749,
                "longitude": -122.4194,
                "country": "US",
                "city": "San Francisco",
                "region": "CA"
            }
        }
    ],
    instructions="Use web_search to find current information.",
)

Generation Parameters

Control response generation with standard parameters:

Python

response = client.responses.create(
    model="openai/gpt-5.2",
    input="Explain quantum computing",
    max_output_tokens=1000,  # Maximum tokens to generate
)

Reasoning Effort

Control the reasoning effort level for reasoning models:

• low: Minimal reasoning effort
• medium: Moderate reasoning effort
• high: Maximum reasoning effort

The reasoning parameter is only supported by models with reasoning capabilities. Models without reasoning support will ignore this parameter.

Python

response = client.responses.create(
    model="openai/gpt-5.2",
    input="Solve this complex problem step by step",
    reasoning={
        "effort": "high"  # Use maximum reasoning
    },
)

Streaming Responses

The Agent API supports streaming responses using Server-Sent Events (SSE). Enable streaming by setting stream=True:

Python

response = client.responses.create(
    model="openai/gpt-5.2",
    input="Explain quantum computing in detail",
    stream=True,
)

# Process streaming response
for chunk in response:
    if chunk.type == "response.output_text.delta":
        print(chunk.delta, end="", flush=True)
    elif chunk.type == "response.completed":
        print(f"\n\nResponse completed: {chunk.response.output_text}")

For comprehensive streaming documentation, see the Streaming Guide.

Error Handling

Handle errors gracefully:

Python

from perplexity import Perplexity, APIError

try:
    response = client.responses.create(
        model="openai/gpt-5.2",
        input="What is AI?",
    )

    if response.status == "completed":
        print(response.output_text)
    elif response.status == "failed":
        if response.error:
            print(f"Error: {response.error.message}")

except APIError as e:
    print(f"API Error: {e.message}")
    print(f"Status Code: {e.status_code}")

Response Structure

Response Structure Example

Responses from the Agent API have a structured format:

{
  "background": false,
  "completed_at": 1770431423,
  "created_at": 1770431423,
  "error": null,
  "frequency_penalty": 0,
  "id": "resp_7ac471db-4e3c-4059-a52d-c4bd6dc7c42b",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {},
  "model": "openai/gpt-5.2",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "AI (artificial intelligence) is the field of creating...",
          "type": "output_text"
        }
      ],
      "id": "msg_3416c756-f840-4ffa-b4ae-07ad2c122a5d",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": null,
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "cost": {
      "currency": "USD",
      "input_cost": 0.0001,
      "output_cost": 0.00148,
      "total_cost": 0.00158
    },
    "input_tokens": 59,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 106,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 165
  },
  "user": null
}

Next Steps

Model Fallback

Specify multiple models for automatic failover and higher availability.

Presets

Explore available presets and their configurations.

Models

Explore available presets and third-party models for the Agent API.

API Reference

View complete endpoint documentation and parameters.

Structured Outputs

Generate formatted responses with JSON schema or regex.

Search API

Get raw search results with the Search API.

Need help? Check out our community for support and discussions with other developers.