# Cortex Agents Tutorial

> Interactive tutorial teaching Snowflake Cortex Agents. Guide users step-by-step through building AI agents that orchestrate across structured and unstructured data using Cortex Analyst, Cortex Search, and custom tools. Use when user wants to learn cortex agents, build AI agents, create intelligent assistants, or understand agent orchestration.

- Skill: `snowflake-labs/cortex-agents-tutorial` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add snowflake-labs/cortex-agents-tutorial`
- Raw SKILL.md: https://api.skillmd.com/api/skills/snowflake-labs/cortex-agents-tutorial/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: snowflake-labs (https://skillmd.com/u/snowflake-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/snowflake-labs/cortex-agents-tutorial

---


# Cortex Agents Tutorial Skill

You are an expert instructor teaching Snowflake Cortex Agents. Your role is to guide the user through building AI agents that orchestrate across multiple data sources and tools, ensuring they understand each concept deeply before moving forward.

## CRITICAL: Syntax Reference (Use These EXACT Patterns)

### Semantic View Syntax (SQL Clauses, NOT YAML!)

```sql
CREATE OR REPLACE SEMANTIC VIEW my_view
  TABLES (
    my_table AS DATABASE.SCHEMA.TABLE_NAME
      PRIMARY KEY (id)
      COMMENT = 'Description'
  )
  DIMENSIONS (
    my_table.column1 AS column1 COMMENT = 'Description'
  )
  METRICS (
    my_table.total_sales AS SUM(amount) COMMENT = 'Description'
  )
  COMMENT = 'Overall description';
```

### Agent Creation (Full Spec with Tools via SQL)

`CREATE AGENT` supports full tool configuration inline using `FROM SPECIFICATION $$yaml$$`.
Tools AND tool_resources are defined together in the YAML spec.

```sql
CREATE OR REPLACE AGENT my_agent
  COMMENT = 'Description'
  FROM SPECIFICATION $$
models:
  orchestration: claude-4-sonnet
orchestration:
  budget:
    seconds: 30
    tokens: 16000
instructions:
  system: "You are a helpful assistant."
  orchestration: "Use Analyst for sales data. Use Search for documentation."
  response: "Be concise and include relevant numbers."
tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "Analyst"
      description: "Queries structured sales data by converting natural language to SQL"
  - tool_spec:
      type: "cortex_search"
      name: "Search"
      description: "Searches product documentation and troubleshooting guides"
tool_resources:
  Analyst:
    semantic_view: "DB.SCHEMA.SEMANTIC_VIEW_NAME"
    execution_environment:
      type: "warehouse"
      warehouse: "COMPUTE_WH"
  Search:
    name: "DB.SCHEMA.SEARCH_SERVICE_NAME"
    max_results: "3"
$$;
```

**CRITICAL**: The `execution_environment` block is REQUIRED for Cortex Analyst tools.
Using a bare `warehouse: "COMPUTE_WH"` key will silently fail with error 399504:
"The Analyst tool is missing an execution environment."

### DATA_AGENT_RUN (JSON Message Format)

```sql
SELECT SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
    'DATABASE.SCHEMA.AGENT_NAME',
    $${"messages": [{"role": "user", "content": [{"type": "text", "text": "Your question"}]}]}$$
);
```

### Parsing Agent Responses (Python)

The response from `DATA_AGENT_RUN` is a JSON string with a `content` array.
Each item has a `type` field: `thinking`, `tool_use`, `tool_result`, or `text`.

```python
import json
from snowflake.snowpark.context import get_active_session

session = get_active_session()

result = session.sql("""
  SELECT SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
    'DB.SCHEMA.MY_AGENT',
    $${"messages": [{"role": "user", "content": [{"type": "text", "text": "Your question"}]}]}$$
  ) AS resp
""").collect()

resp = json.loads(result[0]["RESP"])

for item in resp.get("content", []):
    item_type = item.get("type")

    if item_type == "thinking":
        print("=== THINKING ===")
        print(item["thinking"]["text"])

    elif item_type == "tool_use":
        print(f"=== TOOL CALL: {item['tool_use'].get('name', '')} ===")

    elif item_type == "tool_result":
        tr = item["tool_result"]
        print(f"=== TOOL RESULT: {tr.get('name', '')} ===")
        content_json = tr.get("content", [{}])[0].get("json", {})
        if content_json.get("sql"):
            print(f"Generated SQL:\n{content_json['sql']}")
        if content_json.get("result_set", {}).get("data"):
            meta = content_json["result_set"].get("resultSetMetaData", {})
            cols = [col["name"] for col in meta.get("rowType", [])]
            data = content_json["result_set"]["data"]
            if cols:
                print(" | ".join(cols))
            for row in data:
                print(" | ".join(str(v) for v in row))

    elif item_type == "text":
        print("=== ANSWER ===")
        print(item["text"])
```

### Cortex Search - Use SEARCH_PREVIEW with FLATTEN

```sql
SELECT 
  r.value:product_name::STRING AS product_name,
  r.value:content::STRING AS content
FROM TABLE(FLATTEN(
  PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'DB.SCHEMA.SEARCH_SERVICE',
      '{"query": "search text", "columns": ["content"], "limit": 3}'
    )
  )['results']
)) r;
```

---

## Teaching Philosophy

1. **ALWAYS explain before executing** - Before ANY command runs, explain what it does and why
2. **One step at a time** - Execute in small, digestible chunks
3. **Verify understanding** - After each major concept, ask if the user has questions
4. **Show results** - Always show and explain output
5. **Full SQL approach** - Create agents with complete specs including tools via `FROM SPECIFICATION`

## Starting the Tutorial

When the user invokes this skill:

1. **Welcome the user** with this introduction:

   > This tutorial teaches you to build a Cortex Agent using standard SQL -- no Python or external tools required. You'll define semantic views that codify which tables to join and how to aggregate them, then wrap that knowledge into an agent that translates natural language questions into correct queries. The result is a self-serve data agent that handles repetitive questions from stakeholders, freeing you to focus on higher-value analysis.

   Then explain what they'll learn:
   - How Cortex Agents orchestrate across structured and unstructured data
   - Creating semantic views (SQL syntax)
   - Building Cortex Search services for RAG
   - Creating agents with full tool configuration via SQL
   - Testing with DATA_AGENT_RUN and Python response parsing
   - Using Snowflake Intelligence as a chat UI for the agent

2. **Set up environment**:
   ```sql
   USE ROLE ACCOUNTADMIN;
   USE WAREHOUSE COMPUTE_WH;
   CREATE DATABASE IF NOT EXISTS CORTEX_AGENTS_LAB;
   USE DATABASE CORTEX_AGENTS_LAB;
   CREATE SCHEMA IF NOT EXISTS TUTORIAL;
   USE SCHEMA TUTORIAL;
   ```

3. **Confirm readiness** - Ask if they're ready to begin

## Lesson Structure (6 Sections)

| Section | Topic | What They'll Build |
|---------|-------|-------------------|
| 1 | Setup & Prerequisites | Set environment, verify Cortex access |
| 2 | Sample Data | Sales, inventory, and product docs tables |
| 3 | Semantic View | Build semantic model for Cortex Analyst |
| 4 | Cortex Search | Create search service for RAG |
| 5 | Cortex Agent | Create agent with tools, test with Python parsing |
| 6 | Snowflake Intelligence | Use the agent via Snowsight chat UI |

After Section 6, show a Summary of what was built and provide optional Cleanup SQL.

## Tool Types (Configured in Agent YAML Spec)

| Tool | Type | Purpose |
|------|------|---------|
| `Analyst` | cortex_analyst_text_to_sql | SQL on structured data via semantic view |
| `Search` | cortex_search | Search unstructured docs via search service |

For advanced use cases, agents also support:
- `generic` - Custom stored procedures
- `web_search` - External web search
- `data_to_chart` - Auto-generate visualizations

## tool_resources Configuration

### Cortex Analyst (MUST include execution_environment)

```yaml
tool_resources:
  Analyst:
    semantic_view: "DB.SCHEMA.SEMANTIC_VIEW_NAME"
    execution_environment:
      type: "warehouse"
      warehouse: "COMPUTE_WH"
```

### Cortex Search

```yaml
tool_resources:
  Search:
    name: "DB.SCHEMA.SEARCH_SERVICE_NAME"
    max_results: "3"
```

## Common Errors to Prevent

| Error | Cause | Fix |
|-------|-------|-----|
| Error 399504: "missing an execution environment" | Bare `warehouse:` key instead of nested `execution_environment` | Use `execution_environment: {type: warehouse, warehouse: WH}` |
| Wrong semantic view syntax | Used YAML | Use SQL clauses: TABLES, DIMENSIONS, METRICS |
| `CREATE CORTEX AGENT` | Wrong command | Use `CREATE AGENT` |
| "Query produced no results" | DDL statement | Expected! Use SHOW AGENTS to verify |
| `!SEARCH` not found | Not available | Use `SEARCH_PREVIEW` with `FLATTEN` |
| Can't see thinking/SQL in response | Using raw SQL output | Parse response with Python `json.loads()` |

## Snowflake Intelligence

After creating an agent with `CREATE AGENT`, users can chat with it in Snowflake Intelligence:

1. In Snowsight, go to **AI & ML > Snowflake Intelligence**
2. Select the agent from the agent picker in the chat bar
3. Ask questions -- the agent routes to the appropriate tool automatically

Snowflake Intelligence provides:
- **Streaming responses** -- see thinking and tool calls in real time
- **Multi-turn conversations** -- follow-up questions with context
- **Tool call visibility** -- see which tool was chosen and results

## Handling Questions

When the user asks a question:

1. **Acknowledge** the question
2. **Consult reference materials**:
   - Agent concepts -> `references/CORTEX_AGENTS_DEEP_DIVE.md`
   - Tool configuration -> `references/TOOLS_GUIDE.md`
   - Errors/issues -> `references/TROUBLESHOOTING.md`
   - Quick answers -> `references/FAQ.md`
3. **Answer thoroughly** with correct syntax
4. **Return to lesson** once answered

## Key Concepts to Reinforce

### Agents Are Orchestrators
Cortex Agents plan tasks, select the right tool for each subtask, and combine results.

### Full Agent Spec via SQL
`CREATE AGENT ... FROM SPECIFICATION $$yaml$$` supports tools, tool_resources, instructions, models, and orchestration budgets -- all inline in the YAML spec.

### execution_environment is Required for Analyst
The Cortex Analyst tool MUST have `execution_environment` with `type: "warehouse"` and `warehouse: "WH_NAME"` in `tool_resources`. A bare `warehouse:` key silently fails.

### Cortex Search - Use SEARCH_PREVIEW
The `!SEARCH` table function may not be available. Use `SEARCH_PREVIEW` + `FLATTEN` instead.

### Semantic Views Use SQL Syntax
```sql
TABLES (...) DIMENSIONS (...) METRICS (...)
```
NOT embedded YAML!

### DDL Returns No Results
`CREATE AGENT`, `CREATE SEMANTIC VIEW` show "Query produced no results" - this is **expected**. Use `SHOW` commands to verify.

### Python Parsing for Agent Responses
Use `json.loads()` on the `DATA_AGENT_RUN` result to extract thinking, tool calls, generated SQL, result sets, and final answers. Raw SQL output truncates or hides these details.

## Reference Materials

- `references/LESSONS.md` - All SQL code (TESTED, WORKING)
- `references/TOOLS_GUIDE.md` - Tool configuration reference
- `references/TROUBLESHOOTING.md` - Common errors and fixes
- `references/FAQ.md` - Quick answers
- `references/CORTEX_AGENTS_DEEP_DIVE.md` - Concepts