Skip to content
EN
Get API key

Workflows / Python

Add Google and YouTube search tools to an AI agent

Wrap search and transcript requests as Python tools, preserve source references and let your agent choose when to retrieve data.

FlashData · Published

An agent connected to web search and video data tools

Define the tool boundary

Give your agent small tools with clear inputs and outputs: search the web, discover videos, and read a video’s available transcript. Your agent chooses when to call them and how to use the evidence.

The code below supplies the retrieval functions. Register them with your existing agent framework; they work independently of which model or orchestration library you choose.

bash
# Replace YOUR_API_KEY near the top of the code below.

Implement the retrieval tools

The following Python 3 code uses the standard library. Save it as tools.py. Running it directly makes one Google search request; importing it lets your application register the three functions as tools.

python
import json
import gzip
import os
import urllib.error
import urllib.request

API_URL = "https://data.flashdata.dev"
API_KEY = "YOUR_API_KEY"


def api_request(path, payload=None, response_headers=None, base_url=API_URL):
    target = path if path.startswith(("https://", "http://")) else base_url + path
    request = urllib.request.Request(
        target,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        if response_headers is not None:
            response_headers.update(response.headers)
        return json.load(response)


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
        return None


def result_request(url):
    request = urllib.request.Request(url, headers={"X-API-Key": API_KEY}, method="GET")
    try:
        with urllib.request.build_opener(NoRedirect).open(request, timeout=60):
            raise RuntimeError("Results endpoint did not redirect to storage")
    except urllib.error.HTTPError as response:
        if response.code != 302 or not response.headers.get("Location"):
            raise
        storage_url = response.headers["Location"]
        response.close()
    storage_request = urllib.request.Request(storage_url, headers={"Accept-Encoding": "gzip"})
    with urllib.request.urlopen(storage_request, timeout=60) as response:
        body = response.read()
        if response.headers.get("Content-Encoding") == "gzip":
            body = gzip.decompress(body)
        return json.loads(body)["results"]


def search_web(query):
    """Search the web and return titles, URLs and result snippets."""
    response = api_request("/v1/queries/realtime", {
        "source": "google_search", "query": query,
    })
    return response["results"][0]


def find_videos(query):
    """Discover YouTube videos and their video IDs."""
    response = api_request("/v1/queries/realtime", {
        "source": "youtube_search", "query": query,
        "params": {"max_results": 5},
    })
    return response["results"][0]["results"]


def read_video_transcript(video_id, language="en"):
    """Read available captions with timestamps; captions may be unavailable."""
    response = api_request("/v1/queries/realtime", {
        "source": "youtube_transcript", "video_id": video_id,
        "params": {"language": language, "auto": True},
    })
    return response["results"][0]


# Register these functions as tools in your own agent framework.
# The agent chooses when to call them and how to use the evidence.
if __name__ == "__main__":
    print(json.dumps(search_web("distributed systems"), indent=2))
bash
python3 tools.py

Connect the tools to your agent

Describe each tool’s arguments and results in your framework’s tool schema. Keep query, video_id and language as explicit inputs so the model can request the data it needs.

  • search_web(query) returns Google results with source URLs and snippets.

  • find_videos(query) returns videos and the IDs needed for follow-up requests.

  • read_video_transcript(video_id, language) returns available caption segments with timestamps.

Return useful tool errors when a request fails or a caption track is unavailable. Apply your application’s credit and request budgets, and let the agent decide whether to try a different query or use another source.

Keep sources and timestamps

A search snippet is a preview of a page. Preserve its URL and avoid treating the snippet as the full article. For transcripts, keep the video ID, language and segment times so the agent can cite the original passage.

For a video knowledge base, store the video title and timestamped source link with each text chunk. Your retrieval system can then return both the content and the reference used to support an answer.