Create a data agent

This page describes how to create persistent data agents with the Conversational Analytics API by using either the Python SDK or HTTP.

To create a data agent, you need the Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) Identity and Access Management (IAM) role.

The following sample code demonstrates how to create the data agent synchronously or asynchronously by sending an HTTP POST request to the data agent creation endpoint. The request payload includes the following details:

• The full resource name for the agent. This value includes the project ID, location, and a unique identifier for the agent.
• The data agent's description.
• The data agent's context, including the system description (defined in Configure initial settings and authentication) and the data source that the agent uses (defined in Connect to a data source).

You can optionally protect the data agent with customer-managed encryption keys (CMEK) by providing a kms_key during creation. CMEK is supported only for Looker data sources. For more information, see Customer-managed encryption keys (CMEK).

You can also optionally enable advanced analysis with Python by including the options parameter in the request payload. See the REST Resource: projects.locations.dataAgents for more information about the options parameter and the options that you can configure for the conversation.

Warning: The Python code that data agents return is designed to execute within a secure, Google-managed sandbox. Executing this code in a local or other unverified environment bypasses the sandbox's security protections and can expose your system to security risks, such as the execution of malicious code. For guidance on how to safely inspect and handle agent-generated Python code, see How can I safely inspect and handle agent-generated Python code?

The following example uses the bigquery_data_sources variable that was created in the section on connecting to BigQuery to configure the data agent to connect to a BigQuery table.

To use Looker data instead, replace bigquery_data_sources with looker_data_source.

To use Data Studio data instead, replace bigquery_data_sources with looker_studio_data_source.

To use AlloyDB data instead, replace bigquery_data_sources with alloydb_data_source.

To use Cloud SQL data instead, replace bigquery_data_sources with sql_data_source.

To use Spanner data instead, replace bigquery_data_sources with spanner_data_sources.

Create a data agent synchronously

Python SDK

data_agent_id = "data_agent_1"

# Optional: If using CMEK, replace the empty strings with your KMS key details.
key_ring = ""    # KEY_RING_NAME
key_name = ""    # KEY_NAME
key_project = "" # KMS_PROJECT_ID (Defaults to billing_project if empty)

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}" # Optional

# Optional: Add CMEK key if details are provided
if key_ring and key_name:
  if not key_project:
    key_project = billing_project
  kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
  data_agent.kms_key = kms_key_data_agent # Add for CMEK

request = geminidataanalytics.CreateDataAgentRequest(
  parent=f"projects/{billing_project}/locations/{location}",
  data_agent_id=data_agent_id, # Optional
  data_agent=data_agent,
)

try:
  response = data_agent_client.create_data_agent_sync(request=request)
  print("Data Agent created")
  print(response)
except Exception as e:
  print(f"Error creating Data Agent: {e}")

In the previous example, replace values as follows:

• data_agent_1: A unique identifier for the data agent.
• KEY_RING_NAME: If using CMEK, the name of your Cloud KMS key ring.
• KEY_NAME: If using CMEK, the name of your Cloud KMS key.
• KMS_PROJECT_ID: If using CMEK, the project ID where the key is hosted.

HTTP

data_agent_url = f"https://geminidataanalytics.googleapis.com/v1beta/projects/{billing_project}/locations/{location}/dataAgents:createSync"

data_agent_id = "DATA_AGENT_ID"

# Optional: If using CMEK, replace the empty strings with your KMS key details.
kms_project_id = ""  # KMS_PROJECT_ID (Defaults to billing_project if empty)
key_ring_name = ""   # KEY_RING_NAME
key_name = ""        # KEY_NAME

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}", # Optional
      "description": "This is the description of the data agent.", # Optional
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": bigquery_data_sources,
              "system_instruction": system_instruction,
              "options": {
                  # Optional: To enable advanced analysis with Python
                  "analysis": {
                      "python": {
                          "enabled": True
                      }
                  },
                  # Optional: To limit query costs to 100MiB
                  "datasource": {
                      "bigQueryMaxBilledBytes": "104857600"
                  }
              }
          }
      }
  }

# If key details are provided, construct and add the kms_key field.
if key_ring_name and key_name:
  if not kms_project_id:
    kms_project_id = billing_project
  data_agent_payload["kms_key"] = f"projects/{kms_project_id}/locations/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"

params = {"data_agent_id": data_agent_id} # Optional

data_agent_response = requests.post(
    data_agent_url, params=params, json=data_agent_payload, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agent created successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error creating Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Replace the sample values as follows:

• DATA_AGENT_ID: A unique identifier for the data agent. This value is used in the agent's resource name and as the data_agent_id URL query parameter.
• KMS_PROJECT_ID: If using CMEK, the project ID where the key is hosted. If not provided, this defaults to your billing project.
• KEY_RING_NAME: If using CMEK, the name of your Cloud KMS key ring.
• KEY_NAME: If using CMEK, the name of your Cloud KMS key.
• This is the description of the data agent.: A description for the data agent.

Create a data agent asynchronously

Python SDK

data_agent_id = "data_agent_1"

# Optional: If using CMEK, replace the empty strings with your KMS key details.
key_ring = ""    # KEY_RING_NAME
key_name = ""    # KEY_NAME
key_project = "" # KMS_PROJECT_ID (Defaults to billing_project if empty)

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}" # Optional

# Optional: Add CMEK key if details are provided
if key_ring and key_name:
  if not key_project:
    key_project = billing_project
  kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
  data_agent.kms_key = kms_key_data_agent # Add for CMEK

request = geminidataanalytics.CreateDataAgentRequest(
  parent=f"projects/{billing_project}/locations/{location}",
  data_agent_id=data_agent_id, # Optional
  data_agent=data_agent,
)

try:
  data_agent_client.create_data_agent(request=request)
  print("Data Agent created")
except Exception as e:
  print(f"Error creating Data Agent: {e}")

In the previous example, replace values as follows:

• data_agent_1: A unique identifier for the data agent.
• KEY_RING_NAME: If using CMEK, the name of your Cloud KMS key ring.
• KEY_NAME: If using CMEK, the name of your Cloud KMS key.
• KMS_PROJECT_ID: If using CMEK, the project ID where the key is hosted.

HTTP

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents"

data_agent_id = "DATA_AGENT_ID"

# Optional: If using CMEK, replace the empty strings with your KMS key details.
kms_project_id = ""  # KMS_PROJECT_ID (Defaults to billing_project if empty)
key_ring_name = ""   # KEY_RING_NAME
key_name = ""        # KEY_NAME

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}", # Optional
      "description": "This is the description of the data agent.", # Optional
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": bigquery_data_sources,
              "system_instruction": system_instruction,
              "options": {
                  # Optional: To enable advanced analysis with Python
                  "analysis": {
                      "python": {
                          "enabled": True
                      }
                  },
                  # Optional: To limit query costs to 100MiB
                  "datasource": {
                      "bigQueryMaxBilledBytes": "104857600"
                  }
              }
          }
      }
  }

# If key details are provided, construct and add the kms_key field.
if key_ring_name and key_name:
  if not kms_project_id:
    kms_project_id = billing_project
  data_agent_payload["kms_key"] = f"projects/{kms_project_id}/locations/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"

params = {"data_agent_id": data_agent_id} # Optional

data_agent_response = requests.post(
    data_agent_url, params=params, json=data_agent_payload, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agent created successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error creating Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Replace the sample values as follows:

• DATA_AGENT_ID: A unique identifier for the data agent. This value is used in the agent's resource name and as the data_agent_id URL query parameter.
• KMS_PROJECT_ID: If using CMEK, the project ID where the key is hosted. If not provided, this defaults to your billing project.
• KEY_RING_NAME: If using CMEK, the name of your Cloud KMS key ring.
• KEY_NAME: If using CMEK, the name of your Cloud KMS key.
• This is the description of the data agent.: A description for the data agent.