Snowflake Cortex Agents

Some questions need more than one step. "Why did refunds rise last month, and what do our policies say about them?" asks for numbers from a table and facts from documents. A Cortex Agent plans the steps, picks the right tool for each one, and combines the answers into a single reply.

The Project Manager Comparison

A project manager receives a request, splits it into tasks, hands each task to the right specialist, and merges the results into one report. An agent plays that manager. Cortex Analyst acts as the specialist for table data, and Cortex Search acts as the specialist for documents. Custom tools handle special tasks such as sending an email or calling a stored procedure.

AGENT WORKFLOW
==============

 User question
       |
       v
 +-----------------------------+
 |        CORTEX AGENT         |
 |  1. Plan the steps          |
 |  2. Choose a tool           |
 |  3. Read the tool result    |
 |  4. Repeat or answer        |
 +--------+----------+---------+
          |          |         |
          v          v         v
    CORTEX      CORTEX      CUSTOM TOOL
    ANALYST     SEARCH      (procedure,
    (tables)    (documents)  function)
          \          |         /
           +---------+--------+
                     v
            One combined answer

The Plan and Reason Loop

An agent does not answer in one shot. It thinks, acts, and reviews.

EXAMPLE: "Why did refunds rise last month, and what does policy say?"

Step 1  PLAN      Need refund numbers and the refund policy text
Step 2  ACT       Ask Cortex Analyst: refunds by reason, last two months
Step 3  OBSERVE   Defective item refunds grew 40 percent
Step 4  ACT       Ask Cortex Search: policy on defective item refunds
Step 5  OBSERVE   Policy allows refunds within 30 days
Step 6  ANSWER    Summary with numbers, cause, and policy reference

Tools an Agent Can Use

TOOL TYPE           PURPOSE                          EXAMPLE
------------------  -------------------------------  ----------------------------
Cortex Analyst      Questions about structured data  Revenue, refunds, counts
Cortex Search       Questions about documents        Policies, manuals, contracts
Custom tools        Actions and special logic        Stored procedure that opens
                                                     a support ticket

Giving Clear Instructions

Agents follow written instructions. Good instructions describe the role, the audience, the rules for each tool, and the preferred answer style.

SAMPLE AGENT INSTRUCTIONS
=========================
Role:       You help the support operations team.
Data tool:  Use the sales analyst tool for any number, count, or trend.
Docs tool:  Use the policy search tool for rules, limits, and procedures.
Rules:      Never guess a number. Quote the policy title when citing a rule.
Style:      Short answers first, then a bullet list of supporting facts.
Limits:     If a question falls outside sales and policies, say so.

How Agents Are Built and Called

Snowflake provides an agent object and a REST API. A developer defines the model, instructions, and tools, and connects the agent to an application, a chat page, or Snowsight experiences. The exact creation syntax evolves, so follow the current Snowflake documentation and release notes when building.

Security Follows the User

• Tool calls run under the caller's role, so people see only data their role permits.
• Masking and row access policies apply to Analyst queries.
• Search services respect the access granted on each service.
• Custom tools use the privileges of their owners or callers, depending on how they are defined, so review each one before connecting it.

Design Tips

• Begin with two tools and add more after the first set works well.
• Give each tool a clear name and a short description of when to use it.
• Keep actions that change data behind confirmation steps.
• Log questions and answers, and review them weekly.
• Build a test set of real questions with known good answers.

Cost and Quality Control

Each agent run may call a language model several times and run queries on a warehouse. Cost grows with question volume and tool use. Track usage through the Cortex usage views, set limits on who may call the agent, and prefer concise instructions that avoid wandering loops. Quality grows through review: collect wrong answers, find the cause, and adjust instructions, semantic models, or document chunks.

A Practical Scenario

A hospital operations team wants staff to ask about bed occupancy and visiting rules in one place. A data engineer builds an agent with a table tool over the occupancy data and a search tool over policy documents. A nurse manager types a question about weekend capacity and visiting limits. The agent returns the occupancy figure with the matching visiting rule and its source title. The manager receives the answer in under a minute, and the compliance team reviews the logs each week.

Key Points

• A Cortex Agent plans steps, chooses tools, and merges results.
• Analyst handles tables, Search handles documents, and custom tools handle actions.
• Written instructions shape behavior, accuracy, and tone.
• Security follows the calling user's role and policies.
• Start small, test with real questions, and review logs regularly.
• Check current documentation, since agent features evolve quickly.