构建代理¶

代理结构¶

代理由以下部分组成：

• 为代理行为奠定基础的基础模型

• 解释意图、选择正确工具并规划操作序列的模型（协调器）

• 有关代理行为的说明

• 供代理使用的工具

• 工具的资源

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

有关代理的其他组件的信息，请参阅 Cortex Agents。

先决条件¶

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

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

CopyExpand

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>;

Show lessSee more

Scroll to top

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

• 用于连接到代理的语义视图

  有关创建语义视图的信息，请参阅 语义视图概述。

• 用于连接到代理的 Cortex Analyst 工具

  有关创建 Cortex Analyst 工具的信息，请参阅 Cortex Analyst。

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

• 用于连接到代理的 Cortex Search 工具

  有关创建 Cortex Search 工具的信息，请参阅 Cortex Search。

• 用于连接到代理的自定义工具

  有关创建用户定义函数 (UDFs) 和用作自定义工具的存储过程的信息，请参阅 使用函数和过程扩展 Snowflake。

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

代理配置基础知识¶

创建代理时，必须指定有关代理的信息，例如名称、描述和模型。您还可以指定代理可以使用的工具以及代理可以访问的资源。这些资源作为 YAML 规范在 CREATE AGENT 命令的 FROM SPECIFICATION 子句中传递。

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

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

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

仔细选择工具的数量： 每个代理都应该只能访问其需要的工具。要确定这一点，请考虑代理实现其目的所需的文件或数据。如果代理需要访问非结构化数据，请使用 Cortex Search。如果代理需要访问结构化数据，请使用 Cortex Analyst。如果代理需要其他工具，您可以使用自定义工具。

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

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

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

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

  • 该工具的用途

  • 它访问哪些数据

  • 何时使用

  • 何时 NOT 使用

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

  • 具体明确。

  • 指定数据格式。

  • 提供清晰的数据说明。

  • 提供默认指导。

  • 使用一致的术语。

有关更多代理配置建议，请参阅 构建 Cortex Agent 的最佳实践。

模型选择¶

创建代理时，我们建议您为模型选择 auto。使用此选项，Cortex 会自动为您的账户选择最高质量的模型，并且随着新模型的推出，质量会自动提高。有关可用模型的更多信息，请参阅 支持的模型和区域。

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

models:
  orchestration: auto

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

使用 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>"

Connect Cortex Search（非结构化数据）¶

要处理非结构化数据，您可以通过在 YAML 规范中将 Cortex Search 工具指定为工具资源的一部分，将其连接到代理。Cortex Search 服务使用语义搜索从非结构化数据源中检索文档和记录。Cortex Search 的两个主要用例是检索增强生成 (RAG) 和企业搜索。有关创建 Cortex Search Service 的信息，请参阅 Cortex Search。您也可以使用与您共享的 Cortex Knowledge Extension (CKE)。

将 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 来创建代理：

  CopyExpand

  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"
      system: "You are a friendly agent that helps with business questions"
      sample_questions:
          - question: "What was our revenue last quarter?"
          answer: "I'll analyze the revenue data using our financial database."
  
      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>"
      $$;
  

  Show lessSee more

  Scroll to top

修改现有代理¶

有关修改现有代理配置（包括添加工具及更新其他详细信息）的操作说明，请参阅 Add tools。