Skip to main content
Every agent run begins with one Agent API request. Before prompts, tools, or output format, you decide what runs and how far it can go. The fastest way to start is a preset — a tuned bundle of model, system prompt, search config, and tools — which you then customize with individual settings as needed. This page sets up the call the rest of this section builds on.

​
Start from a preset

A preset gives you a working agent in one field. 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="low",
    input="Give me a thorough overview of the current state of solid-state battery commercialization.",
)

print(response.output_text)

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  preset: 'low',
  input: 'Give me a thorough overview of the current state of solid-state battery commercialization.',
});

console.log(response.output_text);

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "low",
    "input": "Give me a thorough overview of the current state of solid-state battery commercialization."
  }' | jq
Other presets trade depth against latency and cost. See Presets for what each one bundles and how preset updates are managed.

​
Customize the system prompt: instructions

A preset ships its own tuned system prompt. The instructions field is the agent’s system prompt — the standing rules that hold for every turn of the loop: role, tone, citation, and grounding rules. They apply regardless of what the user asks on a given turn. 
instructions="You are a research assistant. Cite every claim by source domain, and never speculate beyond the retrieved evidence."
Setting instructions replaces the preset’s system prompt rather than appending to it. Omit instructions to keep the preset’s prompt.
Keep the system prompt lean. Every token here is re-processed on each step of the loop, so it adds up across tool calls. For machine-readable output or retrieval constraints, prefer request parameters (see Structure the output and Give it tools) over prose rules.

​
Customize the loop: max_steps

An agent run is a loop: the model reasons, optionally calls tools, reads the results, and repeats until it answers. One step is one pass through that cycle — a single model turn that may call tools. max_steps caps how many steps a run may take. Use it to bound runaway loops and to trade latency against depth. When a run reaches the cap, the agent doesn’t error — it makes one final pass to answer from what it has gathered so far. A low max_steps doesn’t disable tools — it limits how many times the agent can act on what they return. At max_steps: 1 the model still gets one turn and can call a tool, but the run won’t loop back to reason over the result. 
response = client.responses.create(
    preset="low",
    input="Give me a thorough overview of the current state of solid-state battery commercialization.",
    max_steps=20,
)
If you pass max_steps alongside a preset, it overrides the preset’s value, up to the preset’s own ceiling for chat-style presets.

​
Customize the model: model or models

A preset picks a model for you. When you need full control over which model answers, set one explicitly instead of (or alongside) a preset:
FieldWhat it is
modelA single model in provider/model format, for example openai/gpt-5.5.
modelsA fallback chain of up to 5 models, tried in order until one succeeds.
If you set models, it takes precedence over model. See Models for the catalog and pricing, and Model fallback for how the chain resolves.
Start from a preset, then move to an explicit model (or models chain) when you need to pin the exact engine.

​
Next steps

Prompt the agent

Split the system prompt from the question, and ground the run.

Presets

See the tuned presets you can start from.