🤖 Chat Agent Bot

Features

• 💬 Interactive chat interface with AI
• 🛠️ Built-in tool system with human-in-the-loop confirmation
• 📅 Advanced task scheduling (one-time, delayed, and recurring via cron)
• 🌓 Dark/Light theme support
• ⚡️ Real-time streaming responses
• 🔄 State management and chat history
• 🎨 Modern, responsive UI

Prerequisites

• Cloudflare account
• OpenWeatherMap API key (for weather tool) - Get free API key
• Firecrawl API key (for news scraping tool) - Get free API key
• OpenAI API key (optional - uses Workers AI by default)

Quick Start

1. Create a new project:

npx create-cloudflare@latest --template cloudflare/agents-starter

2. Install dependencies:

npm install

3. Set up your environment:

Create a .dev.vars file in the project root:

OPENWEATHERMAP_API_KEY=your_openweathermap_api_key
FIRECRAWL_API_KEY=your_firecrawl_api_key
OPENAI_API_KEY=your_openai_api_key  # Optional - only if using OpenAI instead of Workers AI

Note: This starter uses Cloudflare Workers AI by default (Llama 3 model). OpenAI API key is only needed if you switch to OpenAI models.

4. Run locally:

npm start

5. Deploy:

npm run deploy

Project Structure

├── src/
│   ├── app.tsx        # Chat UI implementation
│   ├── server.ts      # Chat agent logic
│   ├── tools.ts       # Tool definitions
│   ├── utils.ts       # Helper functions
│   └── styles.css     # UI styling

Built-in Tools

This starter comes with several pre-configured tools:

Auto-Executing Tools (no confirmation needed)

• getLocalTime - Gets the current local time for a location
• scheduleTask - Schedules a task for later execution (one-time, delayed, or recurring via cron)
• getScheduledTasks - Lists all scheduled tasks
• cancelScheduledTask - Cancels a scheduled task by ID

Tools Requiring Confirmation

• getWeatherInformation - Fetches current weather for a city

  • Uses OpenWeatherMap API
  • Returns temperature, conditions, humidity, and wind speed
  • Requires OPENWEATHERMAP_API_KEY in environment

• getTopNews - Scrapes top news from major sources (CNN, BBC, Fox)

  • Uses Firecrawl API for web scraping
  • Returns markdown content from news websites
  • Requires FIRECRAWL_API_KEY in environment

Tools requiring confirmation will prompt the user for approval before execution, providing an extra layer of safety for potentially sensitive operations.

Customization Guide

Adding New Tools

Add new tools in tools.ts using the tool builder:

// Example of a tool that requires confirmation
const searchDatabase = tool({
  description: "Search the database for user records",
  parameters: z.object({
    query: z.string(),
    limit: z.number().optional()
  })
  // No execute function = requires confirmation
});

// Example of an auto-executing tool
const getCurrentTime = tool({
  description: "Get current server time",
  parameters: z.object({}),
  execute: async () => new Date().toISOString()
});

// Scheduling tool implementation
const scheduleTask = tool({
  description:
    "schedule a task to be executed at a later time. 'when' can be a date, a delay in seconds, or a cron pattern.",
  parameters: z.object({
    type: z.enum(["scheduled", "delayed", "cron"]),
    when: z.union([z.number(), z.string()]),
    payload: z.string()
  }),
  execute: async ({ type, when, payload }) => {
    // ... see the implementation in tools.ts
  }
});

To handle tool confirmations, add execution functions to the executions object:

export const executions = {
  searchDatabase: async ({
    query,
    limit
  }: {
    query: string;
    limit?: number;
  }) => {
    // Implementation for when the tool is confirmed
    const results = await db.search(query, limit);
    return results;
  }
  // Add more execution handlers for other tools that require confirmation
};

Tools can be configured in two ways:

1. With an execute function for automatic execution
2. Without an execute function, requiring confirmation and using the executions object to handle the confirmed action. NOTE: The keys in executions should match toolsRequiringConfirmation in app.tsx.

Use a different AI model provider

The starting server.ts implementation uses the ai-sdk and the OpenAI provider, but you can use any AI model provider by:

1. Installing an alternative AI provider for the ai-sdk, such as the workers-ai-provider or anthropic provider:
2. Replacing the AI SDK with the OpenAI SDK
3. Using the Cloudflare Workers AI + AI Gateway binding API directly

For example, to use the workers-ai-provider, install the package:

npm install workers-ai-provider

Add an ai binding to wrangler.jsonc:

// rest of file
  "ai": {
    "binding": "AI"
  }
// rest of file

Replace the @ai-sdk/openai import and usage with the workers-ai-provider:

// server.ts
// Change the imports
- import { openai } from "@ai-sdk/openai";
+ import { createWorkersAI } from 'workers-ai-provider';

// Create a Workers AI instance
+ const workersai = createWorkersAI({ binding: env.AI });

// Use it when calling the streamText method (or other methods)
// from the ai-sdk
- const model = openai("gpt-4o-2024-11-20");
+ const model = workersai("@cf/deepseek-ai/deepseek-r1-distill-qwen-32b")

Commit your changes and then run the agents-starter as per the rest of this README.

Modifying the UI

The chat interface is built with React and can be customized in app.tsx:

• Modify the theme colors in styles.css
• Add new UI components in the chat container
• Customize message rendering and tool confirmation dialogs
• Add new controls to the header

Example Use Cases

1. Customer Support Agent

   • Add tools for:
     • Ticket creation/lookup
     • Order status checking
     • Product recommendations
     • FAQ database search

2. Development Assistant

   • Integrate tools for:
     • Code linting
     • Git operations
     • Documentation search
     • Dependency checking

3. Data Analysis Assistant

   • Build tools for:
     • Database querying
     • Data visualization
     • Statistical analysis
     • Report generation

4. Personal Productivity Assistant

   • Implement tools for:
     • Task scheduling with flexible timing options
     • One-time, delayed, and recurring task management
     • Task tracking with reminders
     • Email drafting
     • Note taking

5. Scheduling Assistant

   • Build tools for:
     • One-time event scheduling using specific dates
     • Delayed task execution (e.g., "remind me in 30 minutes")
     • Recurring tasks using cron patterns
     • Task payload management
     • Flexible scheduling patterns

Each use case can be implemented by:

1. Adding relevant tools in tools.ts
2. Customizing the UI for specific interactions
3. Extending the agent's capabilities in server.ts
4. Adding any necessary external API integrations

Learn More

• agents
• Cloudflare Agents Documentation
• Cloudflare Workers Documentation

License

MIT