🤖 Chat Agent Starter Kit

A starter template for building AI-powered chat agents using Cloudflare's Agent platform, powered by agents. This project provides a foundation for creating interactive chat experiences with AI, complete with a modern UI and tool integration capabilities.

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)
• 🎨 Image Generation - Create images from natural language descriptions
• 🎬 Video Creation - Generate videos from text prompts with realistic styles
• 🌐 Web Browsing - Browse websites, capture screenshots, and extract information
• 🌓 Dark/Light theme support
• ⚡️ Real-time streaming responses
• 🔄 State management and chat history
• 🎨 Modern, responsive UI

MCP Tool Capabilities

This starter automatically connects to ATXP MCP (Model Context Protocol) servers when configured with an ATXP_CONNECTION, providing advanced capabilities:

🎨 Image Generation

Create images from natural language descriptions. Try prompts like:

• "Create an image of a sunset over mountains"
• "Generate a logo for a tech startup"
• "Draw a cartoon character with blue hair"

🎬 Video Creation

Generate videos from text prompts with various styles. Try prompts like:

• "Create a video of waves crashing on a beach"
• "Generate a timelapse of a city at night"
• "Make a video showing a product rotating"

🌐 Web Browsing

Browse websites, capture screenshots, and extract information. Try prompts like:

• "Take a screenshot of example.com"
• "What's on the homepage of github.com?"
• "Extract the main article from this news site"

These capabilities are automatically enabled when you set up your ATXP connection string. No additional configuration required!

Prerequisites

• Cloudflare account
• ATXP Account (get your connection string from accounts.atxp.ai)

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:

ATXP_CONNECTION=https://accounts.atxp.ai?connection_token=<your_token>&account_id=<your_account_id>

Get your ATXP connection string from https://accounts.atxp.ai

4. Run locally:

npm start

5. Deploy:

First, set your ATXP connection string as a secret:

wrangler secret put ATXP_CONNECTION

Then 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

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.

AI Model Provider

This starter uses the ATXP LLM Gateway which provides OpenAI-compatible API access through the @ai-sdk/openai-compatible provider. The ATXP Gateway allows you to manage your LLM usage with a single connection string.

If you want to use a different AI model provider, you can:

1. Install an alternative AI provider for the ai-sdk, such as the workers-ai-provider or anthropic provider
2. Replace the AI SDK with the OpenAI SDK
3. Use 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