Amplifier Bundle: Perplexity Research

May 31, 2026 · View on GitHub

Deep web research capabilities for Amplifier using Perplexity's Agentic Research API.

Highlights

Categorized References with URLs for Follow-Up Research

Unlike basic search, this bundle returns structured, categorized references that downstream agents can use for deeper investigation:

## References

### Academic Sources
- [1] HEMA: A Hippocampus-Inspired Extended Memory Architecture...
  URL: https://arxiv.org/abs/2504.16754
- [2] Episodic Retrieval in Cognitive Science...
  URL: https://pmc.ncbi.nlm.nih.gov/articles/PMC1074338/

### News & Industry
- [3] AI Emulates Brain's Memory Replay...
  URL: https://neurosciencenews.com/place-cell-ai-learning-23202/

### Documentation
- [4] Memory Architecture Implementation Guide
  URL: https://github.com/example/memory-arch

---
Tokens: 7756

Why this matters: Other agents can use web_fetch on these URLs to dive deeper into specific sources. The research-expert agent includes a Deep Dive Suggestions table prioritizing which sources merit follow-up:

PrioritySourceURLInvestigation Focus
Higharxiv paper[URL]Full methodology section
MediumGitHub repo[URL]Benchmark comparisons

Domain-Specific Query Enhancement

The research-expert agent intelligently adapts queries based on your domain context:

You SayAgent Does
"from neuroscience perspective"Adds domain terms, prioritizes academic sources
"recent 2024-2025 papers"Adds time constraints, notes publication dates
"industry perspective"Includes analyst reports, market coverage
User: "Research AI memory architectures from a neuroscience angle"

Agent uses:
  query: "AI memory architectures inspired by hippocampus and biological neural systems"
  instructions: "Prioritize peer-reviewed neuroscience journals and computational 
                 neuroscience sources. Focus on biological mechanisms."

Installation

This bundle ships its capability as a thin behavior (behaviors/perplexity-research.yaml) that contributes only the research tool, the research-expert agent, and the cost-aware context — it does not include amplifier-foundation. That means you can layer it on top of your existing app without pulling foundation in a second time. The full root bundle (bundle.md) is also available as a standalone that bundles foundation + behavior together.

Layers Perplexity research on top of your active bundle — no duplicate foundation:

amplifier bundle add git+https://github.com/colombod/amplifier-bundle-perplexity@main#subdirectory=behaviors/perplexity-research.yaml --app

Standalone — dedicated session with foundation included

Creates a new perplexity bundle configuration (includes foundation):

amplifier bundle add git+https://github.com/colombod/amplifier-bundle-perplexity@main
amplifier bundle use perplexity

# Verify installation
amplifier bundle list

Compose into your own bundle

Add to your bundle's includes:. Use the behavior path so you don't pull foundation twice:

includes:
  - bundle: git+https://github.com/colombod/amplifier-bundle-perplexity@main#subdirectory=behaviors/perplexity-research.yaml

One-time use (no install)

# Run with the bundle directly (one-time use)
amplifier run --bundle git+https://github.com/colombod/amplifier-bundle-perplexity@main "Research quantum computing breakthroughs"

Environment Setup

Required. This bundle needs a Perplexity API key to function. The perplexity_research tool resolves its key at mount time as:

api_key = config.get("api_key") or os.environ.get("PERPLEXITY_API_KEY")

If neither is set, the bundle still installs, but the tool refuses to mount and emits: Perplexity research tool not mounted: PERPLEXITY_API_KEY not set. Set the key before you expect any research calls to work.

export PERPLEXITY_API_KEY=pplx-xxxxx

Or persist it in your shell profile (~/.bashrc, ~/.zshrc):

echo 'export PERPLEXITY_API_KEY="pplx-xxxxx"' >> ~/.bashrc
source ~/.bashrc

Option B: Bundle/tool config

If you prefer not to use the environment, provide the key via the tool's config.api_key (e.g. through settings.yaml overrides or a composing bundle). Reference the env var rather than hardcoding the literal key so the secret never lands in version control:

overrides:
  tool-perplexity-search:
    config:
      api_key: ${PERPLEXITY_API_KEY}

Secret handling — do not commit your key

  • Never hardcode the literal pplx-... key into bundle files, settings.yaml, recipes, or profiles that get committed. Use the environment variable, or reference it via ${PERPLEXITY_API_KEY}.
  • When testing in an isolated environment (e.g. the Digital Twin Universe profile shipped under .amplifier/digital-twin-universe/), the key is forwarded from your host environment at launch via the profile's passthrough.services block — only the env-var name (PERPLEXITY_API_KEY) lives in the committed profile, never the value.

Quick Start

After installation:

# Start interactive session with perplexity bundle
amplifier

# In the session, delegate research to the expert agent:
> Delegate to perplexity:research-expert to research the latest advances in fusion energy

Or use the tool directly:

# Single research query
amplifier run "Use perplexity_research to find information about CRISPR breakthroughs in 2025"

Features

  • Deep Research Tool: Multi-step web research with categorized citations via perplexity_research
  • Research Expert Agent: Domain-aware research with structured handoff for downstream agents
  • Categorized References: Sources grouped by type (Academic, News, Docs, Other) with extractable URLs
  • Deep Dive Suggestions: Prioritized follow-up recommendations for agents with web_fetch
  • Cost-Aware Guidance: Token-based pricing (~10-15k tokens typical)
  • Stuck-detection nudge: Conservative hook that nudges toward perplexity:research-expert when a session is genuinely looping (see below)

Stuck-detection nudge (optional, on by default)

The bundle ships a hook (hooks-perplexity-nudge) that watches for sessions spinning in circles and injects a single, short <system-reminder> suggesting the agent pause and delegate to perplexity:research-expert to get authoritative information before continuing.

It is deliberately conservative. The nudge fires only when there is a high-confidence objective signal of being stuck:

SignalThreshold
Repeated identical error in tool results≥ 2 times (configurable)
Same tool + same args called in a loop≥ 3 times (configurable)
Struggle phrase ("I'm stuck", "still failing", …) and no successful tool result after—

It is suppressed in all of the following cases (conservative defaults):

  • enabled: false in config — silences the hook entirely
  • Within the 6-turn cooldown after the last injection
  • After 3 injections per session (hard cap)
  • When perplexity_research or research-expert already appears in the recent window
  • When the most recent tool result is a successful, content-bearing result (> 200 chars, non-error) — the session already has knowledge and is making progress

Tuning or disabling

Override any value via the behavior config. To disable completely:

# In your bundle's overrides or settings.yaml:
overrides:
  hooks-perplexity-nudge:
    config:
      enabled: false

To tune conservatism:

overrides:
  hooks-perplexity-nudge:
    config:
      cooldown_turns: 10   # Wait longer between nudges
      max_injections: 1    # Only nudge once per session
      scan_depth: 8        # Look at more recent context

Usage

Direct Tool Use

Use the perplexity_research tool to find current information about quantum computing breakthroughs in 2025.

Delegate to perplexity:research-expert to research AI from a neuroscience perspective, focusing on hippocampus-inspired architectures.

The agent will:

  1. Enhance your query with domain-specific terms
  2. Set appropriate source preferences via instructions
  3. Return categorized references for follow-up
  4. Provide Deep Dive Suggestions for downstream agents

Chaining with Follow-Up Research

After getting research results, use the categorized URLs for deeper investigation:

Based on the research results, use web_fetch on the High-priority academic sources 
to extract the full methodology sections.

Recipes

# Deep research with verification
amplifier tool invoke recipes operation=execute \
  recipe_path=perplexity:recipes/deep-research.yaml \
  context='{"research_question": "What are the latest developments in fusion energy?"}'

# Fact-checking
amplifier tool invoke recipes operation=execute \
  recipe_path=perplexity:recipes/fact-check.yaml \
  context='{"claims": "Claim 1\nClaim 2\nClaim 3"}'

Cost Awareness

Token-based pricing (~10-15k tokens typical per query). Each response includes token count for tracking.

When to Use Deep Research

  • Complex questions requiring synthesis from multiple sources
  • Current events, news, or rapidly changing topics
  • Fact-checking with verified citations
  • Market research, competitive analysis
  • Domain-specific research (neuroscience, academic, industry angles)

When to Use Free Alternatives

  • Simple factual lookups → use web_search
  • Static/historical information → use web_search
  • Code documentation → use existing docs

Components

Tool: perplexity_research (embedded)

Deep research using Perplexity's /v1/responses API. The tool code is embedded in this bundle.

Parameters:

  • query (required): Research question
  • mode: auto (default), research, chat — API mode selection
  • model: sonar-pro (default), sonar, sonar-reasoning — model for chat mode
  • reasoning_effort: low, medium (default), high
  • max_steps: 1-10 (default: 5)
  • instructions: Source preferences, domain focus, time constraints

Output Features:

  • Main research content with inline citations [1], [2]
  • Categorized References section (Academic, News, Docs, Other)
  • Each reference includes full URL for web_fetch
  • Token count for cost tracking

Agent: perplexity:research-expert

Specialized research agent with:

  • Advanced Query Formulation: Domain-aware query enhancement
  • Source Preferences: Uses instructions parameter for targeted research
  • Categorized Output: References grouped by source type
  • Deep Dive Suggestions: Prioritized URLs for downstream agent follow-up
  • Cost-Benefit Framework: Knows when deep research is worth it

Recipes

RecipePurposeEst. Cost
deep-research.yamlMulti-step research with verification~$0.10-0.50
fact-check.yamlVerify claims with tiered approach~$0.05-0.30

URL Categorization

The tool automatically categorizes sources:

CategoryDetected Domains
Academicarxiv.org, doi.org, pubmed, nature.com, ieee.org, .edu, scholar.google
News & Industrytechcrunch, wired, bloomberg, reuters, medium, substack
Documentationgithub.com, docs., api., developer.*
OtherEverything else

API Reference

Perplexity Endpoints Used

EndpointPurpose
/v1/responsesAgentic research (this bundle)
/v1/chat/completionsStandard chat (separate provider module)

Modes & Models

ModeAPIDescription
autoResearch → Chat fallbackDefault. Tries research first, falls back to chat on quota/rate limits
researchAgentic Research APIDeep, multi-step research with autonomous source discovery
chatChat Completions APIFaster, cheaper queries when deep research isn't needed

Chat mode models (model parameter, only applies when mode is chat or auto falls back to chat):

ModelStrengthUse When
sonar-proComprehensiveDefault. Strong search and retrieval
sonarFastQuick lookups, simple queries
sonar-reasoningReasoningComplex analysis requiring multi-step reasoning
  • amplifier-module-provider-perplexity: LLM provider for chat completions (separate module for using Perplexity as your AI backend)

License

MIT

Contributing

Issues and PRs welcome at https://github.com/colombod/amplifier-bundle-perplexity