L'ancrage de recherche donne aux agents IA un accès aux données web en temps réel pour qu'ils cessent d'halluciner des faits obsolètes. Ce modèle fonctionne avec tout framework d'agent Python : avant que le LLM génère une réponse, interrogez une API de recherche pour obtenir des résultats pertinents et injectez-les dans le contexte du prompt. Ce tutoriel présente une approche indépendante du framework utilisant l'API Scavio, qui fonctionne que vous utilisiez OpenAI, Anthropic, LangChain ou une simple boucle Python. À $0.005 par recherche, l'ancrage ajoute moins d'un centime par tour d'agent.
Prérequis
- Python 3.9+ installé
- bibliothèque requests installée
- Une clé API Scavio depuis scavio.dev
- Toute clé API LLM (OpenAI, Anthropic, etc.)
Parcours
Étape 1: Créer la fonction d'ancrage de recherche
Créez une fonction réutilisable qui prend une requête et renvoie un contexte formaté. Cette fonction devient le pont entre votre agent et les données web en direct.
import requests, os
API_KEY = os.environ['SCAVIO_API_KEY']
def ground_with_search(query: str, max_results: int = 5) -> str:
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'})
resp.raise_for_status()
results = resp.json().get('organic_results', [])[:max_results]
context = '\n'.join(
f'[{r["position"]}] {r["title"]}\n {r.get("snippet", "")}\n Source: {r["link"]}'
for r in results
)
return f'Search results for: {query}\n\n{context}'Étape 2: Injecter l'ancrage dans tout modèle de prompt
Enveloppez votre prompt existant avec le contexte de recherche. Les données d'ancrage sont placées avant la question de l'utilisateur pour que le LLM puisse les référencer.
def build_grounded_prompt(user_question: str) -> str:
search_context = ground_with_search(user_question)
return f"""Use the following search results to answer accurately.
Do not make up information not present in the results.
{search_context}
Question: {user_question}
Answer:"""
prompt = build_grounded_prompt('What is the latest Python version in 2026?')
print(prompt[:500])Étape 3: Utiliser directement avec OpenAI / Anthropic
Passez le prompt ancré à n'importe quelle API LLM. Cet exemple montre les modèles OpenAI et Anthropic.
# With OpenAI:
from openai import OpenAI
client = OpenAI()
def ask_grounded_openai(question: str) -> str:
prompt = build_grounded_prompt(question)
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': prompt}],
max_tokens=500
)
return response.choices[0].message.content
# With Anthropic:
import anthropic
client_a = anthropic.Anthropic()
def ask_grounded_anthropic(question: str) -> str:
prompt = build_grounded_prompt(question)
msg = client_a.messages.create(
model='claude-sonnet-4-20250514',
max_tokens=500,
messages=[{'role': 'user', 'content': prompt}]
)
return msg.content[0].textÉtape 4: Utiliser comme outil LangChain
Si vous utilisez LangChain, enveloppez la fonction de recherche comme un outil afin que l'agent puisse l'appeler de manière autonome lorsqu'il a besoin de données actuelles.
from langchain.tools import tool
@tool
def web_search(query: str) -> str:
"""Search the web for current information. Use this when you need
up-to-date facts, prices, or recent events."""
return ground_with_search(query)
# Register with any LangChain agent:
# agent = create_react_agent(llm, tools=[web_search], ...)Étape 5: Ajouter un cache pour réduire les recherches en double
Dans les conversations à plusieurs tours, l'agent peut rechercher la même chose deux fois. Un simple cache TTL évite les appels API en double.
from functools import lru_cache
import hashlib
_cache = {}
def cached_ground(query: str, ttl_seconds: int = 300) -> str:
import time
key = hashlib.md5(query.encode()).hexdigest()
if key in _cache:
result, timestamp = _cache[key]
if time.time() - timestamp < ttl_seconds:
return result
result = ground_with_search(query)
_cache[key] = (result, time.time())
return result
# First call hits API, second returns cached result
ctx1 = cached_ground('python 3.14 release date')
ctx2 = cached_ground('python 3.14 release date') # cached, no API call
print(f'Cache size: {len(_cache)} entries')Exemple Python
import os, requests
API_KEY = os.environ['SCAVIO_API_KEY']
def ground_with_search(query: str, max_results: int = 5) -> str:
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'})
resp.raise_for_status()
results = resp.json().get('organic_results', [])[:max_results]
return '\n'.join(
f'[{r["position"]}] {r["title"]}\n {r.get("snippet", "")}\n Source: {r["link"]}'
for r in results
)
def build_grounded_prompt(question: str) -> str:
ctx = ground_with_search(question)
return f'Use these search results to answer accurately:\n\n{ctx}\n\nQuestion: {question}\nAnswer:'
def main():
question = 'What is the latest Python version in 2026?'
prompt = build_grounded_prompt(question)
print(prompt)
print(f'\nGrounding cost: $0.005 per search')
if __name__ == '__main__':
main()Exemple JavaScript
const API_KEY = process.env.SCAVIO_API_KEY;
async function groundWithSearch(query, maxResults = 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' })
});
const data = await resp.json();
return (data.organic_results || []).slice(0, maxResults)
.map(r => `[${r.position}] ${r.title}\n ${r.snippet || ''}\n Source: ${r.link}`)
.join('\n');
}
async function main() {
const question = 'What is the latest Python version in 2026?';
const context = await groundWithSearch(question);
const prompt = `Use these results to answer:\n\n${context}\n\nQ: ${question}\nA:`;
console.log(prompt);
console.log('\nGrounding cost: $0.005 per search');
}
main().catch(console.error);Sortie attendue
Search results for: What is the latest Python version in 2026?
[1] Python Release Python 3.14.0
Python 3.14.0 was released on April 15, 2026 with experimental JIT...
Source: https://www.python.org/downloads/release/python-3140/
[2] What's New In Python 3.14
This article explains the new features in Python 3.14...
Source: https://docs.python.org/3/whatsnew/3.14.html
Grounding cost: $0.005 per search