Skip to content

tesseract-creator/runloop-workspace

BranchesTags

Repository files navigation

🤖 Runloop Workspace

A comprehensive collection of AI agents, examples, and documentation for the Runloop Platform

License: MIT TypeScript LangGraph Runloop

📋 Table of Contents

🎯 Overview

Runloop Workspace is a unified repository containing production-ready AI agents, SDK examples, code samples, and comprehensive documentation for building agentic applications with the Runloop platform.

This workspace demonstrates:

  • Enterprise-grade AI agents with LangGraph.js and Claude Sonnet 4.5
  • Runloop Devboxes for secure, isolated execution environments
  • Multi-service integration (Supabase, Resend, Brave Search, Tavily, Exa)
  • Production patterns for error handling, logging, and observability
  • TypeScript best practices for agent development

📁 Repository Structure

runloop-workspace/
├── runloop-interview/           # Production AI Agents (3 agents)
│   └── agent-working-directory/
│       └── agents/
│           ├── 1_lead-gen-sales-agent/          # Lead generation & enrichment
│           ├── 2_marketing-content-agent/        # Marketing content generation
│           └── 3_customer-support-triage-agent/  # Support ticket triage
│
├── runloop-practice/            # SDK Examples & Bootcamp
│   ├── examples/                # Basic SDK usage patterns
│   ├── bootcamp/                # Learning exercises
│   └── demos/                   # Demo applications
│
├── runloop-agents/              # Additional Agent Implementations
│   ├── langgraph-agents/        # LangGraph-based agents
│   ├── basic-agents/            # Simple agent examples
│   └── advanced-agents/         # Complex agent patterns
│
├── runloop-code-examples-main/  # Official Code Examples
│   ├── python/                  # Python SDK examples
│   ├── typescript/              # TypeScript SDK examples
│   └── notebooks/               # Jupyter notebooks
│
├── runloop-documentation/       # Technical Documentation
│   ├── api-reference/           # API documentation
│   ├── guides/                  # How-to guides
│   └── architecture/            # System architecture docs
│
└── runloop-system-prompts/      # Agent System Prompts
    ├── templates/               # Reusable prompt templates
    └── best-practices/          # Prompt engineering guides

🚀 Production Agents

1. Lead Generation Sales Agent

Purpose: Automate B2B lead research and enrichment using AI-powered web search

Key Features:

  • Multi-source company research (Brave, Tavily, Exa)
  • Intelligent lead scoring and qualification
  • LinkedIn profile enrichment
  • Automated email notifications
  • Supabase database persistence
  • Duplicate lead detection with URL normalization

Stack: LangGraph.js + Claude Sonnet 4.5 + Brave/Tavily/Exa APIs

Location: runloop-interview/agent-working-directory/agents/1_lead-gen-sales-agent/

Run Command:

cd runloop-interview/agent-working-directory/agents/1_lead-gen-sales-agent
npm run start:langgraph

2. Marketing Content Agent

Purpose: Generate high-quality technical marketing content for developer audiences

Key Features:

  • Video outline generation (7-9 scenes, code examples)
  • Twitter thread creation (5-7 tweets, optimized for engagement)
  • LinkedIn post writing (800-1200 words, technical depth)
  • Developer portfolio demo content
  • AI-powered code snippet generation
  • Content versioning and tracking

Stack: LangGraph.js + Claude Sonnet 4.5 + Runloop Objects API

Location: runloop-interview/agent-working-directory/agents/2_marketing-content-agent/

Run Command:

cd runloop-interview/agent-working-directory/agents/2_marketing-content-agent
npm run start:langgraph

3. Customer Support Triage Agent

Purpose: Intelligent support ticket classification and routing

Key Features:

  • Automated ticket categorization (provisioning, execution, snapshot, environment)
  • Priority scoring (P0-P3)
  • Root cause analysis
  • Diagnostic step generation
  • Engineering team routing
  • SLA tracking and notifications

Stack: LangGraph.js + Claude Sonnet 4.5 + Runloop Devboxes API

Location: runloop-interview/agent-working-directory/agents/3_customer-support-triage-agent/

Run Command:

cd runloop-interview/agent-working-directory/agents/3_customer-support-triage-agent
npm run start:langgraph

🏁 Quick Start

Prerequisites

Installation

  1. Clone the repository:
git clone https://github.com/tesseract-creator/runloop-workspace.git
cd runloop-workspace
  1. Navigate to an agent directory:
cd runloop-interview/agent-working-directory/agents/1_lead-gen-sales-agent
  1. Install dependencies:
npm install
# or
bun install
  1. Configure environment variables:
cp .env.example .env
# Edit .env with your API keys (see Environment Setup below)
  1. Run the agent:
npm run start:langgraph
# or
bun run start:langgraph

🔐 Environment Setup

Each production agent requires the following environment variables in a .env file:

Common Variables (All Agents)

# Runloop Platform
RUNLOOP_API_KEY=your_runloop_api_key_here

# Anthropic (Claude)
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Supabase Database
SUPABASE_URL=your_supabase_project_url
SUPABASE_SECRET_KEY=your_supabase_service_role_key

# Resend (Email Notifications)
RESEND_API_KEY=your_resend_api_key_here
FROM_EMAIL=noreply@yourdomain.com
RECIPIENT_EMAIL=your_email@example.com

Agent-Specific Variables

Lead Generation Agent (Agent 1):

# Search APIs
BRAVE_API_KEY=your_brave_search_api_key
TAVILY_API_KEY=your_tavily_api_key          # Optional
EXA_API_KEY=your_exa_api_key                # Optional

Marketing Content Agent (Agent 2):

# Search APIs (for research)
TAVILY_API_KEY=your_tavily_api_key          # Optional
EXA_API_KEY=your_exa_api_key                # Optional

Customer Support Agent (Agent 3):

# No additional variables required

Important Notes

  • Use Service Role Key: For Supabase, use SUPABASE_SECRET_KEY (service role key) instead of SUPABASE_KEY (anon key) to bypass Row-Level Security policies
  • Email Domain: Ensure FROM_EMAIL uses a domain you've verified in Resend
  • API Key Security: Never commit .env files to version control (already in .gitignore)

🛠️ Technology Stack

Core Frameworks

Services & APIs

  • Supabase - PostgreSQL database with real-time capabilities
  • Resend - Transactional email service
  • Brave Search - Web search API
  • Tavily - AI-optimized search API
  • Exa - Semantic search API

Development Tools

  • TypeScript 5.0+ - Type-safe development
  • Node.js 18+ / Bun 1.0+ - Runtime environments
  • ESM Modules - Modern JavaScript modules
  • UUID - Unique identifier generation

✨ Features

Agent Capabilities

  • ✅ Autonomous execution in isolated Runloop devboxes
  • ✅ Multi-step reasoning with LangGraph React agents
  • ✅ Tool orchestration (web search, file operations, API calls)
  • ✅ Streaming responses with real-time progress updates
  • ✅ Error recovery with exponential backoff and retries
  • ✅ State persistence with LangGraph checkpointers

Production Features

  • ✅ Comprehensive logging (structured console output)
  • ✅ Database integration (Supabase with enhanced error logging)
  • ✅ Email notifications (success/failure alerts)
  • ✅ Devbox snapshots (reproducible execution states)
  • ✅ Metrics tracking (tool calls, LLM calls, execution time)
  • ✅ Resource cleanup (automatic devbox shutdown)

Development Features

  • ✅ TypeScript strict mode (full type safety)
  • ✅ Modular architecture (config, lib, types separation)
  • ✅ Environment validation (missing key detection)
  • ✅ Hot reload (tsx watch mode)
  • ✅ Debug mode (verbose logging)

📚 Documentation

Key Resources

Learning Path

  1. Start with SDK Examples: runloop-practice/examples/
  2. Complete Bootcamp: runloop-practice/bootcamp/
  3. Study Production Agents: runloop-interview/agent-working-directory/agents/
  4. Review System Prompts: runloop-system-prompts/templates/
  5. Build Your Own Agent: Use production agents as templates

🎨 Agent Architecture

All production agents follow a consistent architecture pattern:

agent/
├── index.ts                 # Main agent class and execution flow
├── config/
│   └── index.ts            # Environment and configuration loading
├── lib/
│   ├── database.ts         # Supabase client and operations
│   ├── email.ts            # Resend email service
│   ├── prompts.ts          # System prompt loader
│   └── tools.ts            # LangGraph tool definitions
├── prompts/
│   └── system-prompt.md    # Agent system prompt
├── types/
│   └── index.ts            # TypeScript type definitions
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
└── .env.example            # Environment variable template

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

Development Guidelines

  • Follow existing code style and patterns
  • Add TypeScript types for all new code
  • Include comprehensive logging
  • Test agents end-to-end before submitting
  • Update documentation for new features
  • Never commit .env files or API keys

📊 Project Status

Component Status Notes
Lead Gen Agent ✅ Production Enhanced error logging, deduplication
Marketing Content Agent ✅ Production Service role key, enhanced logging
Support Triage Agent ✅ Production Service role key, enhanced logging
SDK Examples ✅ Complete Basic usage patterns
Documentation ✅ Complete Architecture and guides
System Prompts ✅ Complete Template library

🐛 Known Issues & Solutions

Issue: Supabase RLS Policy Violations

Solution: Ensure you're using SUPABASE_SECRET_KEY (service role key) instead of SUPABASE_KEY (anon key) in your .env file.

Issue: Brave API Rate Limiting (Agent 1)

Solution: The agent implements exponential backoff (1s, 2s, 4s, 8s, 16s). Rate limits are 1 req/sec for free tier.

Issue: Empty Database Error Logs

Solution: All agents now include enhanced error logging showing code, message, details, and hints.

Issue: Lead Duplication (Agent 1)

Solution: The agent now normalizes URLs (removes trailing slashes, www, https) before deduplication checks.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

🙏 Acknowledgments

  • Runloop Team - For the incredible devbox platform
  • LangChain Team - For LangGraph.js framework
  • Anthropic - For Claude Sonnet 4.5
  • Open Source Community - For the amazing tools and libraries

📧 Contact

For questions, issues, or collaboration opportunities:

Built with ❤️ using Runloop, LangGraph, and Claude

⭐ Star this repository if you find it useful!

About

Comprehensive Runloop repository that covers all aspects of API, SDK, Fully Implemented Agents and more.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages