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

> Explore how build_bq_agent and build_web_agent differ. Compare tools and functionality in Knowledge Catalog, focusing on data source capabilities and query options.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: comparison
- Published: 2026-07-16

---

**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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/reference_instruction.md), whereas the Web agent uses [`web_ingestion_instruction.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```python
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:

```python
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:

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

```

And the web equivalent:

```python
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/src/reference_agent/tools/web_tools.py)** – Implements `fetch_url` for web content retrieval
- **[`okf/src/reference_agent/tools/bundle_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/src/reference_agent/prompts/reference_instruction.md)** – System instructions for the BigQuery agent
- **[`okf/src/reference_agent/prompts/web_ingestion_instruction.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/source_tools.py)
- `build_web_agent` includes the `fetch_url` tool for web content retrieval, defined in [`web_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/web_tools.py)
- Both factory functions reside in [`okf/src/reference_agent/agent.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/src/reference_agent/agent.py) and share common tools from [`bundle_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/bundle_tools.py) and [`source_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/source_tools.py) contains `list_concepts`, `read_concept_raw`, and `sample_rows`; [`web_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/web_tools.py) contains the `fetch_url` implementation; and [`bundle_tools.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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.