Configure and interact with Agents¶

You can build an agent in Snowsight or using the REST API, and then integrate the agent into your application to perform tasks or respond to queries. You must first create an agent object that contains information such as the metadata, tools, and orchestration instructions that the agent can use to perform a task or answer questions. You can then reference the agent object in your application to integrate the agent’s functionality. You can configure a thread to maintain the context in memory, so that the client does not have to send the context at every turn of the conversation.

Note

Snowflake REST APIs support authentication via programmatic access tokens (PATs), key pair authentication using JSON Web Tokens (JWTs), and OAuth. For details, see Authenticating Snowflake REST APIs with Snowflake.

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:

Sign in to Snowsight.

From the left-hand navigation, select AI & ML.

Select Agents.

Select Create agent.

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

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

Select Create agent.

Prompt the agent with general knowledge requests.
Create an agent object by specifying the database and schema where the agent will be created, as well as the parameters needed for the agent. You can also specify tool fields when creating the agent object.
curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "name": "TransportationAgent",
    "comment": "This agent handles queries related to transportation methods and costs.",
    "models" {
        "orchestration": "llama3.3-70B"
    }
}'
Copy

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.

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

Select Edit.

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

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

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.

Find Cortex Analyst and select the respective + Add button.

For Name, enter a name for the semantic view.

Select Semantic view.

Select the semantic view that the agent uses.

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

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

For Description, describe the semantic view.

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.

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

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

For Description, describe the Cortex Search service.

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

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.

Find Custom tools and select the respective + Add button.

For Name, enter a name for the custom tool.

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.

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

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.

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

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

Select Add.

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.

Select Save.
To add tools to an agent using the REST API, add the following payloads as part of a request to Update Cortex Agent. You can also specify these fields when creating the agent object.
Add Cortex Analyst tool and tool resources: The following example shows how to add a Cortex Analyst tool and tool resources to an existing agent object.
Add a Cortex Analyst tool
curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "tools": [
  {
   "tool_spec": {
    "description": "Analyst to analyze price",
    "type": "cortex_analyst_text_to_sql",
    "name": "Analyst1"
   }
  }
 ]
}'
Copy
Add a Cortex Analyst tool resource
curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "tool_resources": {
  "Analyst1": {
   "semantic_model_file": "stage1",
   "semantic_view": "The name of the Snowflake native semantic model object",
   "execution_environment": {"type":"warehouse", "warehouse":"my_wh"}
  }
 }
}'
Copy
Add Cortex Search tool and tool resources: The following example shows how to add a Cortex Search tool and tool resources to an existing agent object.
Add a Cortex Search tool
curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "tool_spec": {
  "type": "cortex_search",
  "name": "Search1"
 }
}'
Copy
Add a Cortex Search tool resource
curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "tool_resources": {
  "Search1": {
   "search_service": "db.schema.service_name",
   "filter": {"@eq": {"region": "North America"} },
   "max_results": 5
  }
 }
}'
Copy
Add custom tool and tool resources: The following example shows how to add a custom tool and tool resources to an existing agent object.
Add a custom tool
curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "tools": [
  {
   "tool_spec": {
     "description": "Custom tool",
     "type": "generic",
     "name": "custom1"
   }
  }
 ]
}'
Copy
Add a custom tool resource
curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "tool_resources": {
  "Custom1": {
   "user-defined-function-argument": "argument1"
  }
 }
}'
Copy

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".

Select Orchestration.
For the Orchestration model, select the model that the agent uses to handle orchestration.
For Planning instructions, provide instructions that influence tool selection by the agent based on user-provided input. These can include specific instructions about when to use each tool, or even to always use a tool at the beginning or end of a response.
For Response instruction, provide instructions that the model uses for response generation. For example, specify if you want the agent to prioritize chart creation, or to keep a certain tone with users.
Select Save.

To update an agent using the REST API, add the following payloads as part of a request to Update Cortex Agent. You can also specify these fields when creating the agent object. The following procedure shows how to update the agent with planning and response instructions, and specify the LLM model used for orchestration.

Update the LLM model

curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "models": {
  "orchestration": "llama3.3-70B"
}'

Copy

Specify the planning and response instructions

curl -X PUT "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
 "instructions": {
  "response": "Always provide a concise response and maintain a friendly tone.",
  "orchestration": "<orchestration instructions>",
  "system": "You are a helpful data agent."
 }
}'

Copy

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.

Select Access.
To give a role access to the agent, select Add role, then select the role from the dropdown menu.
Select Save.

GRANT USAGE PRIVILEGE ON AGENT my_agent TO ROLE test_rl;

Copy

Review the agent¶

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

Select Agents.
From the list of agents, select the agent that you want to view the details for. This opens a new page that gives an overview of the agent details.
To review all agent details, select Next.

You can list and describe agents using the REST APIs.

List all agents.

curl -X GET "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/{database}/schemas/{schema}/agents:" \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "Authorization: Bearer $PAT" \

Copy

Describe the desired agent.

curl -X GET "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/{database}/schemas/{schema}/agents/{name}:" \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "Authorization: Bearer $PAT" \

Copy

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 Run agent object.

To test the agent, follow these steps:

Sign in to Snowsight.
From the left-hand navigation, select AI & ML.
Select Agents.
Select the agent from the list of agents.
On the agent details page, enter a query in the agent playground.
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.

Create a thread¶

Create a thread to maintain the context during a conversation. When the thread is created successfully, the system returns a Thread ID.

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>,
}'

Copy

Send a request to the agent¶

To interact with the Agent, you must pass the agent object, thread ID, and a unique parent_message_id as part of your REST API request. The initial parent_message_id should be 0.

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"
       ]
     }
 }'

Copy

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>"
}'

Copy