Pi Tavily Search

A production-oriented Pi extension for Tavily web search with strict context budgets, source URLs, prompt-injection guidance, and out-of-context raw artifacts.

Why this exists

Unbounded web-search results can consume an agent's context window. Real-world testing of the original extension found individual Tavily tool results as large as 13MB, mainly because raw page content entered both the model-visible result and persisted details.

This package keeps useful search evidence in context while moving complete raw responses to private temporary files that Pi can inspect incrementally.

Features

• tavily_search tool with basic, advanced, fast, and ultra-fast modes.
• 8KB maximum model-visible output per call.
• 16KB shared budget across parallel searches in one Pi turn.
• Five results by default, ten maximum.
• Raw page content never enters chat output or tool details.
• Complete responses saved as 0600 temporary JSON artifacts when raw content is requested or the digest is truncated.
• Session and stale-artifact cleanup.
• Search results explicitly marked as untrusted external data.
• Google-compatible string-enum schema.
• Commands for status, default depth, and artifact cleanup.

Requirements

• Pi coding agent 0.80.6 or later.
• Node.js 22 or later.
• A Tavily API key for normal keyed access.

Installation

Recommended npm installation:

pi install npm:@windrunner20/pi-tavily-search

Pin the stable v1.0.0 release for reproducible installations:

pi install npm:@windrunner20/pi-tavily-search@1.0.0

Alternatively, install the tagged GitHub source:

pi install git:github.com/Windrunner20/pi-tavily-search@v1.0.0

Restart Pi after installation. To try without installing:

pi -e npm:@windrunner20/pi-tavily-search@1.0.0

For local development:

pi install /absolute/path/to/pi-tavily-search

Configuration

API key

The extension checks these locations in order:

1. TAVILY_API_KEY
2. $PI_CODING_AGENT_DIR/tavily-api-key
3. ~/.tavily-api-key

Normally Pi's agent directory is ~/.pi/agent, so a private key file can be created with:

install -m 600 /dev/null ~/.pi/agent/tavily-api-key
printf '%s\n' 'tvly-YOUR-KEY' > ~/.pi/agent/tavily-api-key
chmod 600 ~/.pi/agent/tavily-api-key

The key is sent only to https://api.tavily.com/search in the Authorization: Bearer header.

• TAVILY_REQUEST_TIMEOUT_MS — request deadline in milliseconds, clamped to 100–120000; default 30000

Default search depth

Set it for the current process:

export TAVILY_SEARCH_DEPTH=basic

Or use Pi:

/tavily-depth advanced

The command writes $PI_CODING_AGENT_DIR/tavily-search.json.

Precedence:

1. TAVILY_SEARCH_DEPTH
2. tavily-search.json
3. basic

Tool interface

tavily_search({
  query: string,                    // 1-400 characters
  search_depth?: "basic" | "advanced" | "fast" | "ultra-fast",
  max_results?: integer,            // 1-10, default 5
  include_answer?: boolean,         // default true
  include_raw_content?: boolean,    // default false
  include_images?: boolean          // default false
})

Example request the model may issue:

{
  "query": "Pi coding agent extension documentation",
  "search_depth": "advanced",
  "max_results": 5,
  "include_answer": true,
  "include_raw_content": false
}

Commands

/tavily-status

Reports whether an API key is available and displays the active default search depth.

/tavily-depth [depth]

Displays or changes the default depth:

/tavily-depth
/tavily-depth basic
/tavily-depth advanced
/tavily-depth fast
/tavily-depth ultra-fast

/tavily-clean

Deletes raw-response artifacts created by the current session.

Context and artifact behavior

Compact output

The model sees:

• a warning that the content is untrusted;
• a clipped Tavily answer;
• titles, URLs, relevance scores, and clipped snippets;
• at most 8KB per call;
• at most 16KB across searches in one turn.

If parallel searches reserve the full turn budget, later searches are skipped rather than overflowing context.

Raw output

When include_raw_content is true, Tavily receives include_raw_content: "markdown", but raw page content is not returned to the model. The complete response is written to a path like:

/tmp/pi-tavily-XXXXXX/result.json

The JSON begins with an explicit untrusted-content warning. Pi can use its read tool with offset and limit to inspect the artifact incrementally.

Artifacts:

• are created with mode 0600;
• are removed on clean session shutdown;
• can be removed manually with /tavily-clean;
• are considered stale and removed after 24 hours on session start.

Security

Web pages can contain prompt-injection text. This extension adds both system-level guidance and a result-level warning telling the model to treat search content only as evidence, never as instructions.

This is defense in depth, not a guarantee. Review SECURITY.md before deploying the package in environments with secrets or powerful tools.

Development

npm ci
npm run typecheck
npm test
npm run pack:check

Optional live Tavily test:

TAVILY_API_KEY=tvly-... npm run test:integration

Run the complete offline release gate:

npm run check

Compatibility and versioning

The stable v1 interface consists of:

• tool name tavily_search;
• commands tavily-status, tavily-depth, and tavily-clean;
• documented environment variables and config files;
• bounded output and private-artifact behavior.

Breaking these contracts requires a new major version.

License

MIT