agents-starter

agents-starter

A starter kit for building ai agents on Cloudflare

Stars: 231

Visit
 screenshot

A starter template for building AI-powered chat agents using Cloudflare's Agent platform, powered by agents-sdk. It provides a foundation for creating interactive chat experiences with AI, complete with a modern UI and tool integration capabilities. Features include interactive chat interface with AI, built-in tool system with human-in-the-loop confirmation, advanced task scheduling, dark/light theme support, real-time streaming responses, state management, and chat history. Prerequisites include a Cloudflare account and OpenAI API key. The project structure includes components for chat UI implementation, chat agent logic, tool definitions, and helper functions. Customization guide covers adding new tools, modifying the UI, and example use cases for customer support, development assistant, data analysis assistant, personal productivity assistant, and scheduling assistant.

README:

🤖 Chat Agent Starter Kit

agents-header

A starter template for building AI-powered chat agents using Cloudflare's Agent platform, powered by agents-sdk. 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)
  • 🌓 Dark/Light theme support
  • ⚡️ Real-time streaming responses
  • 🔄 State management and chat history
  • 🎨 Modern, responsive UI

Prerequisites

  • Cloudflare account
  • OpenAI API key

Quick Start

  1. Create a new project:
npm create cloudflare@latest -- --template cloudflare/agents-starter
  1. Install dependencies:
npm install
  1. Set up your environment:

Create a .dev.vars file:

OPENAI_API_KEY=your_openai_api_key
  1. Run locally:
npm start
  1. 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

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

License

MIT

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for agents-starter

Similar Open Source Tools

For similar tasks

For similar jobs