Casai Examples

A collection of practical examples demonstrating AI agent patterns using Casai - a framework for building structured AI workflows with the Vercel AI SDK.

Table of Contents

• Installation
• Configuration
• Running Examples
• Customizing Examples
• Examples Overview

Installation

Prerequisites

• Node.js (v18 or higher recommended)
• npm or pnpm
• API keys for any model provider supported by Vercel AI SDK

Setup Steps

1. Clone or download this repository

git clone <repository-url>
cd casai-examples

2. Install dependencies

npm install

3. Configure API keys

Create a .env file in the project root with your API keys:

# Add keys for the providers you want to use
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
# ... any other Vercel AI SDK supported provider

Common providers:

• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/settings/keys
• Google AI: https://aistudio.google.com/app/apikey
• See full list: https://sdk.vercel.ai/providers/ai-sdk-providers

Configuration

Global Configuration (src/setup.ts)

The setup.ts file exports two pre-configured models used across examples:

// Basic model for simple tasks (faster, cheaper)
export const basicModel = withProgressIndicator(
  openai('gpt-4.1-nano'),
  'GPT-4o-nano',
  showProgressIndicators
);

// Advanced model for complex tasks (more capable)
export const advancedModel = withProgressIndicator(
  anthropic('claude-3-7-sonnet-latest'),
  'Claude-3.7-Sonnet',
  showProgressIndicators
);

Configuration options:

• Model Selection: Change the model provider/version in the first parameter

  • OpenAI: openai('gpt-4.1-nano'), openai('gpt-4o'), etc.
  • Anthropic: anthropic('claude-3-7-sonnet-latest'), anthropic('claude-3-5-sonnet-20241022'), etc.

• Progress Indicators: Set showProgressIndicators to true or false

  • true: Shows detailed logging of LLM calls with token counts and timing
  • false: Silent mode (no progress output)

Example progress output:

[GPT-4o-nano #1] 🚩 Start generating | prompt: "Write a short, engaging..." | active: 1
[GPT-4o-nano #1] ✅ Complete generating: 239 tokens in 3.62s | active: 0

Running Examples

Use the npm run example command followed by the example number:

# Run example 1 (Prompt Chaining)
npm run example 1

# Run example 2 (Routing)
npm run example 2

# Run example 3 (Parallelization)
npm run example 3

# Run example 4 (Reflection)
npm run example 4

The script automatically finds and executes the matching example directory (e.g., 1-prompt-chaining, 2-routing, 3-parallelization, 4-reflection).

Cleaning Data

Some examples may generate local data (e.g., vector indices, downloaded files). To clean up this generated data:

npm run clean

This will remove generated artifacts like the vectra_index directory.

## Examples Overview

### Example 1: Prompt Chaining ([src/1-prompt-chaining/index.ts](src/1-prompt-chaining/index.ts))
Generates a blog article by sequentially researching facts, creating an outline, writing the content, and generating a title.
Demonstrates breaking down a complex task into a sequence of simpler steps.
- **Linear Workflow**: Executes steps in order: Research → Outline → Write → Title.
- **State Management**: Passes outputs from one step as inputs to the next.
- **Separation of Concerns**: Each step focuses on a specific sub-task for better quality.

### Example 2: Routing ([src/2-routing/index.ts](src/2-routing/index.ts))
Acts as a customer support agent that classifies inquiries (technical, billing, etc.) and routes them to specialized handlers with appropriate tones.
Demonstrates routing different types of inputs to specialized handlers.
- **Classification**: Uses an LLM to categorize inquiries (Technical, Billing, General, Urgent).
- **Specialized Handlers**: Routes to specific prompts/configs optimized for each category.
- **Conditional Logic**: Uses `switch` or `if/else` logic to direct control flow.
- **Strategy Pattern**: Dynamically selects and applies the appropriate handling strategy.

### Example 3: Parallelization ([src/3-parallelization/index.ts](src/3-parallelization/index.ts))
Performs market analysis by finding and analyzing stocks in multiple markets simultaneously, then ranking them based on calculated scores.
Demonstrates automatic parallel execution through simple for loops.
- **Automatic Concurrency**: Cascada automatically parallelizes independent iterations in `for` loops.
- **Hybrid Logic**: Combines LLM generation (finding/analyzing stocks) with JS logic (ranking/filtering).
- **Structured Data**: Collects and processes structured data from multiple parallel streams.
### Example 4: Reflection ([src/4-reflection/index.ts](src/4-reflection/index.ts))
Iteratively improves a blog post by generating a draft, critiquing it against a quality threshold, and revising it based on specific feedback.
Demonstrates an AI agent that improves its own output through self-critique.
- **Self-Correction Loop**: Generates a draft, critiques it, and revises based on feedback.
- **Quality Control**: Continues revising until a quality threshold is met or max revisions reached.
- **Structured Feedback**: Uses specific scoring and suggestions to guide improvements.

### Example 5: Tool Use ([src/5-tool/index.ts](src/5-tool/index.ts))
Answers weather queries by orchestrating multiple tools: geocoding locations, interpreting relative dates (e.g., "next Friday"), and fetching forecast data.
Demonstrates how to create custom tools that LLMs can use to solve problems.
- **LLM-Powered Tools**: Creates a tool that uses an LLM to interpret natural language (time references).
- **API Integration**: Connects to external weather and geocoding APIs.
- **Tool Composition**: Shows an agent combining multiple tools to answer complex queries.
- **Multi-step Reasoning**: Uses context from previous steps (location) to inform subsequent steps (time interpretation, weather fetch).

### Example 6: Planning ([src/6-planning/index.ts](src/6-planning/index.ts))
Demonstrates an AI agent that builds a complete data dashboard for any SQLite databse from a natural language request. The agent downloads the database file, analyzes its structure to create a schema summary, plans the dashboard layout, and then concurrently generates and executes SQL queries to fetch the necessary data before rendering the final HTML.
- **Planning Pattern**: Break complex tasks into structured steps.
- **Dynamic SQL Generation**: Creates SQL queries based on the dashboard layout.
- **Structured Output**: Using Zod schemas to enforce plan format.
- **Concurrency**: SQL generation and data fetching for elements run in parallel.
- **Multi-step Chaining**: Planner, data fetcher, and code generator.
- **Schema Analysis**: Analyzes database structure to understand available data.
- **Code Generation**: Dynamically generates SQL and HTML based on requirements.

<!---

### Example 7: Multi-Agent
TODO
### Example 8: Memory Management
TODO
### Example 9: Learning and Adaptation
TODO
### Example 10: Model Context Protocol (MCP)
TODO
### Example 11: Goal Setting and Monitoring
TODO
### Example 12: Exception Handling and Recovery
TODO
### Example 13: Human-in-the-Loop
TODO
--->

### Example 14: RAG ([src/14-rag/index.ts](src/14-rag/index.ts))
Answers questions about a document by retrieving vector matches, verifying their relevance with an LLM filter, and synthesizing an answer from verified chunks.
Demonstrates a Retrieval-Augmented Generation system with agentic filtering.
- **RAG Pattern**: Combines document retrieval with generation for accurate, grounded answers.
- **Semantic Chunking**: Splits text by meaning rather than fixed size.
- **Vector Search**: Retrieves broad candidates using cosine similarity.
- **Agentic Filtering**: A second-pass LLM verifies relevance of each chunk to improve the context for the final answer.

<!---
### Example 15: Inter-Agent Communication (A2A)
TODO
### Example 16: Resource-Aware Optimization
TODO

### Example 17: Reasoning Techniques
TODO

### Example 18: Guardrails/Safety Patterns
TODO

### Example 19: Evaluation and Monitoring
TODO

### Example 20: Prioritization
TODO

### Example 21: Exploration and Discovery
TODO
--->

## Troubleshooting

**Issue: "No API key found"**
- Ensure `.env` file exists in the project root
- Verify API keys are correctly set
- Restart your terminal/IDE after creating `.env`

**Issue: Rate limiting or API errors**
- Check your API key has sufficient credits

## Learn More

- [Casai Documentation](https://github.com/geleto/casai)
- [Vercel AI SDK](https://sdk.vercel.ai/)
- [Cascada Engine](https://github.com/geleto/cascada)
- [Cascada Script Language](https://github.com/geleto/cascada/blob/master/docs/cascada/script.mde)

## License

Apache-2.0