|
1 | | -# 🤖 Chat Agent Starter Kit |
| 1 | +🌲 Forest Friends - Social Skills Helper |
2 | 2 |
|
3 | | - |
| 3 | +A safe place for kids to practice talking and making friends, built with love for my brother. |
4 | 4 |
|
5 | | -<a href="https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/agents-starter"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare"/></a> |
| 5 | +Live Demo: [[AI_BOT](https://autism-social-coach-frontend.pages.dev/)] |
6 | 6 |
|
7 | | -A starter template for building AI-powered chat agents using Cloudflare's Agent platform, powered by [`agents`](https://www.npmjs.com/package/agents). This project provides a foundation for creating interactive chat experiences with AI, complete with a modern UI and tool integration capabilities. |
| 7 | +💚 Why I Built This |
| 8 | +I have a younger brother with autism, and watching him navigate social situations inspired me to create something that could help. He loves the color green and anything related to forests and nature. |
| 9 | +Sometimes, practicing conversations can feel stressful - worrying about saying the wrong thing or not understanding what someone means. I wanted to build a space where he (and other kids like him) could practice without any pressure. No judgment. No rush. Just a patient friend who's always there to listen and help. |
| 10 | +This app is my way of combining what I love (building things with code) with what matters most (helping my brother feel more confident talking with others). |
8 | 11 |
|
9 | | -## Features |
| 12 | +🦊 What This Does |
| 13 | +Forest Friends is a chat app where kids can: |
10 | 14 |
|
11 | | -- 💬 Interactive chat interface with AI |
12 | | -- 🛠️ Built-in tool system with human-in-the-loop confirmation |
13 | | -- 📅 Advanced task scheduling (one-time, delayed, and recurring via cron) |
14 | | -- 🌓 Dark/Light theme support |
15 | | -- ⚡️ Real-time streaming responses |
16 | | -- 🔄 State management and chat history |
17 | | -- 🎨 Modern, responsive UI |
| 15 | +Practice saying hello - Learn different ways to greet people |
| 16 | +Talk about feelings - Put words to emotions in a safe way |
| 17 | +Ask questions - Get comfortable with back-and-forth conversations |
| 18 | +Share interests - Talk about things they love without feeling awkward |
18 | 19 |
|
19 | | -## Prerequisites |
| 20 | +The app remembers progress and celebrates wins with fun forest badges. Every small step forward gets recognized because every step matters. |
20 | 21 |
|
21 | | -- Cloudflare account |
22 | | -- OpenAI API key |
| 22 | +🎯 How It Helps Kids with Autism |
| 23 | +Kids on the spectrum often benefit from: |
23 | 24 |
|
24 | | -## Quick Start |
| 25 | +Predictable patterns - The app responds consistently, no surprises |
| 26 | +Clear, simple language - No confusing idioms or sarcasm |
| 27 | +Visual feedback - Progress bars and badges show growth clearly |
| 28 | +Safe practice space - No real-world pressure, practice at your own pace |
| 29 | +Patience - The AI never gets tired or frustrated |
25 | 30 |
|
26 | | -1. Create a new project: |
| 31 | +My brother struggles with abstract language and unexpected changes in conversation. This app keeps things concrete and steady, which helps him feel more comfortable. |
27 | 32 |
|
28 | | -```bash |
29 | | -npx create-cloudflare@latest --template cloudflare/agents-starter |
30 | | -``` |
| 33 | +🌳 The Forest Theme |
| 34 | +The green forest theme isn't just decoration - it's intentional. My brother finds nature calming, and green is his favorite color. When he's overwhelmed, going outside or looking at trees helps him reset. |
| 35 | +I wanted the app to feel like a peaceful walk in the woods - somewhere safe and familiar where he can be himself. |
31 | 36 |
|
32 | | -2. Install dependencies: |
| 37 | +🛠️ How I Built It |
| 38 | +I used Cloudflare's platform because it met all the technical requirements for the assignment, but more importantly, it let me build something that actually works and can scale. |
| 39 | +Tech stack: |
33 | 40 |
|
34 | | -```bash |
| 41 | +Cloudflare Workers - Runs the backend |
| 42 | +Workers AI (Llama 3.3) - Powers the conversations |
| 43 | +Durable Objects - Remembers each kid's progress |
| 44 | +Cloudflare Pages - Hosts the forest-themed interface |
| 45 | + |
| 46 | +The AI is prompted specifically to use literal, simple language and avoid things that confuse kids with autism (like idioms, sarcasm, or abstract concepts). |
| 47 | + |
| 48 | +🎨 Design Choices |
| 49 | +Everything about the design considers how my brother (and kids like him) experience the world: |
| 50 | + |
| 51 | +Forest animals as progress icons - More engaging than generic checkmarks |
| 52 | +Green color palette - Calming and familiar |
| 53 | +Large, clear buttons - Easy to see and click |
| 54 | +Consistent layout - Nothing moves around unexpectedly |
| 55 | +Simple animations - Fun but not overwhelming |
| 56 | +Clear visual progress - You can SEE yourself improving |
| 57 | + |
| 58 | + |
| 59 | +📊 Sample Conversation |
| 60 | +Forest Friend: Hi there! I'm your forest friend. What's your name? |
| 61 | + |
| 62 | +User: Tommy |
| 63 | + |
| 64 | +Forest Friend: Nice to meet you, Tommy! How old are you? |
| 65 | + |
| 66 | +User: 8 |
| 67 | + |
| 68 | +Forest Friend: Cool! I'm here to practice talking. |
| 69 | + Want to practice saying hello or talking about feelings? |
| 70 | + |
| 71 | +User: Saying hello |
| 72 | + |
| 73 | +Forest Friend: Great choice! Let's practice. |
| 74 | + Hello Tommy! How are you today? |
| 75 | + |
| 76 | +User: Hello! I'm good |
| 77 | + |
| 78 | +Forest Friend: Awesome! You did a really good job saying hello back. |
| 79 | + [🦊 Badge Earned: First Hello!] |
| 80 | + |
| 81 | +🚀 Running It Yourself |
| 82 | +If you want to run this for your own family member: |
| 83 | +bash# Clone it |
| 84 | +git clone https://github.com/YOUR-USERNAME/autism-social-coach.git |
| 85 | +cd autism-social-coach |
| 86 | + |
| 87 | +# Install stuff |
35 | 88 | npm install |
36 | | -``` |
37 | | - |
38 | | -3. Set up your environment: |
39 | | - |
40 | | -Create a `.dev.vars` file: |
41 | | - |
42 | | -```env |
43 | | -OPENAI_API_KEY=your_openai_api_key |
44 | | -``` |
45 | | - |
46 | | -4. Run locally: |
47 | | - |
48 | | -```bash |
49 | | -npm start |
50 | | -``` |
51 | | - |
52 | | -5. Deploy: |
53 | | - |
54 | | -```bash |
55 | | -npm run deploy |
56 | | -``` |
57 | | - |
58 | | -## Project Structure |
59 | | - |
60 | | -``` |
61 | | -├── src/ |
62 | | -│ ├── app.tsx # Chat UI implementation |
63 | | -│ ├── server.ts # Chat agent logic |
64 | | -│ ├── tools.ts # Tool definitions |
65 | | -│ ├── utils.ts # Helper functions |
66 | | -│ └── styles.css # UI styling |
67 | | -``` |
68 | | - |
69 | | -## Customization Guide |
70 | | - |
71 | | -### Adding New Tools |
72 | | - |
73 | | -Add new tools in `tools.ts` using the tool builder: |
74 | | - |
75 | | -```ts |
76 | | -// Example of a tool that requires confirmation |
77 | | -const searchDatabase = tool({ |
78 | | - description: "Search the database for user records", |
79 | | - parameters: z.object({ |
80 | | - query: z.string(), |
81 | | - limit: z.number().optional() |
82 | | - }) |
83 | | - // No execute function = requires confirmation |
84 | | -}); |
85 | | - |
86 | | -// Example of an auto-executing tool |
87 | | -const getCurrentTime = tool({ |
88 | | - description: "Get current server time", |
89 | | - parameters: z.object({}), |
90 | | - execute: async () => new Date().toISOString() |
91 | | -}); |
92 | | - |
93 | | -// Scheduling tool implementation |
94 | | -const scheduleTask = tool({ |
95 | | - description: |
96 | | - "schedule a task to be executed at a later time. 'when' can be a date, a delay in seconds, or a cron pattern.", |
97 | | - parameters: z.object({ |
98 | | - type: z.enum(["scheduled", "delayed", "cron"]), |
99 | | - when: z.union([z.number(), z.string()]), |
100 | | - payload: z.string() |
101 | | - }), |
102 | | - execute: async ({ type, when, payload }) => { |
103 | | - // ... see the implementation in tools.ts |
104 | | - } |
105 | | -}); |
106 | | -``` |
107 | | - |
108 | | -To handle tool confirmations, add execution functions to the `executions` object: |
109 | | - |
110 | | -```typescript |
111 | | -export const executions = { |
112 | | - searchDatabase: async ({ |
113 | | - query, |
114 | | - limit |
115 | | - }: { |
116 | | - query: string; |
117 | | - limit?: number; |
118 | | - }) => { |
119 | | - // Implementation for when the tool is confirmed |
120 | | - const results = await db.search(query, limit); |
121 | | - return results; |
122 | | - } |
123 | | - // Add more execution handlers for other tools that require confirmation |
124 | | -}; |
125 | | -``` |
126 | | - |
127 | | -Tools can be configured in two ways: |
128 | | - |
129 | | -1. With an `execute` function for automatic execution |
130 | | -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`. |
131 | | - |
132 | | -### Use a different AI model provider |
133 | | - |
134 | | -The starting [`server.ts`](https://github.com/cloudflare/agents-starter/blob/main/src/server.ts) implementation uses the [`ai-sdk`](https://sdk.vercel.ai/docs/introduction) and the [OpenAI provider](https://sdk.vercel.ai/providers/ai-sdk-providers/openai), but you can use any AI model provider by: |
135 | | - |
136 | | -1. Installing an alternative AI provider for the `ai-sdk`, such as the [`workers-ai-provider`](https://sdk.vercel.ai/providers/community-providers/cloudflare-workers-ai) or [`anthropic`](https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic) provider: |
137 | | -2. Replacing the AI SDK with the [OpenAI SDK](https://github.com/openai/openai-node) |
138 | | -3. Using the Cloudflare [Workers AI + AI Gateway](https://developers.cloudflare.com/ai-gateway/providers/workersai/#workers-binding) binding API directly |
139 | | - |
140 | | -For example, to use the [`workers-ai-provider`](https://sdk.vercel.ai/providers/community-providers/cloudflare-workers-ai), install the package: |
141 | | - |
142 | | -```sh |
143 | | -npm install workers-ai-provider |
144 | | -``` |
145 | | - |
146 | | -Add an `ai` binding to `wrangler.jsonc`: |
147 | | - |
148 | | -```jsonc |
149 | | -// rest of file |
150 | | - "ai": { |
151 | | - "binding": "AI" |
152 | | - } |
153 | | -// rest of file |
154 | | -``` |
155 | | - |
156 | | -Replace the `@ai-sdk/openai` import and usage with the `workers-ai-provider`: |
157 | | - |
158 | | -```diff |
159 | | -// server.ts |
160 | | -// Change the imports |
161 | | -- import { openai } from "@ai-sdk/openai"; |
162 | | -+ import { createWorkersAI } from 'workers-ai-provider'; |
163 | | - |
164 | | -// Create a Workers AI instance |
165 | | -+ const workersai = createWorkersAI({ binding: env.AI }); |
166 | | - |
167 | | -// Use it when calling the streamText method (or other methods) |
168 | | -// from the ai-sdk |
169 | | -- const model = openai("gpt-4o-2024-11-20"); |
170 | | -+ const model = workersai("@cf/deepseek-ai/deepseek-r1-distill-qwen-32b") |
171 | | -``` |
172 | | - |
173 | | -Commit your changes and then run the `agents-starter` as per the rest of this README. |
174 | | - |
175 | | -### Modifying the UI |
176 | | - |
177 | | -The chat interface is built with React and can be customized in `app.tsx`: |
178 | | - |
179 | | -- Modify the theme colors in `styles.css` |
180 | | -- Add new UI components in the chat container |
181 | | -- Customize message rendering and tool confirmation dialogs |
182 | | -- Add new controls to the header |
183 | | - |
184 | | -### Example Use Cases |
185 | | - |
186 | | -1. **Customer Support Agent** |
187 | | - - Add tools for: |
188 | | - - Ticket creation/lookup |
189 | | - - Order status checking |
190 | | - - Product recommendations |
191 | | - - FAQ database search |
192 | | - |
193 | | -2. **Development Assistant** |
194 | | - - Integrate tools for: |
195 | | - - Code linting |
196 | | - - Git operations |
197 | | - - Documentation search |
198 | | - - Dependency checking |
199 | | - |
200 | | -3. **Data Analysis Assistant** |
201 | | - - Build tools for: |
202 | | - - Database querying |
203 | | - - Data visualization |
204 | | - - Statistical analysis |
205 | | - - Report generation |
206 | | - |
207 | | -4. **Personal Productivity Assistant** |
208 | | - - Implement tools for: |
209 | | - - Task scheduling with flexible timing options |
210 | | - - One-time, delayed, and recurring task management |
211 | | - - Task tracking with reminders |
212 | | - - Email drafting |
213 | | - - Note taking |
214 | | - |
215 | | -5. **Scheduling Assistant** |
216 | | - - Build tools for: |
217 | | - - One-time event scheduling using specific dates |
218 | | - - Delayed task execution (e.g., "remind me in 30 minutes") |
219 | | - - Recurring tasks using cron patterns |
220 | | - - Task payload management |
221 | | - - Flexible scheduling patterns |
222 | | - |
223 | | -Each use case can be implemented by: |
224 | 89 |
|
225 | | -1. Adding relevant tools in `tools.ts` |
226 | | -2. Customizing the UI for specific interactions |
227 | | -3. Extending the agent's capabilities in `server.ts` |
228 | | -4. Adding any necessary external API integrations |
229 | | - |
230 | | -## Learn More |
| 90 | +# Login to Cloudflare (one-time setup) |
| 91 | +wrangler login |
| 92 | + |
| 93 | +# Test it locally |
| 94 | +wrangler dev |
| 95 | + |
| 96 | +# Deploy it |
| 97 | +wrangler deploy |
| 98 | +wrangler pages deploy frontend --project-name=forest-friends |
| 99 | + |
| 100 | + |
| 101 | +🌱 What's Next |
| 102 | +Ideas I'd like to add: |
| 103 | + |
| 104 | +More forest animals - Different animals could teach different skills |
| 105 | +Voice option - Some kids prefer talking over typing |
| 106 | +Parent view - Let parents see weekly progress without interrupting practice |
| 107 | +Story mode - Practice conversations in the context of forest adventures |
| 108 | +Calming exercises - When things feel overwhelming, guided breathing with forest sounds |
| 109 | + |
| 110 | + |
231 | 111 |
|
232 | 112 | - [`agents`](https://github.com/cloudflare/agents/blob/main/packages/agents/README.md) |
233 | 113 | - [Cloudflare Agents Documentation](https://developers.cloudflare.com/agents/) |
|
0 commit comments