Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
Perplexity Search (perplexitySearch)
| Field | Value |
|---|---|
| Category | search / tool (dual-purpose) |
| Backend handler | server/nodes/search/perplexity_search/__init__.py - PerplexitySearchNode; dispatched via BaseNode.execute() + the @Operation("search") method (Wave 11; the old server/services/handlers/search.py::handle_perplexity_search is deleted) |
| Tests | server/tests/nodes/test_search.py |
| Skill (if any) | server/skills/web_agent/perplexity-search-skill/SKILL.md |
| Dual-purpose tool | yes - tool name perplexity_search (usable_as_tool = True) |
Purpose
AI-generated answer with inline citations from Perplexity Sonar models. The node returns an LLM completion plus the citation URLs Perplexity used so downstream nodes can render references or follow the sources.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream data; not consumed directly |
Parameters
(Pydantic PerplexitySearchParams, model_config = {"extra": "ignore"}.)
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
tool_name |
string | perplexity_search |
no | - | Tool name when exposed to AI |
tool_description |
string | (see Params) | no | - | Tool description for AI |
query |
string | (none) | yes | - | Question for the model (min_length=1) |
model |
enum | sonar |
no | - | One of sonar / sonar-pro / sonar-reasoning / sonar-reasoning-pro |
search_recency_filter |
enum | all |
no | - | One of all / month / week / day / hour (all = off, not sent) |
return_images |
boolean | false |
no | - | When true, request images from the API |
return_related_questions |
boolean | false |
no | - | When true, request related questions from the API |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | Answer + citations payload |
Output payload
PerplexitySearchOutput:
{
query: string;
answer: string; // markdown content from choices[0].message.content
citations: string[]; // URLs the model cited
results: Array<{ url: string }>; // citations remapped as result objects
images: dict[] | null; // data.images verbatim (null when API omits it)
related_questions: string[] | null; // data.related_questions verbatim (null when API omits it)
model: string; // echoes the model param
provider: 'perplexity';
}
Wrapped by BaseNode._serialize_result in the standard envelope. Shared runtime schema: SearchOutput in server/services/node_output_schemas.py.
Logic Flow
flowchart TD
A[BaseNode.execute -> PerplexitySearchNode.search] --> B{Pydantic validates params}
B -- query missing --> Eret[NodeUserError -> success=false<br/>error: invalid parameters]
B -- ok --> C[Build body: model + messages role=user content=query]
C --> D{search_recency_filter != 'all'?}
D -- yes --> E[Add search_recency_filter to body]
D -- no --> F{return_images?}
E --> F
F -- yes --> G[body.return_images=true]
F --> H{return_related_questions?}
G --> H
H -- yes --> I[body.return_related_questions=true]
H --> J[ctx.connection 'perplexity'<br/>injects Authorization: Bearer]
I --> J
J --> K[POST api.perplexity.ai/chat/completions]
K -- raise_for_status fails --> Estat[Exception -> success=false envelope]
K -- 2xx --> L[answer = data.choices 0 .message.content or empty]
L --> M[citations = data.citations or empty list]
M --> N[results = list of url-only objects]
N --> O[images/related_questions = data.get verbatim]
O --> P[Operation cost spec: service=perplexity action=sonar_search count=1]
P --> Q[Return PerplexitySearchOutput]
Decision Logic
- Validation: Pydantic on
PerplexitySearchParams. Empty / missingquery(min_length=1) is rejected before the operation body (invalid parametersfailure envelope). - Optional body fields:
search_recency_filteris added only when!= 'all';return_images/return_related_questionsare added only when truthy.search_recency_filter='all'is the explicit "off" value. - Empty
choices:answerfalls back to''rather than raising. - Optional response fields:
images/related_questionsare set verbatim fromdata.get(...)- they areNonewhen the API omits them (noif x:gating; this differs from the deleted pre-Wave-11 handler which only included them when non-empty).
Side Effects
- Database writes: one
api_usage_metricsrow per call via the@Operationcost spec (service='perplexity',action='sonar_search',count=1). - Broadcasts: per-node status via
BaseNode.execute; no plugin-specific broadcasts. - External API calls:
POST https://api.perplexity.ai/chat/completionsviactx.connection. - File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials:
PerplexityCredential(ApiKeyCredential, idperplexity, bearer auth). Its_probeshort-circuits toProbeResult(valid=True)- Perplexity has no cheap auth-gated validation endpoint, so a bad key only surfaces as a runtime 401. - Services:
ctx.connection, framework cost tracking. - Python packages:
httpx(via Connection facade).
Edge cases & known limits
- Sonar Reasoning models can be slow; the Connection facade's default timeout governs (no per-call override in the plugin body, unlike the old handler's explicit 60s).
- Citations field shape can vary across Perplexity response versions (
list[str]historically). The plugin assumeslist[str]; a list-of-objects response passes through to the output unchanged but breaks theresultsmapping ({'url': <obj>}). - The
resultslist is purely a citations remap; downstream nodes expectingtitle/snippetwill not find them - usebraveSearchorserperSearchfor those.
Related
- Skills using this as a tool:
perplexity-search-skill/SKILL.md - Companion nodes:
braveSearch,serperSearch - Architecture docs: Plugin System, Pricing Service