Guide agent behavior with authored context

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes the recommended structure for writing effective prompts for your Conversational Analytics API data agents. These prompts are authored context that you define as strings by using the system_instruction parameter. Well-structured system instructions can improve the accuracy and relevance of the responses that the API provides.

For examples of authored context in different environments, see the following documentation pages:

• Define data agent context for BigQuery data sources
• Define data agent context for Looker data sources

What are system instructions?

System instructions are user-defined guidance that developers can provide to shape the behavior of a data agent and to refine the API's responses. System instructions are part of the context that the API uses to answer questions. This context also includes connected data sources (BigQuery tables, Looker Explores, Looker Studio data sources), and conversation history (for multi-turn conversations).

By providing clear, structured guidance through system instructions, you can improve the agent's ability to interpret user questions and generate useful and accurate responses. Well-defined system instructions are especially useful if you're connecting to data such as BigQuery tables, where there may not be a predefined semantic layer like there is with a Looker Explore.

For example, you can use system instructions to provide the following types of guidance to an agent:

• Business-specific logic: Define a "loyal" customer as one who has made more than five purchases within a certain timeframe.
• Response formatting: Summarize all responses from your data agent in 20 words or fewer to save your users time.
• Data presentation: Format all numbers to match the company's style guide.

Provide system instructions

You can provide system instructions to the Conversational Analytics API as a YAML-formatted string by using the system_instruction parameter. Although the system_instruction parameter is optional and the structure is up to your discretion, providing well-structured system instructions is recommended for accurate and relevant responses.

You can define the YAML-formatted string in your code during initial setup, as shown in Configure initial settings and authentication (HTTP) or Specify the billing project and system instructions (Python SDK). You can then include the system_instruction parameter in the following API calls:

• Creating a persistent data agent: Include the system_instruction string within the published_context object in the request body to configure agent behavior that persists across multiple conversations. For more information, see Create a data agent (HTTP) or Set up context for stateful or stateless chat (Python SDK).
• Sending a stateless request: Provide the system_instruction string within the inline_context object in the chat request to define the agent's behavior and context for the duration of that specific API call. For more information, see Create a stateless multi-turn conversation (HTTP) or Send a stateless chat request with inline context (Python SDK).

Related resources

• Define data agent context for BigQuery data sources
• Define data agent context for Looker data sources