AI agents without search access hallucinate outdated information. Adding a search tool takes under 10 minutes and gives your agent real-time web access. This beginner-friendly tutorial walks through getting an API key, making your first search call, and integrating search into a basic agent loop. Scavio offers 250 free searches per month, so you can build and test without spending anything.
Prerequisites
- Python 3.9+ or Node.js 18+ installed
- A free Scavio API key from scavio.dev
- 10 minutes of time
Walkthrough
Step 1: Get your API key and make your first search
Sign up at scavio.dev for a free API key (250 searches/month included). Then make your first search call.
Python
import requests, os
# Set your API key as an environment variable:
# export SCAVIO_API_KEY=your-key-here
API_KEY = os.environ['SCAVIO_API_KEY']
# Your first search
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={
'x-api-key': API_KEY,
'Content-Type': 'application/json'
},
json={
'query': 'what is an AI agent',
'country_code': 'us',
'num_results': 5
})
results = resp.json().get('organic_results', [])
print(f'Search returned {len(results)} results:\n')
for r in results:
print(f' {r["title"]}')
print(f' {r["link"]}')
print(f' {r.get("snippet", "")[:100]}...')
print()Step 2: Wrap it in a reusable search function
Create a clean search function you can use throughout your project. This is the function your agent will call.
Python
def search(query: str, count: int = 5) -> list:
"""Search the web and return structured results."""
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': 'us', 'num_results': count})
if resp.status_code != 200:
print(f'Search error: {resp.status_code}')
return []
results = resp.json().get('organic_results', [])
return [{
'title': r['title'],
'url': r['link'],
'snippet': r.get('snippet', '')
} for r in results]
# Test it
results = search('best python libraries 2026')
for r in results:
print(f'{r["title"]}: {r["url"]}')
print(f'\nCost: $0.005 per search, {250} free/month')Step 3: Build a simple agent loop with search
Create a basic agent that decides when to search and uses results to answer questions. This is the foundation for any search-augmented agent.
Python
def simple_agent(question: str) -> str:
"""A basic agent that searches before answering."""
print(f'Question: {question}')
# Step 1: Search for relevant information
results = search(question, count=3)
if not results:
return 'I could not find any search results for that question.'
# Step 2: Build context from search results
context = '\n'.join(
f'- {r["title"]}: {r["snippet"][:150]}'
for r in results
)
# Step 3: Format the answer (in a real agent, send to LLM)
answer = f'Based on {len(results)} search results:\n\n{context}'
answer += f'\n\nSources:\n'
for r in results:
answer += f' - {r["url"]}\n'
return answer
# Ask the agent a question
answer = simple_agent('What are the best Python web frameworks in 2026?')
print(answer)
print(f'\nTotal cost: $0.005 (1 search query)')Python Example
Python
import requests, os
API_KEY = os.environ['SCAVIO_API_KEY']
def search(query, count=5):
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': 'us', 'num_results': count})
return [{'title': r['title'], 'url': r['link'], 'snippet': r.get('snippet', '')}
for r in resp.json().get('organic_results', [])]
results = search('what is an AI agent')
for r in results:
print(f'{r["title"]}: {r["url"]}')
print(f'\nFree tier: 250 searches/month')JavaScript Example
JavaScript
const API_KEY = process.env.SCAVIO_API_KEY;
async function search(query, count = 5) {
const resp = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST',
headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ query, country_code: 'us', num_results: count })
});
const data = await resp.json();
return (data.organic_results || []).map(r => ({
title: r.title, url: r.link, snippet: r.snippet || ''
}));
}
search('what is an AI agent').then(results => {
results.forEach(r => console.log(`${r.title}: ${r.url}`));
console.log(`\nFree tier: 250 searches/month`);
});Expected Output
JSON
Search returned 5 results:
What Is an AI Agent? - IBM
https://www.ibm.com/topics/ai-agents
An AI agent is a software program that can interact with its environment...
AI Agents Explained - Microsoft
https://learn.microsoft.com/en-us/ai/agents
AI agents are autonomous systems that perceive, decide, and act...
Based on 3 search results:
- What Is an AI Agent? - IBM: An AI agent is a software program...
- AI Agents Explained - Microsoft: AI agents are autonomous systems...
Total cost: $0.005 (1 search query)
Free tier: 250 searches/month