{"id":25940517,"url":"https://github.com/cloudflare/agents-starter","last_synced_at":"2025-05-15T08:00:27.159Z","repository":{"id":278735209,"uuid":"936369652","full_name":"cloudflare/agents-starter","owner":"cloudflare","description":"A starter kit for building ai agents on Cloudflare","archived":false,"fork":false,"pushed_at":"2025-05-12T13:11:44.000Z","size":361,"stargazers_count":736,"open_issues_count":9,"forks_count":100,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-12T14:39:18.599Z","etag":null,"topics":["agents","ai","cloudflare","durable-objects"],"latest_commit_sha":null,"homepage":"https://github.com/cloudflare/agents/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-21T00:58:55.000Z","updated_at":"2025-05-12T13:45:08.000Z","dependencies_parsed_at":"2025-03-26T04:01:40.846Z","dependency_job_id":"42197799-b501-43cc-8000-b770fc09c224","html_url":"https://github.com/cloudflare/agents-starter","commit_stats":null,"previous_names":["threepointone/agents-starter","cloudflare/agents-starter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/agents-starter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301420,"owners_count":22047901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","cloudflare","durable-objects"],"created_at":"2025-03-04T05:16:59.771Z","updated_at":"2025-05-15T08:00:27.127Z","avatar_url":"https://github.com/cloudflare.png","language":"TypeScript","readme":"# 🤖 Chat Agent Starter Kit\n\n![agents-header](https://github.com/user-attachments/assets/f6d99eeb-1803-4495-9c5e-3cf07a37b402)\n\n\u003ca href=\"https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/agents-starter\"\u003e\u003cimg src=\"https://deploy.workers.cloudflare.com/button\" alt=\"Deploy to Cloudflare\"/\u003e\u003c/a\u003e\n\nA 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.\n\n## Features\n\n- 💬 Interactive chat interface with AI\n- 🛠️ Built-in tool system with human-in-the-loop confirmation\n- 📅 Advanced task scheduling (one-time, delayed, and recurring via cron)\n- 🌓 Dark/Light theme support\n- ⚡️ Real-time streaming responses\n- 🔄 State management and chat history\n- 🎨 Modern, responsive UI\n\n## Prerequisites\n\n- Cloudflare account\n- OpenAI API key\n\n## Quick Start\n\n1. Create a new project:\n\n```bash\nnpx create-cloudflare@latest --template cloudflare/agents-starter\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n3. Set up your environment:\n\nCreate a `.dev.vars` file:\n\n```env\nOPENAI_API_KEY=your_openai_api_key\n```\n\n4. Run locally:\n\n```bash\nnpm start\n```\n\n5. Deploy:\n\n```bash\nnpm run deploy\n```\n\n## Project Structure\n\n```\n├── src/\n│   ├── app.tsx        # Chat UI implementation\n│   ├── server.ts      # Chat agent logic\n│   ├── tools.ts       # Tool definitions\n│   ├── utils.ts       # Helper functions\n│   └── styles.css     # UI styling\n```\n\n## Customization Guide\n\n### Adding New Tools\n\nAdd new tools in `tools.ts` using the tool builder:\n\n```typescript\n// Example of a tool that requires confirmation\nconst searchDatabase = tool({\n  description: \"Search the database for user records\",\n  parameters: z.object({\n    query: z.string(),\n    limit: z.number().optional(),\n  }),\n  // No execute function = requires confirmation\n});\n\n// Example of an auto-executing tool\nconst getCurrentTime = tool({\n  description: \"Get current server time\",\n  parameters: z.object({}),\n  execute: async () =\u003e new Date().toISOString(),\n});\n\n// Scheduling tool implementation\nconst scheduleTask = tool({\n  description:\n    \"schedule a task to be executed at a later time. 'when' can be a date, a delay in seconds, or a cron pattern.\",\n  parameters: z.object({\n    type: z.enum([\"scheduled\", \"delayed\", \"cron\"]),\n    when: z.union([z.number(), z.string()]),\n    payload: z.string(),\n  }),\n  execute: async ({ type, when, payload }) =\u003e {\n    // ... see the implementation in tools.ts\n  },\n});\n```\n\nTo handle tool confirmations, add execution functions to the `executions` object:\n\n```typescript\nexport const executions = {\n  searchDatabase: async ({\n    query,\n    limit,\n  }: {\n    query: string;\n    limit?: number;\n  }) =\u003e {\n    // Implementation for when the tool is confirmed\n    const results = await db.search(query, limit);\n    return results;\n  },\n  // Add more execution handlers for other tools that require confirmation\n};\n```\n\nTools can be configured in two ways:\n\n1. With an `execute` function for automatic execution\n2. Without an `execute` function, requiring confirmation and using the `executions` object to handle the confirmed action\n\n### Use a different AI model provider\n\nThe 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:\n\n1. 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:\n2. Replacing the AI SDK with the [OpenAI SDK](https://github.com/openai/openai-node)\n3. Using the Cloudflare [Workers AI + AI Gateway](https://developers.cloudflare.com/ai-gateway/providers/workersai/#workers-binding) binding API directly\n\nFor example, to use the [`workers-ai-provider`](https://sdk.vercel.ai/providers/community-providers/cloudflare-workers-ai), install the package:\n\n```sh\nnpm install workers-ai-provider\n```\n\nAdd an `ai` binding to `wrangler.jsonc`:\n\n```jsonc\n// rest of file\n  \"ai\": {\n    \"binding\": \"AI\"\n  }\n// rest of file\n```\n\nReplace the `@ai-sdk/openai` import and usage with the `workers-ai-provider`:\n\n```diff\n// server.ts\n// Change the imports\n- import { openai } from \"@ai-sdk/openai\";\n+ import { createWorkersAI } from 'workers-ai-provider';\n\n// Create a Workers AI instance\n+ const workersai = createWorkersAI({ binding: env.AI });\n\n// Use it when calling the streamText method (or other methods)\n// from the ai-sdk\n- const model = openai(\"gpt-4o-2024-11-20\");\n+ const model = workersai(\"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b\")\n```\n\nCommit your changes and then run the `agents-starter` as per the rest of this README.\n\n### Modifying the UI\n\nThe chat interface is built with React and can be customized in `app.tsx`:\n\n- Modify the theme colors in `styles.css`\n- Add new UI components in the chat container\n- Customize message rendering and tool confirmation dialogs\n- Add new controls to the header\n\n### Example Use Cases\n\n1. **Customer Support Agent**\n\n   - Add tools for:\n     - Ticket creation/lookup\n     - Order status checking\n     - Product recommendations\n     - FAQ database search\n\n2. **Development Assistant**\n\n   - Integrate tools for:\n     - Code linting\n     - Git operations\n     - Documentation search\n     - Dependency checking\n\n3. **Data Analysis Assistant**\n\n   - Build tools for:\n     - Database querying\n     - Data visualization\n     - Statistical analysis\n     - Report generation\n\n4. **Personal Productivity Assistant**\n\n   - Implement tools for:\n     - Task scheduling with flexible timing options\n     - One-time, delayed, and recurring task management\n     - Task tracking with reminders\n     - Email drafting\n     - Note taking\n\n5. **Scheduling Assistant**\n   - Build tools for:\n     - One-time event scheduling using specific dates\n     - Delayed task execution (e.g., \"remind me in 30 minutes\")\n     - Recurring tasks using cron patterns\n     - Task payload management\n     - Flexible scheduling patterns\n\nEach use case can be implemented by:\n\n1. Adding relevant tools in `tools.ts`\n2. Customizing the UI for specific interactions\n3. Extending the agent's capabilities in `server.ts`\n4. Adding any necessary external API integrations\n\n## Learn More\n\n- [`agents`](https://github.com/cloudflare/agents/blob/main/packages/agents/README.md)\n- [Cloudflare Agents Documentation](https://developers.cloudflare.com/agents/)\n- [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/)\n\n## License\n\nMIT\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fagents-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fagents-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fagents-starter/lists"}