OpenCode: Perplexity Agent Setup Guide

Raw

Perplexity Agent Setup Guide

Before using these agents, you must have a valid API key from Perplexity AI. This key is required to authenticate requests through OpenCode.

🧰 Prerequisites

Create or log into your account on Perplexity AI.
Navigate to Settings → API → API keys and generate an API key.
Log in to OpenCode:
```
opencode auth login
```
When prompted, select perplexity and paste your Perplexity API key. OpenCode will securely store and use it for all agent requests.

Provider Configuration (opencode.json)

"perplexity": {
  "npm": "@ai-sdk/perplexity",
  "name": "Perplexity AI",
  "options": {
    "baseURL": "https://api.perplexity.ai"
  },
  "models": {
    "sonar-deep-research": {
      "name": "Perplexity Sonar Deep Research"
    }
  }
}

OpenCode Agent

.opencode/agent/ .md files (https://opencode.ai/docs/agents/)

Perplexity Researcher (perplexity-researcher.md)

Model: perplexity/sonar

Purpose: Comprehensive search and analysis capabilities using Perplexity AI's sonar model for real-time information queries, multi-source research requiring synthesis and citation, comparative analysis across products or concepts, topic exploration needing comprehensive background, or fact verification with source attribution.

Key Capabilities:

Multi-source information gathering with automatic citation
Query optimization for precise results
Source credibility assessment
Real-time data access and processing
Structured markdown responses with inline citations
Visual elements (tables, lists, code blocks) for clarity

Usage Examples:

Real-time information queries (e.g., latest developments in AI safety research)
Comparative analysis (e.g., React vs Vue.js frameworks)
Fact verification with citations

Perplexity Researcher Pro (perplexity-researcher-pro.md)

Model: perplexity/sonar-pro

Purpose: Complex research requiring deeper analysis, multi-step reasoning, and sophisticated source evaluation for technical, academic, or specialized domain queries needing expert-level analysis, high-stakes decisions, or multi-layered problem solving.

Key Capabilities:

Multi-step logical analysis and inference
Cross-domain knowledge synthesis
Complex pattern recognition and trend analysis
Enhanced fact-checking with multiple source verification
Bias detection and balanced perspective presentation
Technical documentation analysis with code examples
Academic rigor with methodology evaluation

Usage Examples:

Technical security analysis (e.g., quantum computing implications for encryption)
Academic research evaluation (e.g., CRISPR gene editing ethics)

Perplexity Researcher Reasoning (perplexity-researcher-reasoning.md)

Model: perplexity/sonar-reasoning

Purpose: Research with explicit logical reasoning, step-by-step analysis, and transparent decision-making processes for problems requiring diagnostic thinking, troubleshooting, educational contexts, or verification tasks where understanding the reasoning path is crucial.

Key Capabilities:

Step-by-step logical progression
Assumption identification and validation
Inference rule application and justification
Alternative path exploration and evaluation
Transparent analysis with intermediate conclusions
Reasoning verification with self-consistency checking

Usage Examples:

Troubleshooting queries (e.g., code compilation errors)
Decision-making analysis (e.g., microservices vs monolithic architecture)

Perplexity Researcher Reasoning Pro (perplexity-researcher-reasoning-pro.md)

Model: perplexity/sonar-reasoning-pro

Purpose: Highest level of research and reasoning capabilities for complex decision-making with significant consequences, strategic planning, technical architecture decisions, multi-stakeholder problems, or high-complexity troubleshooting requiring expert-level judgment and sophisticated reasoning chains.

Key Capabilities:

Hierarchical reasoning with primary and secondary effects
Cross-domain reasoning and meta-reasoning
Bayesian reasoning with probability updates
Decision theory and utility analysis
Risk assessment and mitigation strategies
Integration of contradictory evidence
Confidence interval estimation

Usage Examples:

Technical architecture decisions (e.g., microservices migration)
Strategic planning (e.g., AI adoption implications)

Perplexity Researcher Deep (perplexity-researcher-deep.md)

Model: perplexity/sonar-deep-research

Purpose: Thorough, exhaustive research requiring extensive multi-source analysis and comprehensive coverage for detailed reports, white papers, literature reviews, in-depth market analysis, or knowledge base articles prioritizing depth and completeness.

Key Capabilities:

Multi-angle topic exploration with 10+ source synthesis
Historical context and evolution tracking
Root cause analysis and underlying mechanism exploration
Second and third-order effects consideration
Long-form content with multiple section organization
Comprehensive reference integration
Thematic organization and detailed examples

Usage Examples:

White paper creation (e.g., future of quantum computing)
In-depth market analysis (e.g., cloud storage competitive landscape)

✅ Quick Reference — File Mapping

Agent	Model	File
Perplexity Researcher	`perplexity/sonar`	`perplexity-researcher.md`
Perplexity Researcher Pro	`perplexity/sonar-pro`	`perplexity-researcher-pro.md`
Perplexity Researcher Reasoning	`perplexity/sonar-reasoning`	`perplexity-researcher-reasoning.md`
Perplexity Researcher Reasoning Pro	`perplexity/sonar-reasoning-pro`	`perplexity-researcher-reasoning-pro.md`
Perplexity Researcher Deep	`perplexity/sonar-deep-research`	`perplexity-researcher-deep.md`

Raw

perplexity-opencode-advanced-configuration.md

Perplexity Agent Configuration: Advanced Options

This document extends the Perplexity Agent Setup Guide with additional configuration options and best practices.

Language Filtering Configuration

Overview

Perplexity's search_language_filter parameter allows you to restrict search results to specific languages, ensuring more relevant results for your use case.

Syntax and Parameters

Parameter name: search_language_filter
Type: Array of strings
Format: ISO 639-1 two-letter language codes (lowercase)
Maximum: Up to 10 language codes per request
Example codes:
- en - English
- de - German
- fr - French
- es - Spanish
- zh - Chinese
- ja - Japanese
- it - Italian
- pt - Portuguese
- ru - Russian
- ko - Korean

Configuration Levels

You can configure language filtering at three different levels in OpenCode:

1. Global Provider Level

Apply language filter to all Perplexity models:

{
  "provider": {
    "perplexity": {
      "npm": "@ai-sdk/perplexity",
      "name": "Perplexity AI",
      "options": {
        "baseURL": "https://api.perplexity.ai",
        "search_language_filter": ["en", "de"]
      },
      "models": {
        "sonar": { "name": "Perplexity Sonar" },
        "sonar-pro": { "name": "Perplexity Sonar Pro" }
      }
    }
  }
}

Use case: When all your research needs are in specific languages.

2. Per-Model Level

Override global settings for specific models:

{
  "provider": {
    "perplexity": {
      "npm": "@ai-sdk/perplexity",
      "name": "Perplexity AI",
      "options": {
        "baseURL": "https://api.perplexity.ai"
      },
      "models": {
        "sonar": {
          "name": "Perplexity Sonar",
          "options": {
            "search_language_filter": ["en"]
          }
        },
        "sonar-pro": {
          "name": "Perplexity Sonar Pro",
          "options": {
            "search_language_filter": ["en", "de", "fr"]
          }
        },
        "sonar-deep-research": {
          "name": "Perplexity Sonar Deep Research",
          "options": {
            "search_language_filter": ["de"]
          }
        }
      }
    }
  }
}

Use case: Different models for different language research tasks.

3. Agent-Level Configuration

Configure filters for specific agents in .opencode/agent/*.md files:

---
description: "German-focused technical research agent"
model: perplexity/sonar-pro
options:
  search_language_filter: ["de", "en"]
  search_recency_filter: "month"
tools:
  webfetch: true
  read: true
  write: true
  edit: true
permissions:
  edit: ask
  bash: deny
---

You are a specialized research agent focused on German technical documentation...

Use case: Specialized agents for specific language domains or regions.

Additional Search Filters

Combine language filtering with other Perplexity search parameters:

Search Recency Filter

Limit results by time period:

{
  "options": {
    "search_language_filter": ["en", "de"],
    "search_recency_filter": "day"
  }
}

Valid values: hour, day, week, month, year

Search Domain Filter

Restrict results to specific domains:

{
  "options": {
    "search_language_filter": ["en"],
    "search_domain_filter": ["arxiv.org", "github.com", "stackoverflow.com"]
  }
}

Use case: Academic research, code repositories, or technical documentation.

Combined Filters Example

{
  "model": "perplexity/sonar-pro",
  "provider": {
    "perplexity": {
      "npm": "@ai-sdk/perplexity",
      "name": "Perplexity AI",
      "options": {
        "baseURL": "https://api.perplexity.ai"
      },
      "models": {
        "sonar-pro": {
          "name": "Perplexity Sonar Pro",
          "options": {
            "search_language_filter": ["en", "de"],
            "search_domain_filter": ["github.com", "docs.rs", "crates.io"],
            "search_recency_filter": "month"
          }
        }
      }
    }
  }
}

Use case: Rust development research focusing on recent documentation in English and German.

Agent Configuration Best Practices

1. Language-Specific Agent Setup

Create dedicated agents for different language contexts:

.opencode/agent/perplexity-researcher-de.md:

---
description: "German technical documentation and news research"
model: perplexity/sonar-pro
options:
  search_language_filter: ["de"]
  search_recency_filter: "week"
tools:
  webfetch: true
  read: true
permissions:
  edit: ask
  bash: deny
---

You are a German-language research specialist...

.opencode/agent/perplexity-researcher-multilingual.md:

---
description: "Multilingual research with European language focus"
model: perplexity/sonar-pro
options:
  search_language_filter: ["en", "de", "fr", "es"]
tools:
  webfetch: true
  read: true
permissions:
  edit: ask
  bash: deny
---

You are a multilingual research agent...

2. Model Selection by Use Case

Use Case	Recommended Model	Language Filter Strategy
Quick fact-checking	`sonar`	Single language for fastest results
Technical analysis	`sonar-pro`	2-3 languages for comprehensive coverage
Reasoning tasks	`sonar-reasoning`	Primary language only for clearer logic
Complex problem-solving	`sonar-reasoning-pro`	1-2 languages to maintain reasoning clarity
Comprehensive research	`sonar-deep-research`	3-5 languages for thorough coverage

3. Priority Configuration

OpenCode loads model configuration in this priority order:

Command line flag: opencode --model perplexity/sonar-pro
Agent-level options (in .opencode/agent/*.md)
Model-level options (in opencode.json)
Provider-level options (in opencode.json)
Global defaults

Tip: Use global settings for common preferences, model-level for specialized tasks, and agent-level for specific use cases.

Complete Configuration Example

Here's a complete opencode.json configuration with language filtering:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "perplexity/sonar-pro",
  "provider": {
    "perplexity": {
      "npm": "@ai-sdk/perplexity",
      "name": "Perplexity AI",
      "options": {
        "baseURL": "https://api.perplexity.ai",
        "search_language_filter": ["de", "en"]
      },
      "models": {
        "sonar": {
          "name": "Perplexity Sonar",
          "options": {
            "search_language_filter": ["en"]
          }
        },
        "sonar-pro": {
          "name": "Perplexity Sonar Pro",
          "options": {
            "search_language_filter": ["en", "de", "fr"]
          }
        },
        "sonar-reasoning": {
          "name": "Perplexity Sonar Reasoning",
          "options": {
            "search_language_filter": ["en"]
          }
        },
        "sonar-reasoning-pro": {
          "name": "Perplexity Sonar Reasoning Pro",
          "options": {
            "search_language_filter": ["en", "de"]
          }
        },
        "sonar-deep-research": {
          "name": "Perplexity Sonar Deep Research",
          "options": {
            "search_language_filter": ["en", "de", "fr", "es"]
          }
        }
      }
    }
  }
}

Use Case Examples

Example 1: German-Only Technical Research

Configuration:

{
  "options": {
    "search_language_filter": ["de"],
    "search_domain_filter": ["heise.de", "golem.de", "t3n.de"]
  }
}

Use case: Researching German tech news and documentation.

Example 2: Multilingual Academic Research

Configuration:

{
  "options": {
    "search_language_filter": ["en", "de", "fr"],
    "search_domain_filter": ["arxiv.org", "scholar.google.com", "researchgate.net"],
    "search_recency_filter": "year"
  }
}

Use case: Academic literature review across European languages.

Example 3: Code Documentation Search

Configuration:

{
  "options": {
    "search_language_filter": ["en"],
    "search_domain_filter": ["docs.rs", "crates.io", "github.com", "stackoverflow.com"],
    "search_recency_filter": "month"
  }
}

Use case: Rust programming research with recent documentation.

Troubleshooting

Language Filter Not Working

Check API key configuration: Ensure you've logged in with opencode auth login
Verify JSON syntax: Invalid JSON in opencode.json will be ignored
Check model support: All Sonar models support language filtering
Restart OpenCode: Configuration changes require a restart

Conflicting Configurations

When multiple configuration levels exist:

Agent-level overrides model-level
Model-level overrides provider-level
Provider-level overrides defaults

Use opencode --verbose to see which configuration is being applied.

Performance Considerations

Fewer languages = faster results: Limiting to 1-2 languages improves response time
More languages = broader coverage: 3-5 languages for comprehensive research
Balance specificity: Too restrictive filters may miss relevant results

Additional Resources

Quick Reference: ISO 639-1 Language Codes

Language	Code	Language	Code
English	en	German	de
French	fr	Spanish	es
Italian	it	Portuguese	pt
Dutch	nl	Russian	ru
Chinese	zh	Japanese	ja
Korean	ko	Arabic	ar
Polish	pl	Turkish	tr
Swedish	sv	Danish	da
Norwegian	no	Finnish	fi

Raw

perplexity-researcher-pro.md

description

mode

model

tools

permissions

Complex research requiring deeper analysis, multi-step reasoning, and sophisticated source evaluation for technical, academic, or specialized domain queries needing expert-level analysis, high-stakes decisions, or multi-layered problem solving.

subagent

perplexity/sonar-pro

webfetch	write	edit	read
true	true	true	true

edit	bash
ask	deny

You are the Perplexity Researcher Pro, utilizing the perplexity/sonar-pro model for advanced research and analysis.

Key Capabilities

Multi-step logical analysis and inference
Cross-domain knowledge synthesis
Complex pattern recognition and trend analysis
Enhanced fact-checking with multiple source verification
Bias detection and balanced perspective presentation
Technical documentation analysis with code examples
Academic rigor with methodology evaluation

Usage Examples

Technical security analysis (e.g., quantum computing implications for encryption)
Academic research evaluation (e.g., CRISPR gene editing ethics)

Conduct thorough, multi-step analysis, verify facts across sources, and provide expert-level insights with balanced perspectives.

d-oit/perplexity-opencode-advanced-configuration.md

Perplexity Agent Setup Guide

🧰 Prerequisites

Provider Configuration (opencode.json)

OpenCode Agent

Perplexity Researcher (perplexity-researcher.md)

Perplexity Researcher Pro (perplexity-researcher-pro.md)

Perplexity Researcher Reasoning (perplexity-researcher-reasoning.md)

Perplexity Researcher Reasoning Pro (perplexity-researcher-reasoning-pro.md)

Perplexity Researcher Deep (perplexity-researcher-deep.md)

Perplexity Agent Configuration: Advanced Options

Language Filtering Configuration

Overview

Syntax and Parameters

Configuration Levels

1. Global Provider Level

2. Per-Model Level

3. Agent-Level Configuration

Additional Search Filters

Search Recency Filter

Search Domain Filter

Combined Filters Example

Agent Configuration Best Practices

1. Language-Specific Agent Setup

2. Model Selection by Use Case

3. Priority Configuration

Complete Configuration Example

Use Case Examples

Example 1: German-Only Technical Research

Example 2: Multilingual Academic Research

Example 3: Code Documentation Search

Troubleshooting

Language Filter Not Working

Conflicting Configurations

Performance Considerations

Additional Resources

Quick Reference: ISO 639-1 Language Codes

Key Capabilities

Usage Examples