このドキュメントでは、Conversational Analytics API（geminidataanalytics.googleapis.com）を使用するための重要なコンセプトについて説明します。この API を使用すると、自然言語を使用して構造化データに関する質問に回答するデータ エージェントを作成して操作できます。このドキュメントでは、エージェントの仕組み、一般的なワークフロー、会話モード、Identity and Access Management（IAM）ロール、複数のエージェントを含むシステムを設計する方法について説明します。
データ エージェントの仕組み
Conversational Analytics API のデータ エージェントは、ユーザーが提供するコンテキスト（ビジネス情報とデータ）とツール（SQL や Python など）を使用して、自然言語の質問を解釈し、構造化データから回答を生成します。
[[["わかりやすい","easyToUnderstand","thumb-up"],["問題の解決に役立った","solvedMyProblem","thumb-up"],["その他","otherUp","thumb-up"]],[["わかりにくい","hardToUnderstand","thumb-down"],["情報またはサンプルコードが不正確","incorrectInformationOrSampleCode","thumb-down"],["必要な情報 / サンプルがない","missingTheInformationSamplesINeed","thumb-down"],["翻訳に関する問題","translationIssue","thumb-down"],["その他","otherDown","thumb-down"]],["最終更新日 2025-09-04 UTC。"],[],[],null,["# Conversational Analytics API architecture and key concepts\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\nThis document describes the key concepts for using the Conversational Analytics API (`geminidataanalytics.googleapis.com`), which lets you create and interact with data agents that use natural language to answer questions about your structured data. This document describes how agents work, typical workflows, conversation modes, Identity and Access Management (IAM) roles, and how to design systems with multiple agents.\n\nHow data agents work\n--------------------\n\nConversational Analytics API data agents use *context* that you provide (business information and data) and tools (such as SQL and Python) to interpret natural language questions and generate responses from your structured data.\n\nThe following diagram illustrates the stages of an agent's workflow when a user asks a question:\n\nAs shown in the diagram, when a user asks a question, the agent processes the request in the following stages:\n\n1. **User input**: The user submits a question in natural language, along with any additional context you provide.\n2. **Data sources**: The agent connects to your data in Looker, BigQuery, and Looker Studio to retrieve the necessary information.\n3. **Reasoning engine**: The core of the agent processes the user's question by using available tools to generate an answer.\n4. **Agent output**: The agent generates a response, which can include text, data tables, or specifications for charts.\n\nWorkflows for designing and using agents\n----------------------------------------\n\nThe Conversational Analytics API supports workflows for agent creators (who build and configure agents) and for agent consumers (who interact with agents).\n\nThe following diagram illustrates the end-to-end process, from the initial setup by an agent creator to the final interactions from an agent consumer:\n\nThe following sections describe the workflows for agent creators and agent consumers in more detail.\n\n### The agent creator workflow\n\nThe agent creator is responsible for setting up and configuring agents. This workflow involves the following steps:\n\n1. **Create agent**: The creator starts by creating a new agent and providing the necessary context, including system instructions and connections to data sources. This step is crucial for enabling the agent to understand and respond to user questions effectively.\n2. **Share the agent**: Once the agent is configured, the creator shares it with other users and sets the appropriate role-based access controls to manage permissions.\n\n### The agent consumer workflow\n\nThe agent consumer is typically a business user who needs to get answers from a configured agent. This workflow involves the following steps:\n\n1. **Find an agent**: The user starts by finding an agent that has been shared with them.\n2. **Ask a question**: The user asks a question in natural language. This question can be a single query or part of a multi-turn conversation.\n3. **Agent \"thinks\"**: The agent's reasoning engine processes the question. The reasoning engine uses the agent's predefined knowledge and available agent tools (like SQL, Python, and charts) in a \"reasoning loop\" to determine the best way to answer the question.\n4. **Agent responds**: The agent returns an answer, which can include text, data tables, or charts.\n\nConversation modes\n------------------\n\nConversational Analytics API agents support different conversation modes that determine how an agent handles conversation history and the persistence of context across interactions. The following conversation modes are available:\n\n- **Stateless mode**: The agent doesn't store conversation history. Each interaction is treated independently. This mode is useful for applications where you don't need to maintain context across multiple turns.\n- **Stateful mode**: The agent retains context and conversation history, allowing for more contextualized interactions. This mode is useful for applications where you need to maintain context across multiple turns. Using stateful mode is recommended for better accuracy and personalized responses.\n\nChoose a conversation mode based on your application's requirements for conversation history and context persistence.\n\nIAM roles\n---------\n\nIAM roles control who can create, manage, share, and interact with Conversational Analytics API agents. The following table describes the key [IAM roles for the Conversational Analytics API](/gemini/docs/conversational-analytics-api/access-control):\n\nSystems with multiple agents\n----------------------------\n\nYou can design complex systems by integrating multiple Conversational Analytics API agents. A common pattern is to use a primary \"orchestrator\" agent that delegates tasks to one or more specialized agents that handle specific domains, such as sales or marketing data. This approach lets you build a system that can handle a wide range of questions by combining the strengths of multiple agents.\n\nThe following diagram illustrates this multi-agent pattern and shows how a primary agent can delegate a data question to a specialized Conversational Analytics agent:\n\nThe typical workflow for a multi-agent system involves the following steps:\n\n1. A business user or data analyst asks a question in natural language, such as \"Show me the top three stores by revenue.\"\n2. A primary \"orchestrator\" agent delegates the request to the appropriate specialized agent.\n3. A specialized agent receives the delegated request, connects to the relevant data sources, uses its tools to generate the necessary SQL queries and charts, and generates a response.\n4. The specialized agent's response is returned to the user, such as \"Stores 4, 9, and 3 have the highest revenue. Here's a chart.\"\n\nWhat's next\n-----------\n\nAfter understanding the core concepts of the Conversational Analytics API, explore how to implement these features:\n\n- Explore how to [authenticate and connect to a data source](/gemini/docs/conversational-analytics-api/authentication).\n- Learn how to [create and configure an agent with HTTP](/gemini/docs/conversational-analytics-api/build-agent-http).\n- Learn how to [create and configure an agent with Python](/gemini/docs/conversational-analytics-api/build-agent-sdk).\n- Learn more about [guiding an agent's behavior with authored context](/gemini/docs/conversational-analytics-api/data-agent-system-instructions).\n- Understand [access control with IAM for the Conversational Analytics API](/gemini/docs/conversational-analytics-api/access-control)."]]
