API Conversational Analytics: crie agentes de dados e converse com seus dados
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Os desenvolvedores podem usar a API Conversational Analytics, acessada pelo geminidataanalytics.googleapis.com, para criar uma interface de chat ou um agente de dados com tecnologia de IA que responda a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio usando linguagem natural. Com a API Conversational Analytics, você fornece ao seu agente de dados informações e dados comerciais ("contexto"), além de acesso a ferramentas como SQL, Python e bibliotecas de visualização. Essas respostas do agente são apresentadas ao usuário e podem ser registradas pelo aplicativo cliente, criando uma experiência de chat de dados simples e auditável.
Para configurar seu ambiente e começar a criar e interagir com agentes de dados usando a API Conversational Analytics, comece com os notebooks do Colaboratory para uma experiência guiada ou siga as etapas em Configuração e pré-requisitos para uma experiência independente.
Notebooks interativos do Colaboratory
Para um guia interativo e explicativo sobre como configurar seu ambiente, criar um agente de dados e fazer chamadas de API, consulte os seguintes notebooks do Colaboratory:
Depois de concluir as etapas anteriores, use a API Conversational Analytics para criar e interagir com um agente de dados seguindo estas etapas:
Criar um agente de dados usando HTTP: oferece um exemplo completo de como criar e interagir com um agente de dados usando solicitações HTTP diretas com Python.
Escreva instruções eficazes para o sistema: aprenda a estruturar o conteúdo YAML para o parâmetro system_instruction e orientar o comportamento do agente, além de melhorar a precisão da resposta.
A API fornece os seguintes endpoints principais para gerenciar agentes de dados e conversas:
Operação
Método HTTP
Endpoint
Descrição
Criar um agente
POST
/v1alpha/projects/*/locations/*/dataAgents
Cria um novo agente de dados.
Obter um agente
GET
/v1alpha/projects/*/locations/*/dataAgents/*
Recupera detalhes de um agente de dados específico.
Atualizar um agente
PATCH
/v1alpha/projects/*/locations/*/dataAgents/*
Modifica um agente de dados.
Listar agentes
GET
/v1alpha/projects/*/locations/*/dataAgents
Lista os agentes de dados disponíveis em um projeto.
Excluir um agente
DELETE
/v1alpha/projects/*/locations/*/dataAgents/*
Remove um agente de dados.
Criar uma conversa
POST
/v1alpha/projects/*/locations/*/conversations
Inicia uma nova conversa persistente.
Conversar usando uma referência de conversa
POST
/v1alpha/projects/*/locations/*:chat
Continua uma conversa com estado enviando uma mensagem de chat que faz referência a uma conversa e ao contexto do agente associado. Para conversas com várias interações, o Google Cloud armazena e gerencia o histórico da conversa.
Usar uma referência de agente de dados para conversar
POST
/v1alpha/projects/*/locations/*:chat
Envia uma mensagem de chat sem estado que faz referência a um agente de dados salvo para contexto. Para conversas com várias interações, o aplicativo precisa gerenciar e fornecer o histórico da conversa com cada solicitação.
Conversar usando contexto inline
POST
/v1alpha/projects/*/locations/*:chat
Envia uma mensagem de chat sem estado fornecendo todo o contexto diretamente na solicitação, sem usar um agente de dados salvo. Para conversas com várias interações, o aplicativo precisa gerenciar e fornecer o histórico da conversa com cada solicitação.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-22 UTC."],[],[],null,["# Conversational Analytics API: Build data agents and chat with your data\n\n| This product or feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA products and features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n| **Important:** The Data QnA API is deprecated. If you're migrating from the Data QnA API, see the [migration guide](/gemini/docs/conversational-analytics-api/migration-guide) for an overview of key differences and required migration steps.\n\nDevelopers can use the Conversational Analytics API, which is accessed through `geminidataanalytics.googleapis.com`, to build an artificial intelligence (AI)-powered chat interface, or data agent, that answers questions about structured data in BigQuery, Looker, and Looker Studio using natural language. With the Conversational Analytics API, you provide your data agent with business information and data (\"context\"), as well as access to tools such as SQL, Python, and visualization libraries. These agent responses are presented to the user and can be logged by the client application, creating a seamless and auditable data chat experience.\n\nLearn [how and when Gemini\nfor Google Cloud uses your data](/gemini/docs/discover/data-governance).\n| As an early-stage technology, Gemini for Google Cloud\n| products can generate output that seems plausible but is factually incorrect. We recommend that you\n| validate all output from Gemini for Google Cloud products before you use it.\n| For more information, see\n| [Gemini for Google Cloud and responsible AI](/gemini/docs/discover/responsible-ai).\n| **Note:** Pre-GA Preview offerings (1) are intended for use in test environments only and shouldn't be used in a production environment or to process personal data or other data subject to legal or regulatory compliance requirements, and (2) are subject to the Pre-GA Offerings Terms of the [Service Specific Terms](/terms/service-terms#1), and the [Consent Addendum for Gemini for Google Cloud Trusted Tester Program](/trusted-tester/gemini-for-google-cloud-preview).\n\nGet started with the Conversational Analytics API\n-------------------------------------------------\n\nTo start using the Conversational Analytics API, you can first review the [architecture and key concepts](/gemini/docs/conversational-analytics-api/key-concepts) documentation to understand how agents process requests, the workflows for agent creators and users, conversation modes, and Identity and Access Management (IAM) roles. Then, to start building data agents, you can choose between a guided experience with the [Colaboratory notebooks](#interactive-colab-notebooks) or a self-driven approach by following the steps in [Setup and prerequisites](#setup).\n\n### Interactive Colaboratory notebooks\n\nFor an interactive, step-by-step guide to setting up your environment, building a data agent, and making API calls, see the following Colaboratory notebooks:\n\n- [Conversational Analytics API HTTP Colaboratory notebook](https://colab.research.google.com/github/GoogleCloudPlatform/generative-ai/blob/main/agents/gemini_data_analytics/intro_gemini_data_analytics_http.ipynb)\n- [Conversational Analytics API SDK Colaboratory notebook](https://colab.research.google.com/github/GoogleCloudPlatform/generative-ai/blob/main/agents/gemini_data_analytics/intro_gemini_data_analytics_sdk.ipynb)\n\n### Setup and prerequisites\n\nBefore you use the API or the examples, complete the following steps:\n\n- [Enable the Conversational Analytics API](/gemini/docs/conversational-analytics-api/enable-the-api): Describes prerequisites to enable the Conversational Analytics API.\n- [Grant Conversational Analytics API IAM roles and permissions](/gemini/docs/conversational-analytics-api/access-control): Describes the predefined IAM roles for managing access to data agents.\n- [Authenticate and connect to a data source with the Conversational Analytics API](/gemini/docs/conversational-analytics-api/authentication): Provides instructions for authenticating to the API and configuring connections to your BigQuery, Looker, and Looker Studio data.\n\n### Build and interact with a data agent\n\nAfter completing the previous steps, use the Conversational Analytics API to build and interact with a data agent by following these steps:\n\n- [Build a data agent using HTTP](/gemini/docs/conversational-analytics-api/build-agent-http): Provides a complete example of building and interacting with a data agent by using direct HTTP requests with Python.\n- [Build a data agent using the Python SDK](/gemini/docs/conversational-analytics-api/build-agent-sdk): Provides a complete example of building and interacting with a data agent by using the Python SDK.\n- [Write effective system instructions](/gemini/docs/conversational-analytics-api/data-agent-system-instructions): Learn how to structure the YAML content for the `system_instruction` parameter to guide agent behavior and improve response accuracy. You can also view examples of system instructions in [BigQuery data sources](/gemini/docs/conversational-analytics-api/data-agent-authored-context-bq) and in [Looker data sources](/gemini/docs/conversational-analytics-api/data-agent-authored-context-looker).\n- [Render a Conversational Analytics API agent response as a visualization](/gemini/docs/conversational-analytics-api/render-visualization): Provides an example of processing chart specifications from API responses and rendering them as visualizations by using the Python SDK and the Vega-Altair library.\n\nBest practices\n--------------\n\n- [Manage BigQuery costs for your agents](/gemini/docs/conversational-analytics-api/manage-costs): Learn how to monitor and manage BigQuery costs for your Conversational Analytics API agents by setting project-level, user-level, and query-level spending limits.\n\nKey API operations\n------------------\n\nThe API provides the following core endpoints for managing data agents and conversations:\n\nSend feedback\n-------------\n\nUse the following links to file a bug or request a feature.\n\n- [File a bug report](https://issuetracker.google.com/issues/new?component=1747873&template=2128893)\n- [File a feature request](https://issuetracker.google.com/issues/new?component=1747873&template=2131795)\n\nSend feedback\n-------------\n\nUse the following links to file a bug or request a feature.\n\n- [File a bug report](https://issuetracker.google.com/issues/new?component=1747873&template=2128893)\n- [File a feature request](https://issuetracker.google.com/issues/new?component=1747873&template=2131795)\n\nAdditional resources\n--------------------\n\n- [Conversational Analytics API reference documentation](/gemini/docs/conversational-analytics-api/reference/rest): Provides detailed descriptions of methods, endpoints, and type definitions for request and response structures.\n- [Troubleshoot Conversation Analytics API errors](/gemini/docs/conversational-analytics-api/troubleshoot-ca-errors): Troubleshoot common Conversation Analytics API errors."]]
