0d7b606311
Detailed setup guide covering API key registration, build-time and runtime configuration, search flow, pricing tiers, rate limits, and common troubleshooting steps.
6.8 KiB
Tavily Web Search Configuration Guide
Tavily is a real-time search engine designed for AI agents and RAG workflows. MimiClaw uses Tavily as the preferred web search provider (with Brave Search as a fallback).
Table of Contents
- Overview
- Getting an API Key
- Configuring MimiClaw
- How It Works in MimiClaw
- API Details
- Pricing
- Rate Limits
- Troubleshooting
Overview
MimiClaw's web_search tool allows the AI agent to search the internet for real-time information. When a Tavily API key is configured, MimiClaw will use Tavily as the search provider. If no Tavily key is set but a Brave Search key exists, it falls back to Brave Search.
Why Tavily?
- Purpose-built for AI agents — returns clean, structured results
- Includes relevance scoring for each result
- Supports advanced search depth for higher quality results
- 1,000 free API credits per month (no credit card required)
Getting an API Key
- Sign up at app.tavily.com
- Create an account — you can sign in with Google or email
- Copy your API key — it starts with
tvly-and is available on the dashboard immediately - The free Researcher plan gives you 1,000 API credits per month with no credit card required
Your API key will look like: tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Configuring MimiClaw
There are two ways to configure the Tavily API key:
Option 1: Build-time Configuration (Recommended for First Setup)
- Copy the secrets template if you haven't already:
cp main/mimi_secrets.h.example main/mimi_secrets.h
- Edit
main/mimi_secrets.hand set your Tavily key:
#define MIMI_SECRET_TAVILY_KEY "tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
- Rebuild the firmware:
idf.py fullclean && idf.py build
- Flash to your ESP32-S3:
idf.py -p PORT flash monitor
Option 2: Runtime Configuration via Serial CLI
Connect to the UART (COM) port and run:
mimi> set_tavily_key tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
This saves the key to NVS flash and takes effect immediately — no rebuild needed. Runtime values override build-time defaults.
Verify Configuration
Check that the key is set:
mimi> config_show
You should see tavily_key: tvly-**** (masked) in the output.
How It Works in MimiClaw
When the AI agent needs to search the web, it calls the web_search tool. MimiClaw selects the search provider with this priority:
1. Tavily (if MIMI_SECRET_TAVILY_KEY is set) <-- preferred
2. Brave Search (if MIMI_SECRET_SEARCH_KEY is set)
3. No search available (tool returns error)
The search flow:
User asks a question requiring web info
|
v
Agent decides to call web_search tool
|
v
MimiClaw sends POST to https://api.tavily.com/search
- Authorization: Bearer tvly-xxxxx
- Body: {"query": "...", "max_results": 5, "search_depth": "basic"}
|
v
Tavily returns structured results
|
v
Agent incorporates results into response
Each basic search costs 1 API credit. With the free plan's 1,000 credits/month, that's about 33 searches per day.
API Details
MimiClaw uses the Tavily Search API endpoint:
| Parameter | Value |
|---|---|
| Endpoint | POST https://api.tavily.com/search |
| Auth | Authorization: Bearer <API_KEY> |
| Content-Type | application/json |
Request Body (as sent by MimiClaw)
| Field | Type | Value | Description |
|---|---|---|---|
query |
string | (from agent) | The search query |
max_results |
integer | 5 |
Number of results to return |
search_depth |
string | "basic" |
Search depth (basic = 1 credit) |
Response Fields
| Field | Type | Description |
|---|---|---|
query |
string | The executed search query |
results |
array | Ranked search results |
results[].title |
string | Result title |
results[].url |
string | Source URL |
results[].content |
string | Summary snippet |
results[].score |
float | Relevance score (0-1) |
response_time |
float | Execution time in seconds |
HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request — invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 429 | Rate Limit — too many requests |
| 432 | Plan Limit — monthly quota exceeded |
| 500 | Server Error |
Pricing
Tavily offers a generous free tier and several paid plans:
| Plan | Monthly Credits | Cost | Per-Credit Rate |
|---|---|---|---|
| Researcher | 1,000 | Free | -- |
| Project | 4,000 | $30 | $0.0075 |
| Bootstrap | 15,000 | $100 | $0.0067 |
| Startup | 38,000 | $220 | $0.0058 |
| Growth | 100,000 | $500 | $0.005 |
| Pay-as-you-go | Variable | $0.008/credit | $0.008 |
Credit costs per search:
basicsearch depth: 1 creditadvancedsearch depth: 2 credits
MimiClaw uses basic by default, so each search = 1 credit.
Rate Limits
| Environment | Limit |
|---|---|
| Development | 100 requests per minute |
| Production | 1,000 requests per minute |
For an ESP32-based agent, you will never hit these limits in practice.
Troubleshooting
"No search provider configured"
The agent returns this when neither Tavily nor Brave Search keys are set.
Fix: Set a Tavily API key via set_tavily_key CLI command or in mimi_secrets.h.
Search returns empty results
- Verify your API key is correct:
config_showshould showtavily_key: tvly-**** - Check your monthly credit balance at app.tavily.com
- Ensure the ESP32 has internet access:
wifi_status
HTTP 401 Unauthorized
Your API key is invalid or expired. Generate a new one at app.tavily.com.
HTTP 432 Plan Limit
You've exceeded your monthly credit quota. Wait for the next billing cycle or upgrade your plan.
Search works but results are poor
Tavily's basic search depth is optimized for speed. The quality is generally sufficient for an AI agent's needs. If you need higher quality, you can modify SEARCH_RESULT_COUNT in tool_web_search.c.