src/agent/client.py

Building Production Agentic Workflows with Perplexity Agent API

Why this matters for builders

Perplexity Agent API is a managed runtime that lets you build agentic workflows with integrated real-time search, tool execution, and multi-model orchestration from a single endpoint.

Instead of stitching together separate search APIs, LLM providers, tool routers, and retry logic yourself, you get a production-grade orchestrator that swaps between frontier models, applies curated presets, enforces step limits and token budgets, and injects grounded web results automatically.

This changes the game for solo builders and small teams: you can ship reliable, citeable, multi-step agents in days instead of weeks, with predictable cost controls and without managing your own agent loop infrastructure.

When to use it

Use Perplexity Agent API when you need any of the following:

• Research-heavy agents that must cite fresh web sources
• Multi-step workflows that benefit from different model strengths (reasoning vs speed vs cost)
• Production agents where you want guardrails on token spend, step count, and tool access
• Rapid prototyping of agentic features without building your own ReAct loop or tool-calling router
• Applications that require model-agnostic behavior today and easy swapping as new frontier models appear

It is not the right choice for pure offline reasoning, extremely high-frequency micro-tasks, or when you need full control over every prompt in the reasoning trace.

The full process

1. Define the goal (30–60 minutes)

Start by writing a one-paragraph product spec. Be explicit about success criteria.

Example goal for a vibe-coding project:

Build a “Competitor Intelligence Agent” that, given a startup name, (1) searches the web for recent news and funding rounds, (2) extracts key metrics and positioning, (3) compares it against a list of known competitors using a strong reasoning model, and (4) returns a concise report with sources. The agent must stay under 80k output tokens total and never exceed 12 reasoning steps.

Write this spec in a SPEC.md file. This becomes the source of truth for every prompt you give your coding assistant.

2. Shape the spec into a strong prompt for your AI coding tool

Use this starter template (copy-paste and adapt):

You are an expert Python engineer building against the Perplexity Agent API.

Project goal: {{paste your SPEC.md here}}

Requirements:
- Use the official Perplexity Agent API endpoint
- Support model selection between available frontier models and curated presets
- Configure tool access (web search must be enabled)
- Enforce max_steps=12 and max_tokens=80000
- Implement structured output for the final report (use Pydantic)
- Include proper error handling and retry logic for transient failures
- Add observability: log every model call, step count, and token usage
- Write clean, typed code with clear comments

Generate the complete implementation including:
1. A reusable client class
2. Example usage script
3. Basic test cases (happy path + step limit exceeded)
4. README with setup instructions

Only use APIs and patterns documented at https://docs.perplexity.ai/docs/agent-api/quickstart

3. Scaffold the project

Create this minimal structure:

competitor-intel-agent/
├── pyproject.toml
├── src/
│   └── agent/
│       ├── client.py
│       ├── models.py
│       └── tools.py
├── examples/
│   └── run_intel.py
├── tests/
│   └── test_agent.py
├── SPEC.md
├── README.md
└── .env.example

Use your AI coding assistant to generate the skeleton by feeding it the directory tree above plus the prompt from step 2.

4. Implement the core client

Here’s a clean starter implementation pattern (generated or refined by your coding assistant):

import os
from typing import Dict, Any, List
from pydantic import BaseModel
import httpx
from dotenv import load_dotenv

load_dotenv()

class AgentReport(BaseModel):
    company: str
    key_metrics: Dict[str, Any]
    positioning: str
    competitors_comparison: List[Dict[str, str]]
    sources: List[str]

class PerplexityAgent:
    def __init__(self):
        self.api_key = os.getenv("PERPLEXITY_API_KEY")
        self.base_url = "https://api.perplexity.ai/agent"  # check official docs for exact endpoint
        self.client = httpx.Client(timeout=180.0)

    def run(self, query: str, model_preset: str = "balanced") -> AgentReport:
        payload = {
            "query": query,
            "model": model_preset,           # or specific model name
            "tools": ["web_search"],
            "max_steps": 12,
            "max_tokens": 80000,
            "response_format": {"type": "json_object", "schema": AgentReport.model_json_schema()}
        }

        resp = self.client.post(
            f"{self.base_url}/run",
            json=payload,
            headers={
                "Authorization": f"Bearer {self.api_key}",
                "Content-Type": "application/json"
            }
        )
        resp.raise_for_status()
        data = resp.json()

        # Log observability
        print(f"Steps used: {data.get('steps_used', 'unknown')}")
        print(f"Tokens used: {data.get('tokens_used', 'unknown')}")

        return AgentReport.model_validate_json(data["result"])

Note: Exact endpoint, parameter names, and payload shape must be confirmed from the official Perplexity Agent API documentation at https://docs.perplexity.ai/docs/agent-api/quickstart. The example above is a realistic starter template based on the announced capabilities.

5. Validate rigorously

Run these checks before considering the agent “shippable”:

• Happy path test: Execute against 5 real companies. Verify every report contains sources and stays under step/token limits.
• Guardrail test: Force a query that would normally require 20+ steps. Confirm the agent stops at max_steps and returns a graceful partial result.
• Cost control test: Compare token usage across “fast”, “balanced”, and “reasoning” presets.
• Structured output test: Confirm Pydantic parsing never fails on real responses.
• Rate limit & retry test: Simulate transient errors and verify exponential backoff works.

Write automated tests that assert these properties.

6. Ship it safely

• Deploy as a simple FastAPI endpoint or a temporal workflow
• Add authentication and per-user token budgets
• Expose usage metrics to users (steps used, tokens, cost estimate)
• Document model preset trade-offs in your public README
• Monitor for drift: frontier model performance changes quickly; have a plan to update presets

Pitfalls and guardrails

### What if the agent hallucinates sources?
Always require tools=["web_search"] and use the returned sources array in your final output. Never trust the model’s memory alone.

### What if token costs explode?
Set strict max_tokens and max_steps on every call. Start with cheaper presets for initial research steps and only escalate to stronger models for the final synthesis step if needed.

### What if the API response format changes?
Code defensively: log the full raw response on first integration. Use Pydantic with extra='ignore' initially, then tighten the schema once you understand real payloads.

### What if I need a tool the Agent API doesn’t expose yet?
The current release focuses on integrated search + curated tools. For custom tool execution, you may still need to build a thin wrapper that calls your own functions and feeds results back as additional context. Check the official docs for the latest supported tool list.

### What if I want to use a specific new model that just dropped?
The API’s strength is model-agnostic orchestration. Test the new model in a preset first, then expose it via configuration rather than hard-coding.

What to do next

1. Ship the first vertical agent (Competitor Intel, Market Research, Lead Qualifier, etc.)
2. Add A/B testing between different presets and measure answer quality vs cost
3. Instrument cost and latency per workflow type
4. Extract common patterns into a small internal agent SDK
5. Explore multi-agent orchestration by composing several Agent API calls with different presets

Sources

• Original announcement: https://x.com/perplexity_ai/status/2031828430694858905
• Official documentation: https://docs.perplexity.ai/docs/agent-api/quickstart
• Perplexity API Platform: https://www.perplexity.ai/api-platform

(Word count: 1,248)

This guide gives you a repeatable, production-minded process to turn the Perplexity Agent API announcement into working software the same week it drops. Start with the spec, stay disciplined about guardrails, and you’ll ship agents that are both powerful and safe.