Define the run

Configure the agent run: start from an effort level, then customize the system prompt, the loop bound, and the model.

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 an effort — 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 an effort level

A effort gives you a working agent in one field.

Python

from perplexity import Perplexity

client = Perplexity()

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

print(response.output_text)

Other effort levels trade depth against latency and cost. See Effort Levels for what each one bundles and how effort level updates are managed.

Customize the system prompt: instructions

A effort 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 effort level’s system prompt rather than appending to it. Omit instructions to keep the effort level’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 model turn plus the tool calls it makes in that turn. max_steps caps how many of these tool-calling turns a run may take. Use it to bound runaway loops and to trade latency against depth.

When a run uses all its steps and the last one called tools, the agent doesn’t error. It makes one extra answer-only turn with tools disabled, and writes the final answer from the tool results it has gathered so far. If the model answers without calling a tool, the run ends there, before the cap.

At max_steps: 1, the agent gets one round of tool calls, then answers from their results. That is enough for a single search followed by an answer. It is not enough when the agent needs to act on what it found: search again, fetch a page from the results, or rerun code that failed. Tools that usually spend a step on setup get little or no work done: with finance_search, and with sandbox plus web_search, the agent typically loads the tool’s instructions in its first step and only queries data or runs code after that.

When you specify model or models without an effort level, omitting max_steps defaults the run to 1 step. Set it explicitly whenever your tools need multiple turns. For direct-model requests that enable finance_search, use max_steps: 3 or higher so the agent has enough room to initialize and run the tool. Effort levels provide their own step budget unless you override it.

response = client.responses.create(
    effort="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 an effort, it overrides the effort level’s value, up to the effort level’s own ceiling for chat-style effort levels.

Customize the model: model or models

An effort level picks a model for you. When you need full control over which model answers, set one explicitly instead of (or alongside) an effort level:

Field	What it is
model	A single model in provider/model format, for example openai/gpt-5.6-sol.
models	A 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 an effort, 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.

Effort Levels

See the tuned effort levels you can start from.