构建代理

You can build agents for Snowflake Intelligence using the following methods:

The following sections provide information about how to build agents for Snowflake Intelligence using SQL commands. Each section provides information about a different part of the agent configuration. The final section shows an example of an agent configuration that includes all of the components described in this topic.

For more information about the other methods to create an agent and the options available, see Configure and interact with Agents.

代理结构

代理由以下部分组成：

  • 为代理行为奠定基础的基础模型
  • 解释意图、选择正确工具并规划操作序列的模型（协调器）
  • 有关代理行为的说明
  • 供代理使用的工具
  • 工具的资源

以下部分提供有关模型选择和工具配置的信息。此示例使用语义视图、Cortex Search Service 和自定义工具来提供答案。尽管您可以创建不使用任何这些工具的基本代理，但该基本代理仅使用基本模型来提供答案。因此，该代理无法访问您的 Snowflake 账户中的数据，并且获得答案的背景有限。

For information about the other components of the agent, see Cortex Agents.

先决条件

要创建 Cortex Agent，必须使用具有以下权限的角色：

权限对象备注
CREATE AGENT架构这是创建 Cortex 代理所必需的。
USAGE数据库、架构在指定的数据库和架构中创建 Cortex Agent 时需要此权限。

以下代码授予创建 Cortex Agent 所需的权限：

GRANT USAGE ON DATABASE <database_name> to ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;
GRANT CREATE AGENT ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;

除了创建 Cortex Agent 所需的权限外，将代理连接到特定工具还需要满足以下先决条件：

  • A semantic view to connect to the agent

    For information about creating a semantic view, see Overview of semantic views.

  • A Cortex Analyst tool to connect to the agent

    For information about creating a Cortex Analyst tool, see Cortex Analyst.

  • 数据库中用于连接到代理的非结构化数据

  • A Cortex Search tool to connect to the agent

    For information about creating a Cortex Search tool, see Cortex Search.

  • A custom tool to connect to the agent

    For information about creating user-defined functions (UDFs) and stored procedures to use as custom tools, see Extending Snowflake with Functions and Procedures.

要将工具附加到代理，用于创建代理的角色必须具有以下权限：

权限对象备注
USAGECortex Search Service将 Cortex Search Service 添加到 Cortex Agent 时需要此权限。
SELECT表/视图访问代理的语义视图/模型中引用的对象时需要。
USAGE工具访问所有要附加到代理的自定义工具时需要。例如，如果自定义工具是存储过程，则您必须对该过程具有 USAGE 权限。
USAGE语义视图/模型访问要附加到代理的语义视图/模型时需要。

代理配置基础知识

When you create an agent, you must specify information about the agent, such as the name, description, and model. You can also specify the tools that the agent can use and the resources that the agent can access. These resources are passed as a YAML specification in the FROM SPECIFICATION clause of the CREATE AGENT command.

以下建议提供了此配置的最佳实践：

缩小代理范围： 在添加工具或编写指令之前，定义代理存在的原因、其服务对象以及它应回答的具体问题。这一步决定了后续的一切，从工具选择到性能和信任。Snowflake 建议您将代理的范围缩小到特定的高价值用例。

在代理证明其在某一领域可靠后，您可以为其他领域复制该模式。例如，您可以让一个代理分析商店最近的销售和营销数据，而让另一个代理推荐最适合向零售商推销的 SKUs。

Select the number of tools carefully: Every agent should have access to only the tools it needs. To determine that, consider the documents or data that the agent needs to fulfill its purpose. If the agent needs to access unstructured data, use Cortex Search. If the agent needs to access structured data, use Cortex Analyst. If the agent needs other tools, you can use custom tools.

编写有用的工具描述： 这些描述用于帮助代理理解该工具的功能以及如何使用它。不清晰的工具描述可能会导致级联故障并产生“幻觉”。

要创建有用的工具描述，请遵循以下准则：

  • 添加清晰且具体的工具名称，以明确工具的领域（“Customer”、“Sales”）和功能（“Analytics”、“Search”）。

  • 编写以目的为导向的工具描述，告知代理：

    • 该工具的用途
    • 它访问哪些数据
    • 何时使用
    • 何时 NOT 使用

  • 明确工具的预期输入。对工具的模糊输入会导致不正确的工具调用和错误。

    • 具体明确。
    • 指定数据格式。
    • 提供清晰的数据说明。
    • 提供默认指导。
    • 使用一致的术语。

For more agent configuration recommendations, see Best Practices for Building Cortex Agents.

For guidance on evaluating reliability and behavior, see Best Practices for Evaluating Cortex Agents.

模型选择

When you create an agent, we recommend that you select auto for the model. With this option, Cortex automatically selects the highest quality model for your account, and the quality automatically improves as new models become available. For more information about the available models, see Supported models and regions.

以下示例演示如何为代理指定模型：

models:
  orchestration: auto

跨区域推理

Important

默认情况下，跨区域推理处于禁用状态。我们建议使用跨区域推理来访问完整的 LLMs，并避免单个区域内的限制。

使用本地区域不可用的模型时，必须使用 Cortex 跨区域推理。此设置允许在与默认区域不同的区域中处理推理请求。跨区域推理的参数只能在账户级别由 ACCOUNTADMIN 角色设置，而不能在用户或会话级别设置。

要设置参数，请使用以下命令：

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

For more information about configuring Cortex cross-region inference, see Cross-region inference.

使用 Cortex Analyst 连接语义视图（结构化数据）

Snowflake Intelligence 支持语义视图，这是一种带有指令的结构化数据，用于告诉代理如何查询或解释数据。Cortex Agent 使用 Cortex Analyst 从语义视图中检索结构化数据，方法是将自然语言请求转换为 SQL 查询。代理可以在多个语义视图之间路由以提供响应。

每个语义视图都应涵盖一组相似的表。您可以设置特定于数据的默认值，例如：如果未指定，则始终添加过去三个月的日期筛选器，或者始终排除内部账户。

您可以通过将语义视图指定为工具资源的一部分，将其连接到代理。以下示例演示如何将语义视图连接到代理，以及如何指定 Cortex Analyst 工具从语义视图中检索结构化数据：

tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "<your cortex analyst tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex analyst tool name>:
    semantic_view: "<db>.<schema>.<semantic_view>"

语义视图的最佳实践

Semantic views power how Snowflake Intelligence understands and queries your data. A well-designed semantic view improves accuracy, reduces latency, and builds user trust. The following best practices are designed to help you create a semantic view that is accurate and efficient:

从小处着手，重点突出： 从单个业务域中的 5-10 个表开始。按用例（销售业绩、客户支持指标）而不是按数据结构进行组织。在验证准确性后再进行扩展。

编写清晰的描述： 描述是最重要的元素。每个表和列都应该有一个适合业务的描述，解释数据所代表的内容，而不仅仅是其名称。包括计算逻辑、业务定义和任何旧术语等上下文。

添加已验证的查询： 这些是将问题与经过验证的 SQL 配对的示例。它们可以提高类似问题的准确性，减少延迟，并帮助系统了解您的业务模式。从涵盖最常见问题的 10 到 20 个查询开始，然后根据实际使用情况添加更多查询。

定义指标和筛选器： 预定义可重复使用的计算（如总收入或平均订单价值）和常用条件（如活跃客户或当前会计年度）。这些可以显著提高一致性。

为业务逻辑使用自定义指令： 为数据特性、会计年度定义、默认筛选器或特定于域的规则添加 SQL 生成指令。具体说明：“如果未提供日期筛选器，则默认为过去 12 个月”比“按日期筛选”更好。

启用 Cortex Search 进行文本匹配： 对于高基数文本列（如产品名称、客户名称或公司名称），当用户输入与数据不完全匹配时，Cortex Search 会启用模糊匹配。

测试和迭代： 创建代表性问题的评估集，衡量准确性，并根据实际使用模式进行完善。定期查看建议，以便添加经过验证的查询并随着时间的推移改进描述。

For more information about best practices for creating semantic views, see Best Practices for Semantic Views in Cortex Analyst.

To process unstructured data, you can connect a Cortex Search tool to an agent by specifying the Cortex Search tool in the YAML specification as part of the tool resources. Cortex Search services retrieve documents and records from unstructured data sources using semantic search. The two primary use cases for Cortex Search are retrieval augmented generation (RAG) and enterprise search. For information about creating a Cortex Search service, see Cortex Search. You can also use a Cortex Knowledge Extension (CKE) that is shared with you.

将 Cortex Search 工具连接到代理时，包含以下有关参数及其预期值的信息尤为重要：

  • 类型和格式（包括示例）
  • 是必填还是可选（含默认值）
  • 有效值或约束（枚举、范围、格式）
  • 与其他参数的关系（依赖关系、冲突）
  • 如何获取值（尤其是针对 IDs）

以下示例演示了如何将 Cortex Search 工具连接到代理，以及如何在 YAML 规范中指定 Cortex Search 工具：

tools:
  - tool_spec:
      type: "cortex_search"
      name: "<your cortex search tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex search tool name>:
    name: "<db>.<schema>.<search_service_name>"
    max_results: "5"
    filter:
      "@eq":
        region: "North America"
    title_column: "<title_name>"
    id_column: "<column_name>"

添加自定义工具

Snowflake Intelligence 支持自定义工具，这些工具是用户定义的函数或存储过程，可用于实现自定义业务逻辑。您可以通过在 YAML 规范中将自定义工具指定为工具资源的一部分，从而将其连接到代理。

以下示例展示了如何将自定义工具连接到代理，以及如何在 YAML 规范中指定该自定义工具：

tools:
  - tool_spec:
      type: "custom_tool"
      name: "<your custom tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your custom tool name>:
    user-defined-function-argument: "argument1"

创建代理

  • 结合使用所有工具和组件，并使用 SQL 来创建代理： 
    CREATE OR REPLACE AGENT <agent_name>
 COMMENT = 'agent level comment'
 PROFILE = '{"display_name": "My Business Assistant", "avatar":  "business-icon.png", "color": "blue"}'
 FROM SPECIFICATION
 $$
 models:
 orchestration: claude-4-sonnet

 orchestration:
 budget:
     seconds: 30
     tokens: 16000

 instructions:
 response: "You will respond in a friendly but concise manner"
 orchestration: "For any revenue question, use Analyst; for policy questions, use Search"
 sample_questions:
     - question: "What was our revenue last quarter?"

 tools:
 - tool_spec:
     type: "cortex_analyst_text_to_sql"
     name: "<your cortex analyst tool name>"
     description: "<clear and specific tool description>"
 - tool_spec:
     type: "cortex_search"
     name: "<your cortex search tool name>"
     description: "<clear and specific tool description>"
 - tool_spec:
     type: "data_to_chart"
     name: "data_to_chart"
     description: "Generates visualizations from data"

 tool_resources:
 <your cortex analyst tool name>:
     semantic_view: "<db>.<schema>.<semantic_view>"
 <your cortex search tool name>:
     name: "<db>.<schema>.<search_service_name>"
     max_results: "5"
     filter:
     "@eq":
         region: "North America"
     title_column: "<title_name>"
     id_column: "<column_name>"
 $$;

修改现有代理

For instructions on modifying the configuration for an existing agent, including adding tools and updating other details, see Add tools.