Manage BigQuery costs for Conversational Analytics API agents

This page describes how to monitor and manage BigQuery costs for your Conversational Analytics API agents, which incur costs by running queries against your BigQuery data. You can use the following methods to control spending and prevent unexpected expenses:

Set quotas for projects and users to apply broad spending limits for an entire project or for individual users.
Limit costs for individual queries by setting a big_query_max_billed_bytes value in the agent's configuration.

Before you begin

Before you implement the cost controls that are described on this page, you must meet the following requirements:

You must have a Google Cloud project with billing enabled.
You must have the necessary Identity and Access Management (IAM) permissions to manage quotas and billing for your Google Cloud project.

Set quotas for projects and users

You can set spending limits for a Google Cloud project or for individual users by applying standard BigQuery quotas . These limits help you control overall costs and prevent individual users from overspending.

For agents that might incur high costs, such as an agent that is built on a very large or unpartitioned table, the recommended practice is to first isolate the agent in its own dedicated project . You can then apply a project-level quota to cap the project's maximum daily cost, a user-level quota to ensure fair use among users, or both project-level and user-level quotas.

Set up a dedicated project for your agent

To set up a dedicated project for your Conversational Analytics API agent or agents, follow these steps:

In the Google Cloud console, create a new Google Cloud project . This project will be dedicated to your agent or agents.
Make sure that billing is enabled for the new project.
Confirm that the agent is configured to use this new project for billing. When you configure the agent, you'll need to specify the project ID of this new project.

Set a quota for the project

After you have set up a dedicated Google Cloud project, you can apply a quota to control costs for the entire project. To set a project-level quota, follow these steps:

In the Google Cloud project for your agent, navigate to IAM & Admin > Quotas.

Go to Quotas
Filter for the BigQuery API service, and select the Query usage per dayquota.
Edit the quota to your chosen daily limit (for example, 10 TiB). This limit creates a hard stop that prevents the project from exceeding the specified daily cost.

Set a quota for users

To prevent any individual user from generating a large bill, you can set a per-user quota by following these steps:

In the Google Cloud project for your agent, navigate to IAM & Admin > Quotas.

Go to Quotas
Filter for the BigQuery APIservice and select the Query usage per day per userquota.
Edit the quota to your chosen daily limit (for example, 1 TiB per user per day). This limit ensures that no single user can consume an excessive amount of resources.

Limit costs for individual queries

To prevent any individual user query from generating a large, unexpected bill, you can set a per-query cost limit by configuring the big_query_max_billed_bytes parameter on an agent.

Before the agent runs any query, the agent performs a trial run to estimate the cost of the query. If the estimated bytes to be scanned exceed the big_query_max_billed_bytes value, then the agent blocks the query and sends an error message to the user.

You can set the big_query_max_billed_bytes parameter within the published_context field when you create or configure an agent with HTTP or with the Python SDK . The following example, shown in textproto format, illustrates the structure of a request that configures a 100 MB limit for an agent that answers questions about San Francisco street trees:

 parent: "projects/sample-project-name/locations/global"
data_agent_id: "sample-agent-id"
data_agent {
  name: "projects/sample-project-name/locations/global/dataAgents/sample-agent-id"
  data_analytics_agent {
    published_context {
      system_instruction: "This agent provides information about street trees in San Francisco, including their species, location, and planting date."
      options {
        datasource {
          big_query_max_billed_bytes {
            value: 104857600 #100MB
          }
        }
      }
      datasource_references {
        bq {
          table_references {
            project_id: "bigquery-public-data"
            dataset_id: "san_francisco"
            table_id: "street_trees"
          }
        }
      }
    }
  }
}

In this example, the big_query_max_billed_bytes parameter is set to 104857600 bytes (100 MB). This value establishes a limit for any queries that are run by the sample-agent-id agent on the bigquery-public-data.san_francisco.street_trees BigQuery table.

For interactive examples of how to create and configure agents, see the Colaboratory notebooks . For detailed information about API fields, consult the API reference .

Limitations

Keep the following limitations in mind when you're managing costs for your Conversational Analytics API agents:

These cost management tools apply only to projects that use on-demand billing and not to projects that use slot reservations .
Setting quotas for individual agents isn't supported. As described in Set quotas for projects and users , the recommended practice is to isolate the agent in its own project, and then apply project-level or per-user quotas to that project.
Tracking costs for individual agents by using BigQuery labels isn't supported.