Cortex Agents¶

Cortex Agents 可协调处理结构化和非结构化数据源，从而提供见解。该服务可规划任务，使用工具执行这些任务，并生成响应。代理使用 |cortex-analyst|（结构化）和 Cortex Search（非结构化）作为工具，并结合 LLMs，用分析数据。Cortex Search 从非结构化来源中提取见解，而 |cortex-analyst| 生成 SQL 以处理结构化数据。全面的工具识别与工具执行支持，可实现基于企业数据的复杂应用程序交付。

该工作流涉及四个关键组件：

规划：应用程序通常需要在结构化与非结构化数据源之间切换处理。以设计用于回答用户查询的对话式应用程序为例。企业用户可能首先查询按收入排序的顶级分销商（结构化数据），随后转向询问合同细节（非结构化数据）。Cortex Agents 可以解析请求以编排计划并得出解决方案或响应。
1. 探索选项：当用户提出模糊查询时（例如“请介绍 Acme Supplies”），代理程序会考量不同衍生维度（产品、地理位置或销售人员）以消除歧义并提升准确性。
2. 拆分为子任务：Cortex代理程序可将任务或请求（例如“Acme Supplies 与 Acme Stationery 的合同条款有何差异？”）拆分为多个部分，以提供更精准的响应。
3. 跨工具路由：代理会精准选择工具 Cortex Analyst 或 Cortex Search，以确保受控访问并符合企业策略。
工具使用：制定计划后，代理可以有效地检索数据。Cortex Search 从非结构化来源中提取见解，而 Cortex Analyst 生成 SQL 以处理结构化数据。全面的工具识别与工具执行支持，可实现基于企业数据的复杂应用程序交付。
反射：在每次工具调用后，代理会评估结果以确定后续步骤，包括请求澄清、迭代处理或生成最终响应。通过这种编排机制，代理可在 Snowflake 安全边界内处理复杂数据查询，同时确保准确性与合规性。
监控和迭代：部署后，客户可以跟踪指标、分析性能并优化行为以实现持续改进。客户端应用程序开发人员可使用 TruLens 监控代理的交互过程。通过持续监控和完善治理控制，企业可以自信地进行扩展 AI 代理，同时保持安全性和合规性。

有关帮助您入门的教程，请参阅 Cortex Agents 教程。

备注

尽管 Snowflake 致力于提供高质量响应，但 LLM 生成的响应内容及其引用来源的准确性不作保证。在向用户提供代理 API 生成的答案前，您应当审核所有响应内容。

访问控制要求¶

查询用户必须满足以下条件：

对查询中引用的 Cortex Search 服务拥有 USAGE 权限
对 Cortex Analyst 语义模型引用的数据库、架构和表拥有 USAGE 权限
具有被授予 CORTEX_USER 数据库角色的权限。有关更多信息，请参阅所需权限。

如何使用代理 API¶

本节介绍使用代理 API 创建代理的步骤。

配置密钥对身份验证¶

目前，Snowflake REST APIs 仅支持通过 JWT 令牌进行身份验证。要使用 JWT 令牌查询代理 API REST 端点，必须先配置密钥对验证。请参阅使用密钥对身份验证以获取说明。随后，您必须使用配置好的密钥对验证生成 JWT 令牌。生成令牌的一种方法是使用 snowSQL (https://community.snowflake.com/s/article/How-To-Use-SnowSQL-to-generate-JWT-Token-for-Key-Pair-Authentication-Mechanism)。

为 Cortex Analyst 创建语义模型¶

您可以使用 Cortex Analyst 将自然语言转换为 SQL 查询。要使用 Cortex Analyst，您必须创建一个语义模型。有关更多信息，请参阅创建语义模型。

创建 Cortex Search 服务¶

使用 Cortex Search 搜索您的数据。有关更多信息，请参阅 CREATE CORTEX SEARCH SERVICE。

备注

查询用户的 DEFAULT_ROLE 必须对Cortex Search 服务及其所在的数据库和架构拥有 USAGE 权限。

调用 API¶

首先，找到您的 Snowflake 账户 URL。当您获得 URL 和 JWT 令牌后，即可使用 cURL 通过以下语法从命令行查询代理 API：

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/agent:run" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $YOUR_JWT" \
--data '{
    "model": "llama3.1-70b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "what are the top 3 customers by revenue"
                }
            ]
        }
    ],
    "tools": [
        {
            "tool_spec": {
                "type": "cortex_search",
                "name": "transcript_search"
            }
        },
        {
            "tool_spec": {
                "type": "cortex_analyst_text_to_sql",
                "name": "data_model"
            }
        }
    ],
    "tool_resources": {
        "transcript_search": {"name": "testdb.testschema.transcript_search_service"},
        "data_model": {"semantic_model_file": "@testdb.testschema.stage/sample_data_model.yaml"}
    }
}'

Copy

响应以增量方式流式传输到客户端。

支持的模型¶

您可以将以下模型与 Cortex Agent 结合使用来生成响应。请注意，该模型不用于编排。

llama3.1-70b
llama3.3-70b
mistral-large2
claude-3-5-sonnet

您还可以指定响应指令来自定义代理的响应。

{
    "response_instruction": "You will always maintain a friendly tone and provide concise response"
}

Copy

重要

Cortex Agents 使用的模型可能并非在所有区域都可用。有关更多信息，请参阅可用性。

区域可用性¶

Cortex Agents 功能在以下区域可用：

函数（模型）	AWS US 西部 2 （俄勒冈）	AWS US 东部 1 （弗吉尼亚北部）	AWS 欧洲中部 1 （法兰克福）	AWS 欧洲西部 1 （爱尔兰）	AWS AP 东南部 2 （悉尼）	AWS AP 东北部 1 （东京）	Azure 东部 US 2 （弗吉尼亚）	Azure 西欧（荷兰）	AWS （跨区域）
COMPLETE (`claude-3-5-sonnet`)	✔	✔							✔
COMPLETE (`llama3.2-1b`)	✔								✔
COMPLETE (`llama3.2-3b`)	✔								✔
COMPLETE (`llama3.1-8b`)	✔	✔	✔	✔		✔	✔	✔	✔
`llama3.1-70b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`llama3.3-70b`	✔					✔			✔
`snowflake-llama-3.3-70b`	✔								✔
`llama3.1-405b`	✔	✔					✔		✔
`snowflake-llama-3.1-405b`	✔								✔
`snowflake-arctic`	✔						✔		✔
`deepseek-r1`									✔
`reka-core`		✔							✔
`reka-flash`	✔	✔				✔			✔
`mistral-large2`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`mixtral-8x7b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`mistral-7b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`jamba-instruct`	✔		✔			✔			✔
`jamba-1.5-mini`	✔		✔			✔			✔
`jamba-1.5-large`	✔								✔
`gemma-7b`	✔	✔	✔				✔	✔	✔
`e5-base-v2`	✔	✔	✔			✔	✔	✔	✔
`snowflake-arctic-embed-m`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-m-v1.5`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-l-v2.0`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`nv-embed-qa-4`	✔								✔
`multilingual-e5-large`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`voyage-multilingual-2`	✔	✔	✔	✔	✔	✔	✔	✔	✔

成本注意事项¶

在预览版中，Cortex Search 服务根据 `Snowflake 服务使用表<https://www.snowflake.com/legal-files/CreditConsumptionTable.pdf>`__ 中列出的明细产生费用。

构建 Cortex Agents¶

我们将使用 Cortex Agents 实现一个对话式应用程序，用于解答业务用户关于合同条款的查询。让我们回顾一下主要组件。（有关完整教程，请参阅 Cortex Agents 入门 (https://quickstarts.snowflake.com/guide/getting_started_with_cortex_agents/index.html?index=..%2F..index#1)）。

第 1 步：指定要在请求中使用的工具

{
    "tools": [
        {
            "tool_spec": {
                "name": "data_model",
                "type": "cortex_analyst_text_to_sql"
            }
        },
        {
            "tool_spec": {
                "name": "transcript_search",
                "type": "cortex_search"
            }
        },
        {
            "tool_spec": {
                "type": "sql_exec",
                "name": "sql_exec"
            }
        },
        {
            "tool_spec": {
                "type": "data_to_chart",
                "name": "data_to_chart"
            }
        }
    ]
}

Copy

第 2 步：为Cortex Agent的工具调用提供静态实参（资源）。

{
    "tool_resources": {
        "data_model": {
            "semantic_model_file": "@cortex_tutorial_db.public.revenue_semantic_model.yaml"
        },
        "transcript_search": {
            "name": "cortex_tutorial_db.public.contract_terms",
            "max_results": 5,
            "title_column": "TRANSCRIPT_TITLE",
            "id_column": "TRANSCRIPT_ID",
            "filter": {"@eq": {"TRANSCRIPT_TYPE": "ENTERPRISE"} }
        }
    }
}

Copy

第 3 步：现在，我们将指定模型和系统提示以生成响应

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": {
                "type": "text",
                "text": "You’re a friendly assistant to answer questions."
            }
        }
    ]
}

Copy

第 4 步：创建一个将被分析工具用于访问结构化数据的语义模型文件。

按照本指南中的步骤 1 至 3 创建 Cortex Analyst 语义模型 Cortex Agents 入门 (https://quickstarts.snowflake.com/guide/getting_started_with_cortex_agents/index.html?index=..%2F..index#1)

第 5 步：接下来，我们将为 Search 工具设置搜索服务以访问非结构化数据。

按照本指南中的第 4 到第 5 步创建 Cortex Search 服务 Cortex 代理入门 (https://quickstarts.snowflake.com/guide/getting_started_with_cortex_agents/index.html?index=..%2F..index#1)

第 6 步：现在，我们已准备好与代理进行交互。您将使用 messages 字段发送请求和接收响应

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "You’re a friendly assistant to answer questions"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "hello"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "hi there!"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "..."
                }
            ]
        }
    ]
}

Copy

第 7 步：随着交互的进行，代理会识别工具并执行（服务端）以完成任务。在下面的示例中，代理将 Text2SQL 标识为工具并执行，以获取 SQL 查询。在交互期间，代理可以请求客户端应用程序（客户端）使用工具。例如，代理会指定需要执行的 SQL 查询。

{
    "role": "assistant",
    "content": [
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_001",
                "name": "cortex_analyst_text_to_sql",
                "input": {
                    "query": "...",
                    "semantic_model_file": "..."
                }
            }
        },
        {
            "type": "tool_results",
            "tool_results": {
                "status": "success",
                "tool_use_id": "tool_001",
                "content": [
                    {
                        "type": "json",
                        "json": {
                            "sql": "select * from table"
                        }
                    }
                ]
            }
        },
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_002",
                "name": "sql_exec",
                "input": {
                    "sql": "select * from table"
                }
            }
        }
    ]
}

Copy