Configure and interact with Agents¶

Create an agent¶

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.

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

Method 1: Snowsight UIMethod 2: REST API

1. Sign in to Snowsight.

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

3. Select Create agent.

4. For Agent object name, specify a name for the agent that is displayed to users in the UI.

5. For Display name, specify a name for the agent that is displayed to admins in the agent list.

6. Select Create agent.

7. Prompt the agent with general knowledge requests.

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 API

To modify the configuration for an existing agent, complete the following steps:

1. Select Edit.

2. For Description, describe the agent and how users can interact with it.

3. To add sample questions that users can ask the agent, enter a sample question and select Add a question.

4. 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 Overview of semantic views.

     1. Find Cortex Analyst and select the respective + Add button.

     2. For Name, enter a name for the semantic view.

     3. Select Semantic view.

     4. Select the semantic view that the agent uses.

     5. For Warehouse, select the warehouse that the agent uses to run queries.

     6. For Query timeout (seconds), specify the maximum time in seconds that the agent waits for a query to complete before timing out.

     7. For Description, describe the semantic view.

     8. Select 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 Troubleshooting.

     1. Find Cortex Search Services and select the respective + Add button.

     2. For Name, enter a name for the Cortex Search service.

     3. For Description, describe the Cortex Search service.

     4. For Search service, select the Cortex Search service that the agent uses.

     5. Select 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 Extending Snowflake with Functions and Procedures.

     1. Find Custom tools and select the respective + Add button.

     2. For Name, enter a name for the custom tool.

     3. For Resource type, select whether the custom tool is a function or a procedure. For information about whether to use a function or procedure, see Choosing whether to write a stored procedure or a user-defined function.

     4. For Custom tool identifier, select the existing function or procedure that you want to add as a custom tool.

     5. The related parameters for the function or procedure automatically appear. You can manually add parameters for the custom tool by adding a name, type, description, and selecting whether the parameter is required. You can also modify parameters that automatically populate.

     6. For Warehouse, select the warehouse that the agent uses to run the custom tool. You must manually select a warehouse.

     7. For Description, describe the custom tool and how to use it.

     8. Select 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 Understanding caller’s rights and owner’s rights stored procedures.

5. Select 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¶

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 PRIVILEGE ON AGENT my_agent 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 Agent run request with agent object.

To test the agent, follow these steps:

1. Sign in to Snowsight.

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

3. Select the agent from the list of agents.

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 Agent run without an agent object.