You can connect a data agent to Looker by using the Conversational Analytics API to let users query data in natural language and receive answers that are grounded in your curated LookML models and business logic.
To configure your data source, first define references to your Looker Explores by using the Python SDK or HTTP. Then, provide these references when you create a persistent data agent or send a stateless chat request with inline context.
You also provide Looker credentials in each chat request, as described in Authorize requests to Looker.
Data agents that you create with the API are managed as Google Cloud resources and don't appear in the Looker UI. To create and manage data agents in Looker, see Create and manage Explore data agents.
Before you begin
Before you connect a data agent to Looker, complete the following tasks:
- Enable the Conversational Analytics API in your Google Cloud project.
- Verify that you have the required Identity and Access Management (IAM) roles.
- Verify that your Looker instance meets the prerequisites for Conversational Analytics and that you have access to the LookML models and Explores that you want to query.
- Get a Looker API key or an access token to authorize the data agent's requests to your instance. To decide which to use, see Choose an authorization method.
Required roles
To get the permissions that you need to connect a data agent to Looker and query Explores, ask your administrator to grant you the following IAM roles:
-
Create a persistent data agent:
Gemini Data Analytics Data Agent Creator (
roles/geminidataanalytics.dataAgentCreator) on your project -
Chat with a persistent data agent:
Gemini Data Analytics Data Agent User (
roles/geminidataanalytics.dataAgentUser) on your project or the data agent -
Chat in stateful conversations:
Gemini for Google Cloud User (
roles/cloudaicompanion.user) on your project -
Chat by using inline context:
Gemini Data Analytics Stateless Chat User (
roles/geminidataanalytics.dataAgentStatelessUser) on your project -
Connect to a Looker (Google Cloud core) instance:
Looker Instance User (
roles/looker.instanceUser) on the project that hosts your Looker (Google Cloud core) instance
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
In addition to IAM roles, you need permissions in Looker. The Looker user or service account whose credentials are used to authenticate must have a Looker role that includes the following permissions for the LookML models that you query:
To configure roles, go to Admin > Roles in your Looker instance.
Connect to Looker Explores
You can connect up to five Looker Explores at a time with the Conversational Analytics API. All Explores in a data source must be on the same Looker instance, and each Explore reference must identify that instance in the same way.
A data agent queries one Explore at a time and can't join data across multiple Explores in a single query. However, an agent can query multiple Explores across a conversation to answer follow-up questions or multi-part prompts. For example, if a prompt requires data from both an orders Explore and an inventory Explore, the agent queries each one sequentially and combines the results in a single response.
To improve response accuracy, you can define golden queries that guide how the agent queries your Explores. For more information, see Define data agent context for Looker data sources.
How you identify your instance in each Explore reference depends on how you connect to the instance.
Connect to an instance that has a public URL
If your Looker instance has a public URL, set the looker_instance_uri field (Python SDK) or the lookerInstanceUri field (HTTP) in each Explore reference.
The following code samples show how to define a connection to multiple Explores on an instance that has a public URL:
Python SDK
from google.cloud import geminidataanalytics
looker_instance_uri = "INSTANCE_URI"
looker_explore_reference_1 = geminidataanalytics.LookerExploreReference()
looker_explore_reference_1.looker_instance_uri = looker_instance_uri
looker_explore_reference_1.lookml_model = "MODEL"
looker_explore_reference_1.explore = "EXPLORE"
# Optional: Define additional Explores (up to 5 total)
looker_explore_reference_2 = geminidataanalytics.LookerExploreReference()
looker_explore_reference_2.looker_instance_uri = looker_instance_uri
looker_explore_reference_2.lookml_model = "MODEL_2"
looker_explore_reference_2.explore = "EXPLORE_2"
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [
looker_explore_reference_1,
looker_explore_reference_2,
]
# Attach the data source to published context
published_context = geminidataanalytics.Context()
published_context.datasource_references = datasource_references
Replace the sample values as follows:
- INSTANCE_URI: The complete URL of your Looker instance (for example,
https://example.looker.com). - MODEL: The name of the LookML model that includes the Explore that you want to connect to.
- EXPLORE: The name of the Looker Explore that you want the data agent to query.
- MODEL_2: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
- EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.
HTTP
looker_instance_uri = "INSTANCE_URI"
looker_data_source = {
"looker": {
"exploreReferences": [
{
"lookerInstanceUri": looker_instance_uri,
"lookmlModel": "MODEL",
"explore": "EXPLORE",
},
# Optional: Add up to 5 total Explore references
{
"lookerInstanceUri": looker_instance_uri,
"lookmlModel": "MODEL_2",
"explore": "EXPLORE_2",
},
],
}
}
# Attach the data source to published context
published_context = {
"datasourceReferences": looker_data_source,
}
Replace the sample values as follows:
- INSTANCE_URI: The complete URL of your Looker instance (for example,
https://example.looker.com). - MODEL: The name of the LookML model that includes the Explore that you want to connect to.
- EXPLORE: The name of the Looker Explore that you want the data agent to query.
- MODEL_2: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
- EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.
Connect to an instance that uses only private connections
If your Looker (Google Cloud core) instance uses only private connections, set the private_looker_instance_info field (Python SDK) or the privateLookerInstanceInfo field (HTTP) in each Explore reference. This field contains the instance ID and Service Directory name. You must also authorize requests by using an access token.
The following code samples show how to define a connection to multiple Explores on an instance that uses only private connections:
Python SDK
from google.cloud import geminidataanalytics
private_instance = geminidataanalytics.PrivateLookerInstanceInfo()
private_instance.looker_instance_id = "INSTANCE_ID"
private_instance.service_directory_name = "SERVICE_DIRECTORY_NAME"
looker_explore_reference_1 = geminidataanalytics.LookerExploreReference()
looker_explore_reference_1.private_looker_instance_info = private_instance
looker_explore_reference_1.lookml_model = "MODEL"
looker_explore_reference_1.explore = "EXPLORE"
# Optional: Define additional Explores (up to 5 total)
looker_explore_reference_2 = geminidataanalytics.LookerExploreReference()
looker_explore_reference_2.private_looker_instance_info = private_instance
looker_explore_reference_2.lookml_model = "MODEL_2"
looker_explore_reference_2.explore = "EXPLORE_2"
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [
looker_explore_reference_1,
looker_explore_reference_2,
]
# Attach the data source to published context
published_context = geminidataanalytics.Context()
published_context.datasource_references = datasource_references
Replace the sample values as follows:
- INSTANCE_ID: The ID of your Looker (Google Cloud core) instance, in the following format:
projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_NAME. - SERVICE_DIRECTORY_NAME: The resource name of the Service Directory service for your Looker (Google Cloud core) instance, in the following format:
projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE/services/SERVICE. To get this name, give your instance ID to your Looker customer engineer. - MODEL: The name of the LookML model that includes the Explore that you want to connect to.
- EXPLORE: The name of the Looker Explore that you want the data agent to query.
- MODEL_2: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
- EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.
HTTP
private_instance = {
"lookerInstanceId": "INSTANCE_ID",
"serviceDirectoryName": "SERVICE_DIRECTORY_NAME",
}
looker_data_source = {
"looker": {
"exploreReferences": [
{
"privateLookerInstanceInfo": private_instance,
"lookmlModel": "MODEL",
"explore": "EXPLORE",
},
# Optional: Add up to 5 total Explore references
{
"privateLookerInstanceInfo": private_instance,
"lookmlModel": "MODEL_2",
"explore": "EXPLORE_2",
},
],
}
}
# Attach the data source to published context
published_context = {
"datasourceReferences": looker_data_source,
}
Replace the sample values as follows:
- INSTANCE_ID: The ID of your Looker (Google Cloud core) instance, in the following format:
projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_NAME. - SERVICE_DIRECTORY_NAME: The resource name of the Service Directory service for your Looker (Google Cloud core) instance, in the following format:
projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE/services/SERVICE. To get this name, give your instance ID to your Looker customer engineer. - MODEL: The name of the LookML model that includes the Explore that you want to connect to.
- EXPLORE: The name of the Looker Explore that you want the data agent to query.
- MODEL_2: Optional: The name of the LookML model that includes the second Explore. This model can be the same as MODEL.
- EXPLORE_2: Optional: The name of a second Looker Explore. To connect more Explores, add a reference for each one, up to five in total.
Authorize requests to Looker
To run queries against your connected Explores, the data agent needs Looker credentials that authorize its requests to your Looker instance. Credentials aren't stored with the data agent, so you provide them in the credentials field of each chat request. For examples, see Build a data agent using HTTP and Build a data agent using the Python SDK.
Choose an authorization method
You can authorize requests by using either a Looker API key or an OAuth access token. If your Looker (Google Cloud core) instance uses only private connections, you must use an access token.
API keys use the permissions and access levels of the user account that the key is associated with. API keys can be useful if you're building an application in which everyone shares the same level of access.
An access token applies the target user's LookML row-level and column-level permissions (for example, access_filters, access_grants, and sql_always_where). An access token is useful for a multi-tenant application.
Use the following table to choose how to authorize requests:
| User type | Authorization method | For Looker (original) | For Looker (Google Cloud core) | For Looker (Google Cloud core) that uses only private connections | Description |
|---|---|---|---|---|---|
| Embed users | Access token | login_user |
login_user |
login_user |
Respects the target user's LookML row-level and column-level permissions (for example, access_filters, access_grants, and sql_always_where). |
| Standard users | Access token |
Or |
OAuth client | OAuth client | Respects the target user's LookML row-level and column-level permissions (for example, access_filters, access_grants, and sql_always_where). |
| Looker API-only service account | API key | Client ID and secret | Client ID and secret | Not supported | All users share the same level of access to Looker. |
Connect with Looker API keys
A Looker API key consists of a client ID and a client secret that are associated with a Looker user account.
For more information about generating Looker API keys, see Admin settings - Users. For more information about authentication methods and managing Looker API keys, see Looker API authentication.
The following code samples show how to specify your credentials by using an API key. Pass the resulting object in the credentials field of your chat request:
Python SDK
credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = "CLIENT_ID"
credentials.oauth.secret.client_secret = "CLIENT_SECRET"
Replace the sample values as follows:
- CLIENT_ID: The client ID of your Looker API key.
- CLIENT_SECRET: The client secret of your Looker API key.
HTTP
looker_credentials = {
"oauth": {
"secret": {
"clientId": "CLIENT_ID",
"clientSecret": "CLIENT_SECRET",
}
}
}
Replace the sample values as follows:
- CLIENT_ID: The client ID of your Looker API key.
- CLIENT_SECRET: The client secret of your Looker API key.
Connect with an access token
If your application uses OAuth to authenticate to Looker, you can provide an access token in your credentials rather than an API key.
You generate an access token by sending a request to the login endpoint of the Looker API. For more information about generating an access token, see Looker API authentication and Present client credentials to obtain an authorization token.
The following code samples show how to specify your credentials by using an access token. Pass the resulting object in the credentials field of your chat request:
Python SDK
credentials = geminidataanalytics.Credentials()
credentials.oauth.token.access_token = "ACCESS_TOKEN"
Replace ACCESS_TOKEN with the OAuth access token that you generate to authorize requests to Looker.
HTTP
looker_credentials = {
"oauth": {
"token": {
"accessToken": "ACCESS_TOKEN",
}
}
}
Replace ACCESS_TOKEN with the OAuth access token that you generate to authorize requests to Looker.
What's next
- Define data agent context for Looker data sources to add golden queries and improve response accuracy.
- Create a data agent that queries your connected Looker Explores, or send stateless chat requests, as described in Build a data agent using HTTP or Build a data agent using the Python SDK.
- Configure customer-managed encryption keys (CMEK) to protect your data agent resources.