# Trace: Replace and Improve Web Search with Tavily API

Agent: pi | Model: Claude Sonnet 4.6 | Project: .pi

---

## User

https://docs.tavily.com/welcome

## Assistant

Here's a summary of what's on the **Tavily Docs Welcome page** at `https://docs.tavily.com/welcome`:

---

## 🔍 Tavily — Web Search for AI

Tavily provides a suite of web APIs designed for AI/LLM applications. Here's what's available:

### Installation
- **Python SDK:** `pip install tavily-python`
- **JavaScript SDK:** `npm i @tavily/core`

---

### Core APIs

| API | Description | Example |
|-----|-------------|---------|
| **Search** | Search the web | `tavily_client.search("Who is Leo Messi?")` |
| **Extract** | Extract content from a specific URL | `tavily_client.extract("https://en.wikipedia.org/...")` |
| **Crawl** | Crawl a site with natural language instructions | `tavily_client.crawl("https://docs.tavily.com", instructions="...")` |
| **Map** | Map all pages of a website | `tavily_client.map("https://docs.tavily.com")` |
| **Research** | Run an autonomous research task | `tavily_client.research("Latest developments in AI?")` |

---

### Developer Resources
- **API Credits Overview** — How credits are consumed
- **Rate Limits** — Policies and limits
- **Playground** — Interactive API testing
- **LLMs.txt** — Guidance for LLM integrations
- **Status Page** — Service health
- **Community** — Support and discussion

---

All APIs use a simple client pattern: instantiate `TavilyClient` with your API key (`tvly-YOUR_API_KEY`) and call the relevant method. Would you like to dive deeper into any specific API or integrate Tavily into a project?

## User

can you add this to your web search functionality, replacing duckduckog?

## Assistant

Let me read the relevant skill files first to understand the current setup.

## Assistant

Now I need to know your Tavily API key to proceed. Do you have one? If so, I'll update the skill to use Tavily's Search API instead of DuckDuckGo.

A few options for storing the key:
1. **Environment variable** — `TAVILY_API_KEY` in your shell profile (recommended)
2. **A local config file** — e.g. `~/.pi/agent/skills/web-search/.env`

Which do you prefer, and what's your API key?

## User

shell profile is fine

## Assistant

What's your Tavily API key?

## User

i will add it ogm

## Assistant

No problem! Once you've added `TAVILY_API_KEY` to your shell profile, I'll update the skill. Let me do that now.

## Assistant

Done! Here's what changed:

- **`search.js`** — now calls the Tavily `/search` API (`POST https://api.tavily.com/search`) using your `TAVILY_API_KEY` env var, with the same `-n` flag for result count
- **`SKILL.md`** — updated description and added the `TAVILY_API_KEY` requirement

Once you've added the key to your shell profile and reloaded it (`source ~/.bashrc` / `source ~/.zshrc`), it'll work automatically.

## User

try it out

## Assistant

Works perfectly! Tavily returned 5 clean results with titles, URLs, and snippets. The API key is set correctly and the switch from DuckDuckGo is fully working. 🎉

## User

https://docs.tavily.com/documentation/api-reference/introduction

go deeper into this and prepare a better search tool. only search, no extra tools

## Assistant

The page is JS-rendered. Let me fetch the actual search API endpoint docs directly via the Tavily API itself, and also try a curl approach to get the raw content.

## Assistant

Now I have a solid picture of all the parameters. Let me write the improved search tool:

## Assistant

Now let's test a few of the new options:

## Assistant

Works beautifully. Here's what was upgraded:

### New flags added
| Flag | What it does |
|------|-------------|
| `-d <depth>` | `basic` / `advanced` / `fast` / `ultra-fast` — controls latency vs. relevance |
| `-t <topic>` | `general` / `news` / `finance` — topic-scoped search |
| `-r <range>` | `day` / `week` / `month` / `year` — time filter |
| `--answer` | Includes Tavily's AI-generated answer at the top |
| `--raw` | Returns raw page content per result |
| `--include <d,d>` | Restrict results to specific domains |
| `--exclude <d,d>` | Block specific domains from results |
| `--json` | Dumps the full raw JSON response |

Also now uses the proper `Authorization: Bearer` header (the new auth standard from the docs), and shows a relevance `score` per result.

## User

Try it out again

## Assistant

Working great! The advanced depth, news topic, weekly time range, and AI answer all fired correctly. Results are fresh (Feb 26–27, 2026) with relevance scores per result. The tool is solid.