Cách thêm Web Search thời gian thực vào agent OpenAI hoặc Claude trong 4 bước

Muốn agent của bạn dựa câu trả lời trên thông tin hiện tại? Bạn cần đúng hai thứ: một API tìm kiếm trả về các snippet sẵn sàng cho LLM, và một định nghĩa tool mà mô hình có thể gọi. Hướng dẫn này làm cả hai trong 4 bước.
Tóm tắt
- •Bước 1: lấy một API key (miễn phí) và thử endpoint bằng curl.
- •Bước 2: lấy tool schema OpenAI/Claude trực tiếp từ API — không viết JSON bằng tay.
- •Bước 3: đăng ký tool với agent của bạn (OpenAI Assistants, Anthropic Messages, LangChain hoặc n8n).
- •Bước 4: triển khai tool handler gọi /api/search/web và trả kết quả về cho mô hình.
Vì sao bài này ngắn
Phần lớn các hướng dẫn \"thêm web search vào LLM của bạn\" rất dài vì thực chất chúng là hướng dẫn về một SDK API tìm kiếm hoặc một framework agent nặng nề. Bài này thì không. Toàn bộ công việc là: chọn một endpoint, đăng ký nó làm tool, viết một handler 5 dòng.
1Lấy một API key (miễn phí) và gọi endpoint
Đăng ký tại apipick.com/dashboard/api-keys. Tài khoản mới nhận 100 credits miễn phí — không cần thẻ tín dụng. Tạo một key và thử endpoint:
curl -X POST https://www.apipick.com/api/search/web \
-H "x-api-key: pk_yourkey" \
-H "Content-Type: application/json" \
-d '{"query": "what is retrieval augmented generation"}'Bạn sẽ nhận lại một danh sách nhỏ đã xếp hạng gồm tiêu đề, URL và snippet. Xác nhận nó hoạt động trong curl giúp tiết kiệm thời gian debugging về sau.
2Lấy tool schema (đừng viết bằng tay)
API Pick cung cấp các tool schema sẵn sàng dán tại GET /api/search/web/tool-schema. Phản hồi bao gồm cả một định nghĩa function theo kiểu OpenAI lẫn một định nghĩa tool use của Claude.
curl https://www.apipick.com/api/search/web/tool-schemaHãy cache kết quả — nó không thay đổi giữa các lần gọi. Viết function schema bằng tay là nguồn bug phổ biến nhất trong code agent (sai type, sai required fields, thiếu description).
3Đăng ký tool với agent của bạn
OpenAI Assistants
from openai import OpenAI
import requests
client = OpenAI()
schema = requests.get("https://www.apipick.com/api/search/web/tool-schema").json()
assistant = client.beta.assistants.create(
name="Research Agent",
model="gpt-4o",
instructions="Use web_search whenever the user asks about current events or anything that changes after your training cutoff.",
tools=[{"type": "function", "function": schema["openai"]}],
)Anthropic Claude
import anthropic
import requests
schema = requests.get("https://www.apipick.com/api/search/web/tool-schema").json()
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=[schema["claude"]],
messages=[{"role": "user", "content": "Summarise this week's RAG research."}],
)LangChain
from langchain.tools import tool
import requests
@tool
def web_search(query: str) -> dict:
"""Real-time web search. Use for any question that needs current information."""
return requests.post(
"https://www.apipick.com/api/search/web",
headers={"x-api-key": "pk_yourkey"},
json={"query": query},
).json()n8n
Thêm một node HTTP Request: method POST, URL https://www.apipick.com/api/search/web, header x-api-key: pk_yourkey, body JSON {"query": "{{ $json.query }}"}. Kết nối nó vào node agent hoặc LLM Chain của bạn. Không cần SDK.
4Xử lý lệnh gọi tool
Với OpenAI Assistants, khi run tạm dừng với trạng thái requires_action, hãy chạy tìm kiếm và gửi output:
import json, time, requests
from openai import OpenAI
client = OpenAI()
KEY = "pk_yourkey"
def run_with_tool(thread_id: str, assistant_id: str):
run = client.beta.threads.runs.create(thread_id=thread_id, assistant_id=assistant_id)
while True:
run = client.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)
if run.status == "requires_action":
outputs = []
for call in run.required_action.submit_tool_outputs.tool_calls:
if call.function.name == "web_search":
args = json.loads(call.function.arguments)
result = requests.post(
"https://www.apipick.com/api/search/web",
headers={"x-api-key": KEY},
json=args,
).json()
outputs.append({"tool_call_id": call.id, "output": json.dumps(result)})
client.beta.threads.runs.submit_tool_outputs(
thread_id=thread_id, run_id=run.id, tool_outputs=outputs,
)
elif run.status in ("completed", "failed", "cancelled", "expired"):
return run
time.sleep(0.5)Vòng lặp của Anthropic Messages API cũng tương tự — khi phản hồi chứa một khối tool_use, hãy gọi API, rồi gửi kết quả trở lại dưới dạng khối nội dung tool_result ở lượt tiếp theo.
Siết chặt vòng lặp
- Đặt mô tả tool theo góc nhìn của mô hình: \"Use this when the user asks about current events, breaking news, or anything that may have changed after your training cutoff.\" Đừng nói \"đây là một API web search\".
- Cache kết quả trong handler khi cùng một query xuất hiện hai lần trong một phiên. Kết quả web search ổn định trong ~vài phút; bạn không cần trả 15 credits hai lần trong cùng một cuộc hội thoại.
- Thêm bộ lọc
start_datekhi độ mới quan trọng. \"Tin tức tuần này\" mà không có bộ lọc ngày thường trả về các tiêu đề của năm ngoái.
Đi tiếp đâu
Khi agent của bạn đã tìm kiếm được, bước tiếp theo tự nhiên là đọc các trang được liên kết. Thêm URL Content Extraction API làm tool thứ hai — cùng auth, cùng hình thức JSON, tối đa 25 URL mỗi lệnh gọi. Bộ đôi \"search + extract\" là agent research hữu ích nhỏ nhất.
Câu hỏi thường gặp
Tôi có thể dùng cái này với OpenAI Responses API thay vì Assistants không?
Có. Cùng một tool schema hoạt động trong client.responses.create() — truyền nó qua tools=[{...}] đúng như tài liệu OpenAI chỉ dẫn. Hình thức handler là giống hệt: parse tool_calls, chạy POST /api/search/web, trả về JSON.
Tôi có cần định dạng kết quả trước khi trả về cho mô hình không?
Không. POST /api/search/web trả về title + URL + snippet thân thiện với LLM đã được xếp hạng. Truyền JSON thô trở lại làm kết quả tool. Mô hình sẽ trích dẫn các snippet và liên kết các URL.
Mỗi lượt agent tốn bao nhiêu?
Mỗi lệnh gọi web search là 15 credits (~$0,015 ở mức $5/5.000 credits). Một lượt agent điển hình dùng tool một lần thấp hơn nhiều so với một xu Mỹ chi phí tìm kiếm — token LLM mới chiếm phần lớn.
Nếu mô hình không bao giờ gọi tool thì sao?
Hãy làm cho mô tả tool thật cụ thể. "Use this for any question that requires current or post-training information" hoạt động tốt hơn nhiều so với "web search". Mô hình điều hướng tới những tool mà nó hiểu được mục đích.
Tôi có thể giới hạn kết quả theo quốc gia hoặc khoảng ngày không?
Có. Truyền country_code (ISO 3166-1 alpha-2) và/hoặc start_date / end_date (YYYY-MM-DD). Thêm chúng làm tham số trong tool schema nếu bạn muốn mô hình tự chọn; hoặc hard-code trong handler nếu agent của bạn có locale hay yêu cầu độ mới cố định.
Các API dùng trong bài viết này
Sarah Choy là CEO của API Pick. Cô viết về việc xây dựng các API sẵn sàng cho production cho AI agent và quy trình LLM.