本页面介绍了如何通过系统指令编写有效的提示，并针对 BigQuery 数据额外提供结构化上下文，从而以最佳方式为您的 Conversational Analytics API 数据代理提供编写的上下文。虽然提供编写的上下文并非强制性要求，但结构清晰的编写的上下文可以提高 API 所提供回答的准确性和相关性。
编写的上下文指的是什么？
编写的上下文是一种指导性内容，开发者可以通过提供编写的上下文来引导数据代理的行为并优化 API 的回答。该指导性内容包括自由格式的系统指令，以及针对 BigQuery 数据源的结构化上下文字段，其中包含表说明和示例查询等信息。为了回答问题，代理会将此编写的上下文与数据源（例如 BigQuery 表、Looker 探索和 Looker Studio 数据源）中的信息以及对话记录（针对多轮对话）相结合。
通过结构化上下文字段和自由格式系统指令提供明确的指导，您可以提高代理解读用户问题和生成有用且准确回答的能力。如果您要连接到 BigQuery 表等数据，那么提供明确定义的上下文则尤为重要。例如，您可以使用编写的上下文向代理提供以下类型的指导：
- 业务特定逻辑：将“忠实”客户定义为在特定时间范围内购买次数超过 5 次的客户。
- 回答格式：将数据智能体的所有回答总结为不超过 20 个字，以节省用户的时间。
- 数据呈现：将所有数字的格式设置为符合公司的风格指南。
提供编写的上下文
您可以提供的具体信息取决于您的数据源：
- 对于 BigQuery 数据，您可以同时定义结构化上下文和系统指令。为获得最佳结果，请先通过可用的结构化字段为代理提供上下文。然后，您可以通过定义系统指令来提供补充指导。
- 对于 Looker 数据，编写的上下文只能通过系统指令提供。
您可以在 API 字段中提供结构化上下文，以提供表说明和示例查询等详细信息。您可以使用 system_instruction 参数以 YAML 格式的字符串形式提供系统指令。
定义编写的上下文后，您可以通过以下任一调用将其提供给 API：
- 创建持久化数据代理：在请求正文的
published_context对象中添加编写的上下文，以配置可在多轮对话中保持的代理行为。如需了解详情，请参阅创建数据代理 (HTTP) 或为有状态或无状态聊天设置上下文 (Python SDK)。 - 发送无状态请求：在聊天请求的
inline_context对象中提供编写的上下文，以定义该代理在相应 API 调用期间的行为。如需了解详情，请参阅创建无状态多轮对话 (HTTP) 或发送包含内嵌上下文的无状态聊天请求 (Python SDK)。
构建智能体的最佳实践：对编写的上下文使用版本控制
使用 stagingContext、publishedContext 和 lastPublishedContext 字段，在通过 Conversational Analytics API 构建智能体时控制上下文版本。以下用例展示了如何使用这些字段来创建智能体上下文的预发布版本和正式版。
假设您使用的是具有 publishedContext 字段的现有智能体，但您需要对该智能体进行更新（例如，将所有图表都设为绿色，而不是蓝色）。
如需进行更改并在发布前进行测试，请按以下步骤操作：
- 在
stagingContext字段中对智能体进行更改，并测试更改后的智能体。 - 当更改准备就绪后，请使用
stagingContext中的更改更新publishedContext字段。 - 您可以根据需要将
publishedContext更新为lastPublishedContext，以恢复为旧版智能体。