Configure and interact with Agents¶

创建代理¶

Create an agent object by specifying the database and schema where the agent should be located, along with a name and description for the agent. In addition, specify the display name, avatar, and the color. These attributes are used by the client application to display the agent. The display name is also used as the handle to reference the agent in conversations.

For best practices when creating an agent, see Best Practices to Building Cortex Agents.

The following examples show how to create an agent object from Snowsight or using the REST API:

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

1. Sign in to Snowsight.

2. In the navigation menu, select AI & ML » Agents.

3. 选择 Create agent。

4. 对于 Agent object name，请指定代理的名称，该名称将在 UI 中向用户显示。

5. 对于 Display name，指定代理的名称，该名称将在代理列表中向管理员显示。

6. 选择 Create agent。

7. 用常识请求提示代理。

Add tools¶

After you've created the agent, you need to add tools and provide instructions on how to orchestrate across the tools. Agents support the following tool types:

• Cortex Analyst: You specify the semantic views so that Cortex Analyst can use these to retrieve structured data. The Agents can route across multiple semantic views to provide the response.

• Cortex Search: You provide the Cortex Search indices as tools, including related information like search filters, column names, and metadata. The Cortex Agent uses the Cortex Search indices to retrieve unstructured data.

• Custom tools: You can implement code for a specific business logic as a stored procedure or user defined function (UDF). Alternatively, you can use the custom tools to retrieve data from your backend systems using APIs.

You also specify the resources used by each tool. For example, on Cortex Analyst you specify the warehouse along with the timeout for SQL query execution. Similarly for Cortex Search, you specify the filters and column names used in the search query, along with the max results in the search response. For custom tools, you will provide the warehouse details.

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

To modify the configuration for an existing agent, follow these steps:

1. In the navigation menu, select AI & ML » Agents.

2. From the list of agents, select the agent that you want to modify.

   The configuration details for the agent are displayed.

3. 选择 Edit。

4. 对于 Description，请描述代理以及用户与之交互的方式。

5. 要添加用户可以向代理询问的示例问题，请输入示例问题并选择 Add a question。

6. Select Tools. Add one or more of the following tools.

   • To add a semantic view in Cortex Analyst to the agent: This section assumes that you already have a semantic view created. For information about semantic views and how to create one, see 语义视图概述.

     1. 找到 Cortex Analyst 并选择相应的 + Add 按钮。

     2. 对于 Name，请输入语义视图的名称。

     3. 选择 Semantic view。

     4. 选择代理使用的语义视图。

     5. 对于 Warehouse，请选择代理用来运行查询的仓库。

     6. 对于 Query timeout (seconds)，请指定代理在超时之前等待查询完成的最长时间（以秒为单位）。

     7. 对于 Description，请描述语义视图。

     8. 选择 Add。

   • To add a Cortex Search service to the agent: This section assumes that you've already created a Cortex Search service. 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. For a tutorial that uses a CKE, see 故障排除.

     1. 找到 Cortex Search Services 并选择相应的 + Add 按钮。

     2. 对于 Name，请输入 Cortex Search Service 的名称。

     3. 对于 Description，请描述 Cortex Search Service。

     4. 对于 Search service，请选择代理使用的 Cortex Search Service。

     5. 选择 Add。

   • To add a custom tool to the agent: By adding custom tools, you can extend the functionality of your agents. With custom tools, the agent can call stored procedures and functions that you have defined to perform actions or do computations. This section assumes that you've already created a custom tool. For information about procedures and functions, see 使用函数和过程扩展 Snowflake.

     1. 找到 Custom tools 并选择相应的 + Add 按钮。

     2. 对于 Name，请输入自定义工具的名称。

     3. 对于 Resource type，请选择自定义工具是函数还是过程。有关是否使用函数或过程的信息，请参阅 选择是编写存储过程还是用户定义函数。

     4. 对于 Custom tool identifier，请选择要添加为自定义工具的现有函数或过程。

     5. 函数或过程的相关参数会自动显示。您可以通过添加名称、类型、描述以及选择是否需要参数，来手动为自定义工具添加参数。您也可以修改自动填充的参数。

        备注

        Snowflake Cortex does not support stored procedures and custom tools with a parameter of type object.

     6. 对于 Warehouse，请选择代理用来运行自定义工具的仓库。必须手动选择仓库。

     7. 对于 Description，请描述自定义工具及其使用方法。

     8. 选择 Add。

     9. After creating the custom tool, make sure users are granted USAGE privileges to the function or procedure that you added as a custom tool. When using stored procedures, agents maintain whether the procedure runs with owner's or caller's rights. For information about owner's and caller's rights, see 了解调用方权限和所有者权限存储过程.

7. 选择 Save。

Specify orchestration¶

Cortex Agents orchestrate the task by breaking it into a sequence of sub-tasks and identifying the right tool for each sub-task. You specify the LLM that the Agent should use to conduct this orchestration. You can also influence the orchestration by providing instructions. For example, consider an agent built to respond to retail product questions. You can use the orchestration instruction "Use the search tool for all requests related to refunds" to ensure the Agent only provides refund policy details (using Cortex Search) and does not actually calculate the refund amounts (using Cortex Analyst). You can also specify instructions to align the response to a brand or a tone, such as "Always provide provide a concise response; maintain a friendly tone".

Set up access to the agent¶

GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> TO ROLE <role_name>;

Set up access policies from Snowsight UI or using SQL so that users can access the Agent. Specify the role to provide access to the Agent.

GRANT USAGE ON AGENT myagent TO ROLE test_rl;

Review the agent¶

After you have built the Agent, you can review the Agent to verify all parameters.

Test the agent¶

After you've created the agent, you can test it to see how it responds to user queries. You can also test the agent using 带有代理对象的代理运行请求.

To test the agent, follow these steps:

1. Sign in to Snowsight.

2. In the navigation menu, select AI & ML » Agents.

3. 从代理列表中选择代理。

4. On the agent details page, enter a query in the agent playground.

5. Verify that the agent responds to the query as expected. If the agent does not respond as expected, modify the agent's configuration by following the steps in Add tools.

Interact with the agent¶

After creating the agent object, you can integrate the agent directly into your application using the REST API. To maintain context during the interaction, use a thread. The agent object and thread combined simplify the client application code.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/threads" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "origin_application": <application_name>,
}'

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run" \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "Authorization: Bearer $PAT" \
 --data '{
     "thread_id": <thread id for context>,
     "parent_message_id": <parent message id>,
     "messages": [
      {
         "role": "user",
         "content": [
           {
            "type": "text",
             "text": "What are the projected transportation costs for the next three quarters? "
             }
         ]
       }
     ],
     "tool_choice": {
       "type": "required",
       "name": [
         "Analyst1",
         "Search1"
       ]
     }
 }'

Collect feedback about the agent¶

You can collect feedback from users about the responses given by the agent. This feedback can help you refine the agent as you iterate on your use case. Users can provide an objective rating (postive/negative), as well as more subjective detail with a message. Also, users can classify the feedback across one of many categories.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>:feedback:" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "request_id": "<request-id>",
    "positive": true
    "feedback_message": "This answer was great",
    "categories":[
        "category1", "category2", "category3"
    ],
    "thread_id": "<thread-id>"
}'

Interact without an agent object¶

In some cases, you may want to get started with Cortex Agents by using agent:run without an agent object. For example, this may be useful when you want to quickly try out a use case. For more information about the REST API, see 代理在没有代理对象的情况下运行.