pi-tavily

Official Tavily extension for the Pi coding agent.

Published package name:

@tavily/pi-extension

Install in Pi with:

pi install npm:@tavily/pi-extension

What it adds

This extension adds two Tavily-powered tools to Pi:

• web_search — search the web with Tavily Search
• web_fetch — extract content from one or more URLs with Tavily Extract

Authentication

v1 uses an API key via environment variable:

export TAVILY_API_KEY=tvly-...

OAuth / Pi-native login flow is not included yet.

Install

From npm

pi install npm:@tavily/pi-extension

Local development

From this repo:

npm install
pi -e ./index.ts

Isolated local testing

To test only this extension without other skills/extensions interfering:

pi --no-session --no-skills --no-prompt-templates --no-context-files --no-extensions -e ./index.ts

Example prompts

Search

Search the web for the latest Tavily announcements.

Search the web for recent Tavily news from the last month. Use news topic, advanced depth, include an answer, and include favicons.

Search the web for the exact phrase "Tavily Search" and exclude reddit.com.

Fetch / extract

Fetch https://docs.tavily.com and summarize it.

Fetch these pages and compare them:
https://docs.tavily.com/documentation/api-reference/endpoint/search
https://docs.tavily.com/documentation/api-reference/endpoint/extract

Fetch these URLs and extract only content relevant to API credits and pricing:
https://docs.tavily.com/documentation/api-reference/endpoint/search
https://docs.tavily.com/documentation/api-reference/endpoint/extract

Tool behavior

web_search

Backed by Tavily Search.

Supports the full v1 parameter surface defined in docs/tool-contract.md, including:

• search_depth
• topic
• time_range
• start_date / end_date
• include_domains / exclude_domains
• include_answer
• include_raw_content
• include_images
• include_favicon
• auto_parameters
• exact_match
• include_usage

web_fetch

Backed by Tavily Extract.

Supports the full v1 parameter surface defined in docs/tool-contract.md, including:

• urls
• query
• chunks_per_source
• extract_depth
• format
• include_images
• include_favicon
• timeout
• include_usage

Validation rules

The extension currently enforces a few important contract rules:

• web_search.chunks_per_source requires search_depth: "advanced"
• web_search.country is only valid with topic: "general"
• web_fetch.chunks_per_source requires query
• web_fetch allows a maximum of 20 URLs

Notes

• Public Pi tool parameters use Tavily-style snake_case.
• For deep page extraction, prefer web_search to discover URLs first, then web_fetch to extract selected pages.
• Large outputs may be truncated for Pi context safety, with the full output saved to a temp file.

Releasing

See RELEASING.md for the local test, packaging, and npm publish workflow.

Contract

The public tool contract for v1 lives here:

• docs/tool-contract.md

Repository name vs package name

This repository is named pi-tavily, while the published npm package is:

@tavily/pi-extension