Terminal
Terminal/Skill
Converts code that calls Perplexity's Sonar chat completions API to the newer Agent API, covering endpoints, parameters, models, streaming and citations.
By Perplexity
Works with
npx skills add perplexityai/api-platform-developers --skill migrate-sonar-to-agent-apiMigrates a codebase from Perplexity's Sonar API (POST /chat/completions, chat.completions.create()) to the Agent API (POST /v1/agent, responses.create()).
Both APIs are live; this is a contract migration - endpoint, request body, response parsing, streaming - not a rewrite.
Start by inventorying Sonar usage:
python scripts/scan_sonar_usage.py [path-to-code]
Run it from this skill's directory (the directory containing this SKILL.md), or pass the script's full path. It prints a file-by-file migration checklist with line numbers and the reference file that covers each finding.
Canonical human guide: https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar - when this skill and the live docs disagree on an API fact, the docs win; cross-check there if something looks off.
If a perplexity-docs MCP server is available in your session (the Claude Code plugin ships one; other clients can add https://docs.perplexity.ai/mcp), prefer its search tools for that cross-check.
Never invent model availability, limits, defaults, or API behavior: if a fact is in neither this skill nor the docs, verify it against the live API - or state that you could not.
Classify before touching code, and KEEP the style - do not "upgrade" raw HTTP to an SDK or swap SDKs.
requests, fetch, curl to https://api.perplexity.ai/chat/completions):
migrate to POST https://api.perplexity.ai/v1/agent with the same HTTP library.base_url="https://api.perplexity.ai/v1" - the /v1 is required, the SDK appends /responses - and switch to client.responses.create().
Perplexity-only fields (preset, max_steps, response_format, Perplexity tool types) go through extra_body={...} in Python or a type cast in TypeScript.
Requires a recent OpenAI SDK (openai>=1.66 for Python).from perplexity import Perplexity / @perplexity-ai/perplexity_ai):
switch client.chat.completions.create() to client.responses.create().
Same client construction, same PERPLEXITY_API_KEY env var.ChatPerplexity, LlamaIndex Perplexity LLM, OpenAI Agents SDK):
read integration-styles.md - it has the concrete Agents SDK class swap and the ranked options for LangChain/LlamaIndex.Classification trap: the Perplexity call may live OUTSIDE the framework as a sibling SDK client.
Find which client actually hits api.perplexity.ai and migrate that call site by its own style.
Leave framework-internal LLMs pointed at other providers alone.
Do NOT migrate:
client.search.create(), POST /search) - a different product, unaffected.responses.create, /v1/agent, /v1/responses).THE #1 MIGRATION FAILURE: the Agent API rejects ANY unknown or leftover field - top-level or nested - with HTTP 400:
{"error":{"message":"invalid request body: json: unknown field \"X\"","type":"invalid_request","code":400,"param":"X"}}Sonar silently dropped many params; the Agent API does not. Strip every field not explicitly mapped in request-mapping.md, including everything on its REMOVE list.
Leftover Sonar params -> 400 unknown field. Strict mode (above). Check every request body against the param table and REMOVE list in request-mapping.md.
Web search is NOT automatic - and offering the tool does not guarantee the model calls it.
A bare model request does no search and answers ungrounded.
Add "tools": [{"type": "web_search"}] (or use a preset, which bundles it).
For citation-critical flows, force the search with "tool_choice": {"type": "web_search"} or use a preset.
Even forced, an occasional run returns zero sources - handle empty search_results gracefully.
Do not force tool_choice universally; it adds cost and latency where grounding is optional.
Citations moved.
There is no top-level citations or search_results on Agent responses.
Read the search_results OUTPUT ITEM inside output[].
Message annotations are often an empty array - do not rely on them for citations.
200-wrapped failures.
Failed and cancelled runs return HTTP 200 with status: "failed" or "cancelled" and a populated error field.
Always branch on response.status, never only on the HTTP status code.
Streaming consumers must handle ALL terminals.
Exactly one of response.completed, response.failed, response.incomplete, response.cancelled arrives, plus a bare error event for transport failures.
A consumer that only exits on response.completed hangs on failed runs.
No perplexity/sonar-pro slug exists.
Map sonar-pro per the two-option rule (preset "low" vs perplexity/sonar + web_search) in models-and-presets.md.
max_output_tokens is REQUIRED for anthropic/* models (400 otherwise); values under 16 floor to 16.
On presets and reasoning models, tight caps can be consumed by reasoning tokens before any text or search appears - size generously or omit.
incomplete_details.reason: "max_output_tokens" is the truncation signal (the old finish_reason: "length").
OpenAI SDK traps.
text={"format": ...} is rejected - send top-level response_format via extra_body.
Perplexity-only output items deserialize as raw dicts: use result.get("url"), not result.url, and avoid model_dump() on responses containing them.
Prefer response.output_text for the plain-text case.
Reserved custom-function names.
Custom tool names colliding with built-in tool names (web_search, search_web, people_search, search_people, fetch_url, finance_search, sandbox, and others) are rejected with a 400.
Sonar allowed shadowing; rename during migration (e.g. web_search -> my_web_search).
If any custom tool name 400s, rename it - other names may also be reserved.
Preset mechanics.
instructions alongside a preset REPLACES the preset's system prompt (empty string clears it).
Preset tools cannot be disabled (tools: [] does not clear them; max_tool_calls: 0 is the blunt all-tools off-switch).
Request fields override preset values.
Presets may resolve to third-party models.
python scripts/scan_sonar_usage.py [path-to-code] from this skill's directory (the directory containing this SKILL.md), or pass the script's full path, and turn its output into a file-by-file checklist./v1/agent; messages -> input (system prompt to instructions or a system input item); model slug or preset per models-and-presets.md; search filters into tools[web_search].filters; strip everything on the REMOVE list.output[] walk or output_text; citations from the search_results item; usage key renames; status branching.delta.content; handle all terminals.name/description/parameters), reserved-name renames, function_call -> function_call_output loop.
Details in integration-styles.md.Minimal-diff rule: keep the author's structure, naming, and voice; do not refactor unrelated code.
When a Sonar feature has no Agent equivalent (images, related questions, academic search mode), apply the documented workaround from request-mapping.md if it is small.
For return_related_questions specifically, use the lightweight prompt-delimiter recipe in request-mapping.md - it fits free-text flows too.
If no workaround fits, remove the feature AND call the removal out in your migration notes; never drop user-facing output silently.
max_output_tokens and a cheap model (except on presets and reasoning models - see pitfall 7).chat.completions, choices[0], max_tokens (as a request field), top-level search_recency_filter, citations, delta.content, sonar- model slugs.
Every hit must be intentional legacy prose.