Agent API Presets: Customize what you need, use defaults for the rest

Start from a preset

A preset is a preconfigured bundle of Agent API settings, that packages a model, search config, reasoning steps, system prompt, and available tools into a single string you pass on the request, so you inherit a maintained configuration instead of needing to specify and update each field yourself. Perplexity updates the underlying configuration as evaluations improve, and your calls pick up those updates without needing to adjust your code. Imagine a preset configuration almost perfectly matches your use case, with the exception of one field that you’d like to change. Pass your preset by name and add only the field you want to modify; everything else retains the preset’s default. Tools work per type: listing one tool overrides only that tool’s options and leaves the preset’s other tools attached. Agent API presets

Check the prerequisites

You need Python 3.10 or newer, the perplexityai SDK installed, and an API key exported as PERPLEXITY_API_KEY. The SDK’s package metadata declares Python 3.9 as its minimum, but at least one 3.9 build fails to import perplexity at runtime; 3.10 is the lowest version verified against perplexityai 0.43.3 for both import and a live client.responses.create(...) call. Create the key at console.perplexity.ai/group/keys. If you have never called the API before, run through the Perplexity API quickstart first; come back here once client.responses.create(...) returns for you.

pip install perplexityai
export PERPLEXITY_API_KEY="pplx-..."

Run a basic example

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="low",
    input="Summarize the current Perplexity Agent API pricing page.",
)

print("model:", response.model)
print(response.output_text)

The low preset supplies the model, the tools, the system prompt, and every parameter default. Your request adds only the input.

Make the three updates

1. Override one parameter

Pass one field you want to change and leave the rest to the preset. low documents a default max_steps of 5. The call written below raises the max_steps ceiling to 8. Other field defaults are left unchanged.

response = client.responses.create(
    preset="low",
    input="Summarize this week's Agent API changelog.",
    max_steps=8,
)

print("model:", response.model)
print("status:", response.status)
print("tool invocations:", response.usage.tool_calls_details)

Example run (captured August 2026 with perplexityai 0.43.3):

model: openai/gpt-5.6-luna
status: completed
tool invocations: {'fetch_url': ToolCallDetailsOutput(invocation=1), 'search_web': ToolCallDetailsOutput(invocation=2)}

Tool invocations vary run to run because open-web agent calls are nondeterministic. For this call, model, system prompt, and tools all came from low and only max_steps was overridden as a request field; the response object does not expose an effective max_steps, so treat this as a documented request override rather than something you can print back and verify from the response. Agent API presets

2. Merge tool options

Pass a partial entry for one tool and the preset’s other tools stay attached.

response = client.responses.create(
    preset="high",
    input=(
        "Read https://docs.perplexity.ai/docs/agent-api/presets "
        "and list the preset names on that page."
    ),
    tools=[{
        "type": "web_search",
        "max_tokens": 6000,
        "max_tokens_per_page": 1200,
    }],
)

print("model:", response.model)
print("tool invocations:", response.usage.tool_calls_details)

Example run (captured August 2026 with perplexityai 0.43.3):

model: openai/gpt-5.6-sol
tool invocations: {'fetch_url': ToolCallDetailsOutput(invocation=1)}

We updated web_search but fetch_url still ran because tools merge per type. usage.tool_calls_details is the evidence: it records which tools actually ran, and fetch_url appears there even though we never passed a fetch_url entry. Because the prompt above names a URL, a skeptical reader might ask whether the URL alone triggered fetch_url. Drop the preset, supply an explicit model, and pass only web_search:

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input=(
        "Read https://docs.perplexity.ai/docs/agent-api/presets "
        "and list the preset names on that page."
    ),
    tools=[{"type": "web_search"}],
)

That call completes with search_web only and no fetch_url invocation; add preset="high" back and fetch_url returns. To also adjust fetch_url, add a fetch_url entry to tools alongside web_search. The API rejects a request that omits both preset and model with 400: model, models, or preset is required. Agent API presets

3. Inspect what the preset is running

response.model and response.usage.tool_calls_details tell you which model served this call and which tools ran on this call. This is inspection of the observed run, not of the preset’s configuration: the response does not expose the effective system prompt, max_steps, reasoning, or the full inherited tool set. Read these fields on any request where correctness or cost matters.

def inspect(preset: str, prompt: str) -> None:
    response = client.responses.create(preset=preset, input=prompt)
    print(f"preset={preset}")
    print(f"  model:       {response.model}")
    print(f"  status:      {response.status}")
    print(f"  invocations: {response.usage.tool_calls_details}")
    print(f"  total_cost:  ${response.usage.cost.total_cost}")

inspect("low",  "Summarize the current Perplexity Agent API pricing page.")
inspect("high", "Read https://docs.perplexity.ai/docs/agent-api/presets and list the preset names on that page.")

Example run (captured August 2026 with perplexityai 0.43.3):

preset=low
  model:       openai/gpt-5.6-luna
  status:      completed
  invocations: {'search_web': ToolCallDetailsOutput(invocation=3)}
  total_cost:  $0.01245
preset=high
  model:       openai/gpt-5.6-sol
  status:      completed
  invocations: {'fetch_url': ToolCallDetailsOutput(invocation=3, cost_usd=0.01316, token_usage=[...])}
  total_cost:  $0.14862

Both cost and tool invocation counts will vary between runs and between presets. What we learn from this inspection is which backing model served the call, which tools actually ran, and what that particular call cost. In the live calls captured for this cookbook, response.tools did not reliably echo the preset’s inherited tools, so use response.usage.tool_calls_details to identify which tools actually ran. Agent API quickstart

Freeze when you need reproducibility

Override when the preset almost matches your task and you want to pick up Perplexity’s re-tuning as models and defaults change. Use overrides for product features that should improve as the preset improves. Freeze when you need the deploy to be reproducible: regulated environments, snapshot tests, published benchmarks, and other cases where stability outranks improvement. Freezing means copying the preset’s current values into your request and omitting the preset field. Copy the full self-contained current values block from the presets documentation: model, instructions (the system prompt), tools with every field, max_steps, max_output_tokens, and reasoning. Do not omit any of them. The snippet below shows the request shape, not a copy-paste frozen low. The instructions value is truncated for space; freeze the real low by pasting the complete instructions string verbatim from the presets documentation.

response = client.responses.create(
    # preset= is intentionally omitted
    model="openai/gpt-5.6-luna",
    instructions="Today is {{current_date}}.\n\nYou are an expert research assistant...",  # paste the full text from the presets doc
    input="Your input goes here.",
    max_steps=5,
    max_output_tokens=32768,
    reasoning={"effort": "minimal"},
    tools=[
        {"type": "web_search", "max_results": 15, "max_tokens": 2000, "max_tokens_per_page": 2000},
        {"type": "fetch_url", "max_urls": 1},
    ],
)

Freezing pins your configuration. It does not pin the live web or nondeterministic model output; a frozen call still returns different content as pages change and generations vary. Agent API presets Pricing

​Start from a preset

​Check the prerequisites

​Run a basic example

​Make the three updates

​1. Override one parameter

​2. Merge tool options

​3. Inspect what the preset is running

​Freeze when you need reproducibility

Start from a preset

Check the prerequisites

Run a basic example

Make the three updates

1. Override one parameter

2. Merge tool options

3. Inspect what the preset is running

Freeze when you need reproducibility