Snowflake-Labs/awesome-custom-cortex-agents-rest-api-react-app

Snowflake-Labs/awesome-custom-cortex-agents-rest-api-react-app

Language: TypeScript

License: Apache-2.0

Stars: 20

Forks: 11

Open issues: 0

Created: 2025-11-06T03:08:17Z

Pushed: 2025-11-17T16:27:23Z

Default branch: main

Fork: no

Archived: no

README:

Overview

This guide provides the instructions to build custom application for the data agents you have already built in your Snowflake account. The LLM orchestration, planning, thinking, deep reasoning, and execution of SQL queries, etc. (similar to [ai.snowflake.com](ai.snowflake.com)) is powered by Snowflake Cortex Agents via the REST API and the interface is built with TypeScript and Material-UI.

Use this as a starter project or template and extend or customize it. Also note that agents can make mistakes, so double-check responses.

Table of Contents

• [Prerequisites](#prerequisites)
• [Setup Steps](#setup-steps)
• [1. Clone Repo](#1-clone-repo)
• [2. Install Dependencies](#2-install-dependencies)
• [3. Configure Environment Variables](#3-configure-environment-variables)
• [Launch Application](#launch-application)
• [Demo](#demo)
• [Usage](#usage)
• [Implemented Features](#implemented-features)
• [Future Enhancements](#future-enhancements)
• [Common Issues](#common-issues)
• [Optimized Build](#optimized-build)
• [Deploy To Snowpark Container Services](#deploy-to-snowpark-container-services)
• [Questions](#questions)

---

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0
• Snowflake Account
• With ACCOUNTADMIN role
• Personal Access Token (PAT) created for authentication
• Access to Snowflake Intelligence and at least one Agent

NOTE: If you have not created an agent or do not have access to one, follow this step-by-step guide. You can then use the same account and interact with that agent in this application.

Setup Steps

1. Clone Repo

Clone this repository to get the required files.

• Folders
• src/
• server/

• Files
• craco.config.js
• package.json
• tsconfig.json
• env.backend.example
• env.frontend.example

> #### Expand to see the folder structure and files details.

├── src/ # Frontend React application
│ ├── components/ # UI Components
│ │ ├── Main.tsx # Main chat interface
│ │ ├── ChartVisualization.tsx # Chart rendering with Recharts
│ │ ├── ThemeToggle.tsx # Dark/Light mode toggle
│ │ └── chat/ # Chat-specific components
│ │ ├── AnnotationsSection.tsx # Annotations display section
│ │ ├── ChatHeader.tsx # Header with agent selector
│ │ ├── ChatInput.tsx # Message input with voice support
│ │ ├── ChatMessage.tsx # Message display with markdown
│ │ ├── ChartsSection.tsx # Chart visualization section
│ │ ├── EmptyState.tsx # Empty chat state
│ │ ├── MarkdownFormatter.tsx # Markdown rendering
│ │ ├── SqlQueriesSection.tsx # SQL query display
│ │ ├── StarterQuestions.tsx # Suggested questions
│ │ ├── ThinkingSteps.tsx # Agent thinking visualization
│ │ └── index.ts # Component exports
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── useAccordionState.ts # Accordion state management
│ │ ├── useAgentConfig.ts # Agent configuration & loading
│ │ ├── useChatMessages.ts # Message handling & streaming
│ │ └── useSpeechRecognition.ts # Voice input (Web Speech API)
│ │
│ ├── services/ # API services
│ │ └── snowflakeAgentsApi.ts # Backend proxy API calls
│ │
│ ├── types/ # TypeScript type definitions
│ │ ├── chat.ts # Chat message types
│ │ └── chart.ts # Chart data types
│ │
│ ├── utils/ # Utility functions
│ │ └── chatUtils.ts # Chat helper functions
│ │
│ ├── contexts/ # React contexts
│ │ └── ThemeContext.tsx # Theme state management
│ │
│ ├── constants/ # App constants
│ │ └── textConstants.ts # UI text & messages
│ │
│ ├── theme/ # MUI theme configuration
│ │ └── theme.ts # Dark/Light theme definitions
│ │
│ ├── config/ # App configuration
│ │ └── env.ts # Environment variable validation
│ │
│ └── index.tsx # App entry point with ErrorBoundary
│
├── server/ # Backend proxy server (Node.js/Express)
│ ├── server.js # Express server (PAT secured here)
│ └── constants.js # Server constants & error messages
│
├── public/ # Static assets
│ ├── images/ # Logos and icons
│ │ ├── icons/ # App icons
│ │ │ └── dash_snowboard_512.png # Alternative app icon
│ │ ├── logos/ # Brand logos
│ ├── index.html # HTML template
│ ├── manifest.json # PWA manifest
│ ├── robots.txt # SEO configuration
│ └── _headers # Security headers for deployment
│
├── package.json # Dependencies & npm scripts
├── tsconfig.json # TypeScript configuration
│
├── env.backend.example # Backend environment template
├── env.frontend.example # Frontend environment template
│
├── README.md # Main documentation (you are here!)

2. Install Dependencies

Browse to the cloned repo folder on your local machine. Then, run the following command in a terminal window.

npm install

This creates the node_modules/ folder with all required packages.

3. Configure Environment Variables

• Copy env.backend.example → .env

> NOTE: Update .env and add your Snowflake account details

• Copy env.frontend.example → .env.local

Launch Application

Browse to the cloned repo folder on your local machine. Then, run the following command in a terminal window to launch both the frontend application and the backend server.

npm run start:all

NOTE: If you get SecurityError: Cannot initialize local storage without a '--localstorage-file' path try downgrading to version 20.

If all goes well, the application will automatically launch on http://localhost:3000 in a browser window.

Demo

https://github.com/user-attachments/assets/03cdaf49-51aa-4f8b-8bf8-26310249f169

Usage

• Click on one of the starter questions (if any)
• Type in a question/prompt in the text input field in the footer
• To enable voice dictation, click the microphone icon. You will need to grant the necessary audio permissions to your browser. Once permissions are active, you can begin speaking your prompt.

Implemented Features

• Agent selector
• Example questions (if any) for the selected agent
• Streaming responses
• Charts and tables
• Citations
• Executed SQL(s) with "Answer accuracy verified by agent owner" indicated when…