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 how to best provide authored context to your Conversational Analytics API data agents by writing effective prompts through system instructions and, for BigQuery data, by additionally providing structured context. While providing authored context is optional, well-structured authored context can improve the accuracy and relevance of the responses that the API provides.

What is authored context?

Authored context is guidance that developers can provide to shape the behavior of a data agent and to refine the API's responses. This guidance includes free-form system instructions and, for BigQuery data sources, structured context fields with information such as table descriptions and sample queries. To answer questions, the agent combines this authored context with information from data sources (such as BigQuery tables, Looker Explores, and Looker Studio data sources) and with conversation history (for multi-turn conversations).

By providing clear guidance through structured contextual fields and free-form system instructions, you can improve the agent's ability to interpret user questions and generate useful and accurate responses. Well-defined context is especially useful if you're connecting to data such as BigQuery tables. For example, you can use authored context 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 authored context

The specific information that you can provide depends on your data source:

• For BigQuery data, you can define both structured context and system instructions. For best results, first provide context to the agent through the available structured fields. You can then provide supplemental guidance by defining system instructions.
• For Looker data, authored context is provided only through system instructions.

You provide structured context in API fields for details like table descriptions and sample queries. You provide system instructions as a YAML-formatted string by using the system_instruction parameter.

After you define your authored context, you can provide it to the API in one of the following calls:

• Creating a persistent data agent: Include authored context 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 authored context within the inline_context object in a chat request to define the agent's behavior for 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

• Build a data agent using HTTP and Python
• Build a data agent using the Python SDK
• Define data agent context for BigQuery data sources
• Define data agent context for Looker data sources