Set up Perplexity with an AI agent

name: perplexity
description: Use when building AI agents that need web-grounded answers with
  citations, accessing multiple LLM providers through one API, performing
  real-time web search, generating embeddings, making classification decisions,
  or orchestrating complex multi-step research workflows. Agents should reach
  for this skill when users need current information, structured outputs, tool
  integration, or multi-provider model access.
metadata:
  mintlify-proj: perplexity
  version: "1.0"

Perplexity API Platform

Product summary

Perplexity API Platform is a unified interface for building AI agents with web search, multi-provider LLM access, and structured reasoning. The platform includes five APIs: Agent API (web-grounded answers with built-in tools and third-party models), Search API (ranked web results as JSON), Embeddings API (text vectors for semantic search), Decisions API (calibrated probabilities for classification), and Orchestrator API (direct model access via OpenAI/Anthropic formats). All APIs share one API key (PERPLEXITY_API_KEY) and one host (api.perplexity.ai). The Agent API endpoint is POST /v1/agent (or /v1/responses for OpenAI compatibility). Install the SDK: pip install perplexityai (Python) or npm install @perplexity-ai/perplexity_ai (TypeScript). See Agent API quickstart for getting started.

When to use

Reach for this skill when:

• Building agents that answer questions with current information: Use Agent API with effort levels or web_search tool to ground answers in real-time web data with inline citations.
• Accessing multiple LLM providers through one API: Use Agent API to call OpenAI (GPT-6, GPT-5.6), Anthropic (Claude), Google (Gemini), xAI (Grok), and others without managing separate API keys.
• Needing raw web search results for your own processing: Use Search API to get ranked results with extracted text, then pass to your model or agent.
• Extracting structured data from unstructured content: Use Agent API with response_format (JSON Schema) to enforce consistent output formats.
• Running long-running research or batch processing: Use Batch API to submit many requests asynchronously (up to 50,000 lines per file).
• Generating embeddings for semantic search or RAG: Use Embeddings API with standard or contextualized embeddings.
• Making yes/no or classification decisions with probabilities: Use Decisions API for grounded, calibrated answers.
• Integrating custom tools or external services: Use Agent API with custom functions, MCP servers, or connectors.

Quick reference

Essential endpoints and SDKs

Task	Endpoint	SDK method
Ask a question with web search	POST /v1/agent	client.responses.create()
Get raw web results	POST /search	client.search.create()
Generate embeddings	POST /v1/embeddings	client.embeddings.create()
Make a classification decision	POST /v1/decisions	client.decisions.create()
Run batch requests	POST /v1/batches	client.batches.create()

Effort levels (pre-configured Agent API setups)

Effort	Use when	Max steps	Model
fast	Single-fact lookups, quick summaries	1	GPT-6-Luna
low	Everyday research, light multi-step	3	GPT-5.6-Sol
medium	Multi-hop browsing, wide aggregation	5	GPT-5.6-Sol
high	Expert-level reasoning, exhaustive sources	8	GPT-5.6-Sol
xhigh	Open-ended agentic work, code execution	12	GPT-5.6-Sol
ultra-preview	Broad research, maximum coverage	15+	GPT-5.6-Sol

Built-in tools for Agent API

Tool	Type	Use for
Web Search	web_search	Real-time web results with domain/date/location filters
Fetch URL	fetch_url	Extract content from specific URLs
Sandbox	sandbox	Run Python code in isolated container
People Search	people_search	Find professionals and people
Finance Search	finance_search	Retrieve financial data and SEC filings

Authentication and configuration

# Set API key (required for all APIs)
export PERPLEXITY_API_KEY="your_key_here"

# Verify key is set (do NOT print it)
test -n "$PERPLEXITY_API_KEY" && echo "Key is set"

Common request patterns

Basic Agent API call with effort level:

response = client.responses.create(
    effort="low",
    input="Your question here"
)
print(response.output_text)

Agent API with specific model:

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Your question",
    max_output_tokens=2048
)

Agent API with custom tools:

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Your question",
    tools=[
        {"type": "web_search"},
        {
            "type": "function",
            "name": "get_data",
            "description": "Fetch data from your system",
            "parameters": {"type": "object", "properties": {...}}
        }
    ]
)

Search API for raw results:

search = client.search.create(
    query="your search query",
    max_results=10
)
for result in search.results:
    print(f"{result.title}: {result.url}")

Structured output (JSON Schema):

response = client.responses.create(
    effort="low",
    input="Extract company info",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "company_info",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "founded": {"type": "integer"}
                },
                "required": ["name", "founded"]
            }
        }
    }
)

Decision guidance

When to use Agent API vs Search API

Need	Use Agent API	Use Search API
Generated answer with citations	✓	—
Raw ranked results only	—	✓
Model reasoning and synthesis	✓	—
Just web results for your model	—	✓
Tool integration (sandbox, custom functions)	✓	—
Lowest cost per request	—	✓

When to use effort level vs direct model selection

Scenario	Use effort level	Use direct model
Want Perplexity's optimized defaults	✓	—
Need specific model capability	—	✓
Want automatic improvements over time	✓	—
Need exact reproducibility	—	✓
Unsure which model to pick	✓	—

When to use streaming vs background mode

Scenario	Use streaming	Use background
Real-time user experience	✓	—
Long-running research (minutes)	—	✓
Need to keep connection open	✓	—
Can poll for results later	—	✓
Batch processing	—	✓

Workflow

Typical Agent API workflow

1. Understand the task: Determine if you need a generated answer (Agent API), raw results (Search API), embeddings, or a classification decision.

2. Choose your approach:

   • For quick answers: Use an effort level (effort="low")
   • For specific model: Use model="provider/model-name"
   • For custom tools: Add tools array with built-in or custom tools

3. Build the request:

   • Set input (the question or prompt)
   • Add instructions if you need specific behavior
   • Include tools if needed (web_search, fetch_url, sandbox, custom functions)
   • Set max_output_tokens if you need a limit
   • Add response_format if you need JSON Schema output

4. Handle the response:

   • Check response.status (should be "completed")
   • Extract text from response.output_text (SDK convenience property)
   • Iterate response.output array for tool results, citations, or generated files
   • Check response.usage for token counts and costs

5. Continue conversation (if needed):

   • Pass previous_response_id to continue context
   • Or replay the full conversation in input array with prior messages and tool calls

Batch processing workflow

1. Create a JSONL file (one JSON request per line, up to 50,000 lines)
2. Upload with client.files.create(file, purpose="batch")
3. Create batch with client.batches.create(file_id)
4. Poll with client.batches.retrieve(batch_id) until status is "completed"
5. Download results with client.files.content(output_file_id)

Custom function workflow

1. Define the function schema in tools array with type: "function"
2. Call client.responses.create() with the tools
3. Check response for function_call items in output array
4. Execute the function on your side
5. Send followup request with original input + function_call + function_call_output
6. Continue until response status is "completed"

Common gotchas

• API key in logs: Never print, echo, or log your API key. Store in environment variables only. Commands like echo $PERPLEXITY_API_KEY leave the key in shell history.

• Anthropic models require max_output_tokens: Requests using anthropic/* models must include max_output_tokens or they return HTTP 400. Other models don't require it.

• Web search is opt-in: A request with only model and input answers from the model's knowledge, not the web. Add effort level or tools: [{"type": "web_search"}] to enable web search.

• Function calls don't execute server-side: When the model calls a custom function, the API pauses and returns a function_call item. Your code must execute it and send the result back in a followup request.

• Effort level updates are automatic: Dynamic effort levels (e.g., effort="low") pick up improvements automatically. Pin a version (e.g., effort="low@2026-10-16.0") if you need stability.

• Streaming keeps connection open: Streaming holds the connection for the entire run. For long-running tasks (minutes), use background=true instead and poll by ID.

• Search results may have empty snippets: Always check if snippet is empty or null before passing to your model. Skip those results or fetch the full URL with fetch_url.

• Batch API has 30-day retention: Files and batch results expire after 30 days. Download outputs before they expire.

• Tool results are in the output array: Built-in tools (web_search, sandbox, etc.) return results as separate items in response.output, not in the message text. Iterate the array to find search_results, sandbox_results, etc.

• JSON Schema first request has delay: The first request with a new JSON Schema may take 10-30 seconds to prepare. Subsequent requests are fast.

• Effort level tools merge, not replace: When you override tools under an effort level, they merge per tool type. Listing one tool overrides only that tool's options.

Verification checklist

Before submitting work:

• API key is set in environment (PERPLEXITY_API_KEY) and not hardcoded
• Request includes required fields: input (or query for Search API), and either effort, model, or response_format
• Anthropic models include max_output_tokens
• Web search is explicitly enabled if current information is needed
• Custom functions are defined with complete JSON Schema
• Response status is checked (should be "completed" or "success")
• Tool results are extracted from response.output array, not just message text
• Streaming or background mode is used appropriately for task duration
• Batch files are valid JSONL (one JSON object per line)
• Citations are extracted from search results if needed
• Token usage and costs are logged from response.usage

Resources

• Comprehensive navigation: See llms.txt for a complete page-by-page listing of all documentation.
• Agent API quickstart: https://docs.perplexity.ai/docs/agent-api/quickstart — Start here for web-grounded answers with tools.
• Effort levels guide: https://docs.perplexity.ai/docs/agent-api/effort — Understand pre-configured setups and when to use each.
• Search API quickstart: https://docs.perplexity.ai/docs/search/quickstart — Get raw ranked web results for your own processing.

---

For additional documentation and navigation, see: https://docs.perplexity.ai/llms.txt