How build_bq_agent Differs from build_web_agent in Knowledge Catalog: Tools and Functionality Compared

The build_bq_agent and build_web_agent factory functions in the GoogleCloudPlatform/knowledge-catalog repository share identical catalog management tools but differ in their data source capabilities: the BigQuery agent includes sample_rows for querying table data, while the Web agent provides fetch_url for retrieving external web content.

The build_bq_agent and build_web_agent functions located in okf/src/reference_agent/agent.py create specialized google.adk.Agent instances for the Knowledge Catalog system. While both agents handle documentation generation for data concepts, they are optimized for different source types, with distinct toolsets that determine how they interact with BigQuery datasets versus external web content.

Core Architecture and Shared Foundation

Both factory functions follow an identical pattern defined in okf/src/reference_agent/agent.py. They instantiate agents with the same core catalog management capabilities, creating a google.adk.Agent configured with a specific subset of tools from the Knowledge Catalog tool ecosystem.

The shared architecture ensures consistent behavior when listing concepts, reading raw concept data, or managing documentation files, regardless of whether the underlying data comes from BigQuery tables or web pages.

Tool Comparison: BigQuery vs. Web Ingestion Capabilities

The primary distinction between these agents lies in their specialized data retrieval tools, while they share common catalog operations.

Shared Catalog Management Tools

Both agents include four identical tools implemented across the codebase:

• list_concepts – Enumerates available concepts in the catalog (implemented in okf/src/reference_agent/tools/source_tools.py)
• read_concept_raw – Fetches raw concept metadata and structure (implemented in okf/src/reference_agent/tools/source_tools.py)
• read_existing_doc – Retrieves previously generated documentation (implemented in okf/src/reference_agent/tools/bundle_tools.py)
• write_concept_doc – Persists new documentation artifacts (implemented in okf/src/reference_agent/tools/bundle_tools.py)

These tools provide the foundational CRUD operations for documentation management and are available to both agent types.

BigQuery-Specific Functionality with sample_rows

The build_bq_agent function creates an agent named okf_bq_reference_agent that includes the sample_rows tool from okf/src/reference_agent/tools/source_tools.py. This specialized tool enables the agent to execute queries against BigQuery tables and retrieve sample data rows.

According to the source code in source_tools.py, this capability allows the agent to enrich documentation with actual data patterns, column statistics, and table contents when generating reference materials for BigQuery datasets.

Web Ingestion with fetch_url

Conversely, build_web_agent instantiates an agent named okf_web_ingestion_agent that replaces the BigQuery sampling capability with the fetch_url tool from okf/src/reference_agent/tools/web_tools.py.

This tool enables the agent to retrieve and process content from external URLs, making it suitable for ingesting web-based documentation, API specifications, or reference materials published on external sites when building the knowledge catalog.

Configuration and Instruction Differences

Beyond tooling, the agents differ in their initialization parameters and instruction sets:

• Agent Names: build_bq_agent registers as okf_bq_reference_agent while build_web_agent registers as okf_web_ingestion_agent
• Instruction Prompts: The BigQuery agent loads instructions from reference_instruction.md, whereas the Web agent uses web_ingestion_instruction.md to guide its behavior

These configuration distinctions ensure each agent receives context-appropriate system instructions aligned with its data source specialization.

Implementation Examples

The following examples demonstrate how to instantiate each agent type in your Knowledge Catalog implementation.

Creating a BigQuery-focused agent:

from reference_agent.agent import build_bq_agent

bq_agent = build_bq_agent(model="gemini-flash-latest")

# Now the agent can call sample_rows internally when generating docs

Creating a Web-focused agent:

from reference_agent.agent import build_web_agent

web_agent = build_web_agent(model="gemini-flash-latest")

# The agent can now call fetch_url to ingest external web content

When executing within the ADK framework, the tools are invoked automatically based on the agent's reasoning. For example, the BigQuery tool would be called as:

result = await agent.tools["sample_rows"](project="my-project", dataset="my_ds", table="my_table")

And the web equivalent:

result = await agent.tools["fetch_url"](url="https://example.com")

Key Source Files

Understanding these agents requires familiarity with the following repository files:

• okf/src/reference_agent/agent.py – Contains the build_bq_agent and build_web_agent factory functions
• okf/src/reference_agent/tools/source_tools.py – Implements list_concepts, read_concept_raw, and sample_rows
• okf/src/reference_agent/tools/web_tools.py – Implements fetch_url for web content retrieval
• okf/src/reference_agent/tools/bundle_tools.py – Contains read_existing_doc and write_concept_doc shared by both agents
• okf/src/reference_agent/prompts/reference_instruction.md – System instructions for the BigQuery agent
• okf/src/reference_agent/prompts/web_ingestion_instruction.md – System instructions for the Web agent

Summary

• Both agents share identical catalog management tools (list_concepts, read_concept_raw, read_existing_doc, write_concept_doc)
• build_bq_agent includes the sample_rows tool for BigQuery data sampling, defined in source_tools.py
• build_web_agent includes the fetch_url tool for web content retrieval, defined in web_tools.py
• Both factory functions reside in okf/src/reference_agent/agent.py and create google.adk.Agent instances with distinct names (okf_bq_reference_agent vs okf_web_ingestion_agent) and instruction prompts
• The architecture allows reuse of core documentation workflows while specializing data source interactions

Frequently Asked Questions

What is the primary difference between build_bq_agent and build_web_agent?

The primary difference is the specialized data retrieval tool each agent possesses. build_bq_agent includes sample_rows for querying BigQuery tables, while build_web_agent includes fetch_url for retrieving external web content. Both agents share the same four catalog management tools for reading and writing documentation, but they differ in how they acquire source data for enrichment.

Can I use both agents in the same Knowledge Catalog workflow?

Yes. Since both agents are instantiated from okf/src/reference_agent/agent.py and share common tools from bundle_tools.py and source_tools.py, they can operate within the same ecosystem. You can initialize both agents simultaneously, using the BigQuery agent for table documentation and the Web agent for external reference ingestion, ensuring comprehensive catalog coverage.

Which file contains the tool implementations for these agents?

The tool implementations are distributed across three files in the repository: source_tools.py contains list_concepts, read_concept_raw, and sample_rows; web_tools.py contains the fetch_url implementation; and bundle_tools.py houses read_existing_doc and write_concept_doc used by both agent types.

How do I choose between build_bq_agent and build_web_agent?

Choose build_bq_agent when your documentation workflow requires sampling actual data rows from BigQuery tables to enrich concept descriptions, as implemented in the GoogleCloudPlatform/knowledge-catalog reference system. Choose build_web_agent when you need to ingest and process content from external URLs or web-based APIs. Both agents provide identical catalog management capabilities, so the decision depends solely on your data source requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}