Automation and Agents

Perplexity Agent API Profiles: Pin a Version or Follow Latest?

A reusable agent configuration is easier to share. The production question is how to change it without losing the ability to explain which setup handled a request.

By Demetri Panici

October 1, 2026

16 min read

On this page

What a Profile actually packages
What changed on September 28
Pinning versus following latest
The hidden change paths around the Profile
A practical release lane
Worked example: a support triage agent
The change-control checklist
Common rollout mistakes
FAQs
What is a Perplexity Agent API Profile?
Should production applications use a pinned version or latest?
Does pinning a Profile make the full request reproducible?
What happens if the Profile ID or version is invalid?
Did Perplexity launch Skills and connectors on September 28?
Are there independent performance results for Profiles?
The release choice belongs to the operator

Perplexity's Agent API update gives a team one versioned reference for a reusable agent setup. The decision after creating one is less glamorous and more consequential: should production calls pin an exact Profile version, or follow the newest version automatically?

For a workflow that must be explainable after a bad result, pin a tested version and promote changes deliberately. For an internal experiment where rapid shared updates are more valuable than repeatability, following latest may be a reasonable choice, provided somebody watches the changes and can respond. Neither setting makes an agent reliable by itself. A Profile gives configuration a shared home and a version history. It does not automatically test your workflow, freeze every caller input, or tell you whether a new setup is better for your users.

That boundary is the useful story in Perplexity's September 28 update. Profiles now sit beside versioned Skills and managed connectors. Perplexity says Profiles and custom Skills are available for Agent API projects; managed connectors are in preview. Skills and connectors did not both begin on September 28. Perplexity had announced Skills in July and the first four managed connectors in August. The September update adds the reusable Profile layer and names six connectors in the current catalog. This article focuses on the practical release decision Profiles create.

The release decision: Pin a tested Profile version when callers need an explainable baseline. Follow latest only when owners intend shared changes to reach every caller and have a way to evaluate and respond. A Profile version alone does not freeze request overrides or application behavior.

What a Profile actually packages

A Profile is a reusable, versioned configuration that Perplexity stores and manages. Current Profile documentation says it can bundle the model or model fallback chain, system instructions, reasoning effort, tools, Skills, managed connectors and agent-loop step budget under one ID. A request can then refer to that ID instead of resending the same configuration every time.

Think of the Profile as a named release record for the agent's operating recipe. It can reduce drift caused by separately copied instruction blocks, tool lists and runtime settings across several application codebases. If two applications intentionally use the same Profile version, their requests start from the same saved defaults. If an administrator edits the Profile, Perplexity creates another immutable version instead of silently altering the old version.

That is meaningful infrastructure. It is also narrower than the phrase “reusable agent” can suggest. The Profile stores configuration, not your application's full behavior. A calling application still supplies the particular user input and may supply request-level parameters. It still controls surrounding code, output parsing, retries, access to application data and what happens after the agent responds. The Profile is one stable component in a system, not a guarantee that two applications will behave identically end to end.

This matters when someone asks, “Which agent handled this?” The useful answer is more than a friendly Profile name. You want the Profile ID and version, caller version, request parameters, input or a privacy-safe input fingerprint, tool invocations, response, and the evaluation or review record tied to that release. A reusable ID helps establish provenance only when the calling application preserves enough context to interpret the run.

What changed on September 28

The vendor announcement frames the update as a project-level reuse layer. An administrator can configure a Profile and make it available to authorized developers in the same project. Skills package reusable procedures and supporting files. Managed connectors supply service integrations configured by an administrator. Together, those resources can be reused from multiple applications without rebuilding every element in each codebase.

The announcement says custom Skills and Profiles are available now, while managed connectors are in preview. The named connector set is GitHub, Slack, Google Drive, Datadog, Linear and Notion. The current connector documentation lists those same six. Earlier coverage of the rollout that listed only four reflects an earlier snapshot: GitHub, Slack, Google Drive and Datadog were announced first, before Linear and Notion appeared in the current catalog.

Independent coverage of the September announcement is still mostly summary rather than hands-on validation. Revenue Hub LatAm described the same Profile, Skills and connector update the next day. That helps confirm the announcement is being reported outside Perplexity, but it does not verify account availability, security properties, reliability, or the productivity examples in the launch post. The practical advice here is based on current vendor documentation and clearly labeled operational reasoning, not a test of a Perplexity account.

A Profile and a Skill also do different jobs. A Profile groups the settings that shape a run. A Skill is a reusable procedure and supporting material that a team can attach or invoke. A Profile can include Skills, but the terms are not interchangeable. If a team only needs to share a procedure, it may not need a new Profile. If it needs a stable bundle of model, tool and runtime choices, a Profile is the relevant unit to version.

Pinning versus following latest

Perplexity's Profile docs document two ways to select a Profile: pin a specific numeric version or use the moving latest reference. Because each saved version is immutable, a call pinned to version 3 continues to use that exact configuration even after an administrator creates version 4. A call using latest resolves to whatever version is current when the request is admitted. A later edit can therefore change what future calls receive without a code change in every application.

Pinning is useful when you need a reproducible production baseline, when an agent's output can trigger consequential decisions, or when several teams must coordinate before a change. It makes the deployment change visible: someone updates the Profile reference or its pinned version, and that change can be reviewed and tied to an evaluation. It also provides a practical rollback path. If version 4 misbehaves, return the caller to the previously tested version 3 while investigating.

The cost is operational ceremony. Someone must decide when a new version is ready, update the release reference, and make sure each application moves on purpose. If the Profile changes frequently, strict pinning can leave teams on old behavior unless the release process has an owner and a cadence. A pinned Profile also does not freeze caller overrides or application code. You can preserve one shared configuration version and still change request fields, tool options, user context, preprocessing, or downstream actions outside that Profile.

Following latest removes a manual version bump from the application. That can help a prototype, an internal workflow with a small blast radius, or a centrally governed service where operators want all callers to receive the newest shared setup. But an administrator changing the Profile then changes the effective defaults for callers following latest. The moment of change is still a deployment, even if it happened in a console rather than a code release. Treat it like one: announce it, record it, monitor representative outcomes and know how to reverse it.

A useful default for a growing team is to pin in production and use a controlled lane for evaluation. That is not a Perplexity requirement. It is a release-management recommendation based on the documented version behavior. There are cases where latest is a better fit, but “the API supports it” is not itself a reason to let every production request float.

Three release choices: pin a tested version, evaluate a candidate, then promote deliberately or return to the prior version.

The hidden change paths around the Profile

A version pin provides a boundary, not complete reproducibility. Perplexity's Profile documentation says request parameters can override Profile values. It also specifies a special behavior for tools: tools supplied in the request merge per tool rather than replacing the whole set. That means the actual run configuration can be the Profile plus caller-side changes.

This is convenient when one application needs a small, explicit adjustment. It also creates a review question: which fields are permitted to vary outside the shared Profile? If one service silently changes reasoning effort, model, tool choices or step budget, logging only the Profile version will give an incomplete explanation of the run. The right answer is not to forbid all overrides. It is to make them visible, intentional and testable.

Start by identifying three layers in your own implementation. The first is the saved Profile: the common baseline. The second is request configuration: parameters the caller can override and tools it can merge. The third is the application behavior: prompt assembly, input filtering, response validation, retry policy and downstream effects. Keep a concise record of the first two with each request, and version the third in the same deployment record as your application.

A good rollout question is not only “Did we update the Profile?” Ask “What changed for this request compared with the last successful one?” A diff might show a new instruction or model, another connector, a new Skill version, a larger step budget, a caller's override, or a changed application prompt. These changes have different owners and test paths. Grouping them into one release note labeled “agent updated” makes later diagnosis harder. NIST's 2025 workshop summary on agent tool use proposes describing tools by access patterns, write permissions, risk, reversibility and monitoring. That is a useful vocabulary for a Profile change review, not an evaluation of Perplexity Profiles themselves.

Perplexity's Profile error documentation notes that problems such as an invalid ID, inaccessible Profile, unsupported model, or invalid version fail with a 4xx response before the run starts. Handle that as a distinct failure class in your application. It is not the same as a completed run returning a weak answer or a connector timing out after admission. Your operational dashboard should distinguish admission/configuration errors from in-run tool failures and from output validation failures.

A practical release lane

You do not need a huge platform team to make a versioned Profile useful. You do need a small repeatable path from change to adoption.

First, name the workflow and identify its user-visible job. “Support helper” is too broad. “Classify a billing-support message, gather approved account context, and propose a reply for a human to approve” gives the team something observable to test. Record where a human must intervene and what the system must not do.

Second, keep a representative evaluation set. Include ordinary cases, ambiguous cases, missing-information cases and adversarial or out-of-scope inputs. Save expected properties rather than brittle exact wording: the response cites the correct source, includes required fields, asks for missing information, and does not trigger an unapproved action. The test set should be small enough to run on every candidate and broad enough to expose obvious regressions. This is a proposed practice, not a capability delivered automatically by Profiles.

Third, create a candidate Profile version and capture exactly what changed. Evaluate it in a nonproduction lane using the same relevant tools and Skills where practical, but with test accounts or harmless data. Compare the candidate against the currently pinned version. Review differences that matter to users: unsupported certainty, missing citations, added tool calls, longer response time, changed output structure or refusal behavior. Do not equate a cleaner prompt with a better operational result unless the evaluation demonstrates that.

Fourth, promote deliberately. Pin a test application to the candidate version first. If the evaluation passes, update the production caller's Profile version in a reviewed release. If you choose latest instead, announce the Profile edit as the production change, record which callers follow latest, and monitor the same evaluation cases or a privacy-safe sample after the update. Keep the previous version available as the return point.

Fifth, make ownership clear. The person who edits a Profile does not necessarily own every application that uses it. Maintain an inventory of callers, owners, pinned versions and override policies. Before an edit, notify the affected owners. After a promotion, record the evaluation date, candidate and prior versions, decision, unresolved limitations and rollback reference. This is basic change management applied to a shared configuration resource.

A practical rollout lane moves from configuration diff to evaluation, staging, promotion and rollback.

Worked example: a support triage agent

Imagine a company building an internal support triage tool. One application receives email from a help form. Another gives agents a panel inside the company's operations workspace. Both use a model, shared instructions, a read-only lookup tool and a structured output contract. The company wants the two applications to use the same policy language and escalation rules, but each application has a different interface and passes different case context.

A team could place common agent settings into a Profile. It might attach a Skill with the triage procedure and configure the required tools. Each application would select the same Profile ID and pinned version. The email intake could supply ticket text and account ID; the operations panel could supply the open ticket and the operator's selected context. The Profile helps centralize common configuration. The application still has to enforce which user can view a case, what account data may be sent, how output is validated, and whether a response remains a draft.

For version 1, test a known set of anonymized support cases. Check whether each output uses allowed categories, quotes a relevant policy source, identifies uncertainty and requests missing details. Confirm that a tool failure produces a safe fallback and does not invent a lookup result. Then draft a version 2 that changes one meaningful instruction. Run the same cases. If the new version changes category behavior, review the cases where it changed and decide whether those changes were intended.

Now compare rollout choices. If the applications are handling real customer requests, pinning both to version 1 while version 2 is evaluated gives the team an explainable baseline. The internal panel can test version 2 with staff first, then both applications can move after approval. If the workflow is only an internal prototype used by three developers, following latest may be simpler, as long as those developers know a Profile edit changes the shared behavior. These are examples of a decision method, not a report that such a Perplexity configuration was created or tested.

The example also reveals a common mistake: centralizing the instructions but leaving their duplicates in application prompts. If application A still adds a local paragraph that says “always close the ticket,” while the shared Profile instructs the agent only to recommend closure, the outputs will diverge. A Profile cannot remove duplicated policy logic that lives outside it. Search your callers for those remnants, then either move truly shared behavior into the Profile or keep it as an explicit application-specific rule.

The change-control checklist

Before a Profile change reaches a consequential workflow, answer these questions:

Which Profile ID and version does each application use today?
Does any caller select latest?
Which request-side parameters can override Profile values, and are overrides logged?
Are caller-supplied tools merged with Profile tools? Which combination does each application actually send?
What changed between the previous and candidate Profile versions?
Which test cases represent normal, ambiguous and out-of-scope use?
How will a reviewer inspect a materially changed answer or tool trace?
Does an invalid or inaccessible Profile produce a safe application response?
Who approves promotion, and who can roll the caller back?
What record lets the team reconstruct the effective configuration for a past request?

If those answers are not available, the immediate next step is not necessarily to abandon Profiles. It is to add enough configuration visibility to answer them. A shared resource can make consistency easier, but it can also widen the impact of a small edit. The point of versioning is to make changes easier to control, not merely easier to distribute.

Common rollout mistakes

One mistake is pinning the Profile and assuming the whole application is pinned. It is not. The app can still change its input template, add tools, override fields or reinterpret the response. Tie the Profile version to an application release and log request-level deltas.

Another is using latest because “it is versioned.” Version history only helps if the team can identify which version ran and react when a new one becomes active. If nobody owns the update, latest simply moves the release decision out of the code review where application developers may notice it.

A third is testing the prompt in isolation. The Profile may include tools, Skills and connectors that alter the behavior of an actual run. A prompt-only review can catch confusing instructions, but it does not test tool access, tool result handling, response schema or downstream actions. Evaluate the full workflow on representative safe cases.

A fourth is changing several elements at once. A new model, instruction rewrite, extra connector and larger step budget can each alter the result. When possible, change one major dimension at a time so your evaluation can explain what caused a behavior shift. When the change must be bundled, say so and expand the review around the interactions.

A fifth is treating success as a good demo. One happy-path request proves that one request completed. It does not show that version pinning works across all callers, that the output remains stable on edge cases or that the rollback path is ready. A small case set and an explicit release record are more useful than a polished screenshot.

FAQs

What is a Perplexity Agent API Profile?

A Profile is a reusable, versioned configuration for an Agent API run. Current docs say it can bundle the model or fallback chain, instructions, reasoning effort, tools, Skills, managed connectors and loop step budget under an ID.

Should production applications use a pinned version or latest?

Pin a tested numeric version when repeatability, review and rollback matter. Use latest when centrally shared changes should reach callers automatically and the team has monitoring and ownership. That is an operational recommendation; the API supports both patterns.

Does pinning a Profile make the full request reproducible?

No. Request parameters can override Profile settings, and tools supplied by the request merge per tool. The application can also change its own input preparation, validation and downstream behavior. Record those layers with the Profile version.

What happens if the Profile ID or version is invalid?

Perplexity documents that Profile problems such as an invalid ID, inaccessible Profile, unsupported model or invalid version fail with a 4xx error before the run starts. Your application should handle that separately from an in-run failure.

Did Perplexity launch Skills and connectors on September 28?

No. Skills and managed connectors existed earlier. The September 28 announcement adds Profiles and describes the three resources as a reusable layer. The current announcement and connector docs list six managed connectors, which are marked as preview.

Are there independent performance results for Profiles?

The sources reviewed for this article contain no independent test showing Profile adoption improves reliability, output quality, cost or team speed. Treat those as outcomes to measure for your own workload. If cost is part of the decision, our guide to measuring the cost of an accepted AI task explains why token rates alone do not settle it.

A configuration failure, a tool failure and a weak answer are different events with different recovery paths.

The release choice belongs to the operator

For production, a useful default is to pin a tested Profile version, evaluate candidates before promotion and record request overrides alongside the pin. Latest can suit a monitored prototype or a centrally operated service whose owners deliberately accept shared changes. The API supports both options; your release process must make the consequences visible. Start by listing which callers pin a version, which follow latest, and what each request can still override. That gives every evaluation and rollback a clear starting point. It does not prove a candidate is better, but it tells the team what changed and what to test.

The companion question is what a shared agent can reach. Our guide to Perplexity Agent API connector access examines the project-level boundary and connected-service permissions. For the broader application ownership question, see Should Your Team Build an Internal App with Copilot Code?. Together, the decisions are clearer: version the shared configuration, then define who may call it and what those callers may reach.

Checked for this article