{"id":28718087,"url":"https://github.com/brookr/serverless-agents","last_synced_at":"2025-08-26T20:08:20.075Z","repository":{"id":296504333,"uuid":"992404075","full_name":"brookr/serverless-agents","owner":"brookr","description":"Build agents on modern serverless infra for low overhead and high-powered AI app functionality","archived":false,"fork":false,"pushed_at":"2025-07-03T19:20:09.000Z","size":169,"stargazers_count":22,"open_issues_count":0,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-03T20:27:47.052Z","etag":null,"topics":["agents","agentsdk","ai","openai","serverless"],"latest_commit_sha":null,"homepage":"https://serverless-agents.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brookr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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-05-29T05:22:29.000Z","updated_at":"2025-07-03T19:20:13.000Z","dependencies_parsed_at":"2025-06-13T01:26:46.142Z","dependency_job_id":"fa9e497d-792e-417f-9719-872c898f3ce0","html_url":"https://github.com/brookr/serverless-agents","commit_stats":null,"previous_names":["brookr/serverless-agents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/brookr/serverless-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookr%2Fserverless-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookr%2Fserverless-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookr%2Fserverless-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookr%2Fserverless-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brookr","download_url":"https://codeload.github.com/brookr/serverless-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brookr%2Fserverless-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272252444,"owners_count":24900652,"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","status":"online","status_checked_at":"2025-08-26T02:00:07.904Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","agentsdk","ai","openai","serverless"],"created_at":"2025-06-15T04:09:58.969Z","updated_at":"2025-08-26T20:08:20.067Z","avatar_url":"https://github.com/brookr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless Agent Architecture Starter\n\nA production-ready starter project demonstrating how to build full-stack applications with AI agents deployed to Vercel, orchestrated by Inngest, and powered by Next.js 15. This architecture pattern enables you to build scalable AI-powered applications with long-running workflows.\n\n🔗 **GitHub Repository**: [https://github.com/brookr/serverless-agents](https://github.com/brookr/serverless-agents)\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fbrookr%2Fserverless-agents\u0026env=OPENAI_API_KEY,NEWSLETTER_READ_WRITE_TOKEN\u0026envDescription=Configure%20your%20AI%20agents%20and%20storage\u0026envLink=https%3A%2F%2Fgithub.com%2Fbrookr%2Fserverless-agents%23environment-setup\u0026project-name=serverless-agents\u0026repository-name=serverless-agents)\n\n⚠️ **Important**: After deploying, you must configure the Inngest integration in Vercel. See [Deployment Instructions](#-deployment) for details.\n\n![Architecture Pattern](public/newspaper-icon.svg)\n\n## 🏗️ Architecture Pattern\n\nThis starter demonstrates a modern serverless architecture for AI applications:\n\n- **AI Agents as Vercel Functions**: Python FastAPI agents that deploy as serverless functions\n- **Next.js Frontend**: Modern React application with App Router\n- **Inngest Orchestration**: Reliable workflow management for long-running AI tasks\n- **Vercel Blob Storage**: Persistent storage for generated content\n- **Two-Stage Processing**: Separation of concerns with research and formatting agents\n\n## 🎯 Why This Architecture?\n\nThis pattern solves common challenges in AI application development:\n\n- **Serverless Scalability**: Agents scale automatically with demand\n- **Long-Running Jobs**: Inngest handles workflows that exceed typical timeout limits\n- **Cost Efficiency**: Pay only for actual usage, no idle servers\n- **Developer Experience**: Local development mirrors production exactly\n- **Type Safety**: Full TypeScript support across the stack\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+ and npm\n- Python 3.9+\n- OpenAI API key\n- Vercel account (free tier works)\n\n### 1. Clone and Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/brookr/serverless-agents.git\ncd serverless-agents\n\n# Install Node.js dependencies\nnpm install\n\n# Install Python dependencies\npip install -r requirements.txt\n```\n\n### 2. Environment Setup\n\nCreate a `.env.local` file:\n\n```bash\n# Required\nOPENAI_API_KEY=your_openai_api_key_here\nNEWSLETTER_READ_WRITE_TOKEN=your_vercel_blob_token\n\n# Optional (Inngest will auto-generate if not provided)\nINNGEST_SIGNING_KEY=your_inngest_signing_key\n```\n\n### 3. Run Development Servers\n\nYou'll need three terminals:\n\n**Terminal 1 - Python Agent Server:**\n\n```bash\nuvicorn api.agents:app --reload --reload-dir api --port 8000\n```\n\n**Terminal 2 - Next.js Development:**\n\n```bash\nnpm run dev\n```\n\n**Terminal 3 - Inngest Dev Server:**\n\n```bash\nnpx inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest\n```\n\n### 4. Access the Application\n\n- **Main App**: http://localhost:3000\n- **Python API**: http://localhost:8000\n- **Inngest Dashboard**: http://localhost:8288\n\n## 📁 Project Structure\n\n```text\n├── src/\n│   ├── app/                      # Next.js app directory\n│   │   ├── api/\n│   │   │   ├── inngest/         # Inngest webhook endpoint\n│   │   │   └── newsletter/      # API routes for the example app\n│   │   └── newsletter/\n│   │       └── [slug]/          # Dynamic pages\n│   ├── components/              # React components\n│   │   └── ui/                  # shadcn/ui components\n│   ├── inngest/\n│   │   ├── client.ts           # Inngest client configuration\n│   │   └── functions.ts        # Workflow definitions\n│   └── lib/\n│       └── *.ts                # Utilities and helpers\n├── api/\n│   └── agents.py               # FastAPI agent definitions\n├── public/                     # Static assets\n├── vercel.json                # Vercel routing configuration\n├── requirements.txt            # Python dependencies\n└── package.json               # Node.js dependencies\n```\n\n## 🔧 Core Components\n\n### 1. AI Agents (FastAPI + Vercel Functions)\n\nThe `api/agents.py` file demonstrates how to structure AI agents:\n\n```python\n# Example agent structure\nresearch_agent = Agent(\n    name=\"Research Agent\",\n    model=\"gpt-4.1\",\n    instructions=\"...\",\n    tools=[WebSearchTool()]\n)\n\n@app.post(\"/research\")\nasync def research_endpoint(request: TopicsRequest):\n    # Agent logic here\n\n# Example agent structure\nformatting_agent = Agent(\n    name=\"Formatting Agent\", \n    model=\"o3\", # Your OpenAI Org must be verified to use o3. Else use a different model.\n    ...\n)\n```\n\n### 2. Inngest Workflows\n\nThe `src/inngest/functions.ts` shows how to orchestrate long-running tasks:\n\n```typescript\nexport const generateNewsletter = inngest.createFunction(\n  { id: \"generate-newsletter\" },\n  { event: \"newsletter/generate\" },\n  async ({ event, step }) =\u003e {\n    // Multi-step workflow with retries and error handling\n  }\n);\n```\n\n### 3. Next.js Integration\n\nAPI routes in `src/app/api/` demonstrate the integration pattern:\n\n- Webhook endpoint for Inngest\n- Status checking endpoints\n- Trigger endpoints for workflows\n\n### 4. Vercel Configuration\n\nThe `vercel.json` file is critical for proper Python API routing. Build python after NextJS, and configure the routes to point to the python file:\n\n```json\n{\n  \"builds\": [\n    { \"src\": \"package.json\", \"use\": \"@vercel/next\" },\n    { \"src\": \"api/agents.py\", \"use\": \"@vercel/python\" }\n  ],\n  \"routes\": [\n    { \"src\": \"^/api/agents/(.*)\", \"dest\": \"/api/agents.py\" },\n    { \"src\": \"^/api/agents$\", \"dest\": \"/api/agents.py\" }\n  ]\n}\n```\n\nThis configuration ensures that all `/api/agents/*` paths are routed to your Python FastAPI application.\n\n## 🎨 Customizing for Your Use Case\n\nThis starter uses a newsletter generator as an example, but the architecture supports any AI-powered application:\n\n### Common Patterns\n\n1. **Document Processing**\n   - Replace newsletter generation with document analysis\n   - Use multiple agents for extraction, summarization, etc.\n\n2. **Data Pipeline**\n   - Implement ETL workflows with AI enhancement\n   - Chain multiple processing steps\n\n3. **Content Generation**\n   - Build blog post generators, report writers, etc.\n   - Add review and approval workflows\n\n4. **Multi-Modal Applications**\n   - Integrate image generation APIs\n   - Process audio/video with AI agents\n\n### Key Files to Modify\n\n- `api/agents.py` - Define your AI agents and their capabilities\n- `src/inngest/functions.ts` - Create your workflow logic\n- `src/app/api/` - Add your API endpoints\n- `src/app/` - Build your UI\n\n## 🚢 Deployment\n\n### One-Click Deploy with Vercel\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fbrookr%2Fserverless-agents\u0026env=OPENAI_API_KEY,NEWSLETTER_READ_WRITE_TOKEN\u0026envDescription=Configure%20your%20AI%20agents%20and%20storage\u0026envLink=https%3A%2F%2Fgithub.com%2Fbrookr%2Fserverless-agents%23environment-setup\u0026project-name=serverless-agents\u0026repository-name=serverless-agents)\n\n1. **Click the Deploy Button**\n   - This will fork the repository to your GitHub account\n   - You'll be prompted to enter the required environment variables:\n     - `OPENAI_API_KEY` - Your OpenAI API key\n     - `NEWSLETTER_READ_WRITE_TOKEN` - Generate this in Vercel Blob storage settings\n\n2. **Configure Inngest Integration** ⚠️ **Critical Step**\n\n   After deployment completes:\n   - Go to your new project in the Vercel dashboard\n   - Navigate to **Settings** → **Integrations**\n   - Search for and install the **Inngest** integration\n   - Follow the setup wizard to connect your Inngest account\n   - This automatically adds `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`\n\n   **Note**: Without this step, the API routes will return 404 errors!\n\n3. **Redeploy Your Project**\n   - After installing Inngest, go to the **Deployments** tab\n   - Click the three dots menu on the latest deployment\n   - Select **Redeploy**\n   - Wait for the deployment to complete\n\n4. **Verify Everything Works**\n   - Visit your deployed site\n   - Try generating a newsletter\n   - Check that all API endpoints respond:\n     - `/api/newsletter/[slug]` - Newsletter generation\n     - `/api/agents/ping` - Python API health check\n     - `/api/agents/research` - AI research agent\n     - `/api/agents/format` - AI formatting agent\n     - `/api/inngest` - Inngest webhook\n\n⚠️ **Important**: After pressing the Generate Newsletter button, if the progress spinner spins infinitely and you get an error message similar to, \"Your organization must be verified to use the model `o3-2025-04-16`\", then you may need to [verify your organization on OpenAI](https://platform.openai.com/settings/organization/general). If you don't verify, you can switch your model from \"o3\" to something else like \"gpt-4.1\" to get this working.\n\n### Manual Deployment\n\nIf you prefer to deploy manually:\n\n```bash\n# Clone your fork\ngit clone https://github.com/YOUR_USERNAME/serverless-agents\ncd serverless-agents\n\n# Login to Vercel\nvercel login\n\n# Deploy (you'll be prompted for env vars)\nvercel --prod\n```\n\nThen follow steps 2-4 above to configure Inngest.\n\n### Environment Variables Reference\n\n| Variable | Description | When Added |\n|----------|-------------|------------|\n| `OPENAI_API_KEY` | OpenAI API key for AI agents | During deployment |\n| `NEWSLETTER_READ_WRITE_TOKEN` | Vercel Blob storage token | During deployment |\n| `INNGEST_EVENT_KEY` | Event security key | Auto-added by Inngest |\n| `INNGEST_SIGNING_KEY` | Webhook signing key | Auto-added by Inngest |\n\n### Troubleshooting\n\n- **404 on API routes**: Make sure you've installed the Inngest integration and redeployed\n- **500 on Python agents**: Check that `OPENAI_API_KEY` is set correctly\n- **Newsletter not generating**: Verify all environment variables are present in Vercel dashboard\n\n## 🔍 Understanding the Architecture\n\n### Request Flow\n\n1. **User Interaction** → Next.js frontend\n2. **API Route** → Triggers Inngest workflow\n3. **Inngest Function** → Orchestrates the process\n4. **Agent Calls** → Vercel Functions execute AI tasks\n5. **Storage** → Results saved to Vercel Blob\n6. **Response** → User sees the result\n\n### Why Inngest?\n\n- **Reliability**: Automatic retries and error handling\n- **Observability**: Built-in monitoring and debugging\n- **Scalability**: Handles thousands of concurrent workflows\n- **Developer Experience**: Great local development tools\n\n### Why Vercel Functions for Agents?\n\n- **Zero Config**: Python agents deploy automatically\n- **Auto-scaling**: Handle any load without infrastructure management\n- **Cost Effective**: Pay per execution, not for idle time\n- **Global Edge**: Deploy close to your users\n\n## 📄 License\n\nThis project is licensed under CC0 1.0 Universal - see the [LICENSE.md](LICENSE.md) file.\n\n## 📚 Learn More\n\n### Architecture Components\n\n- [Next.js Documentation](https://nextjs.org/docs)\n- [Inngest Documentation](https://www.inngest.com/docs)\n- [Vercel Functions](https://vercel.com/docs/functions)\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n\n### Related Patterns\n\n- [Serverless AI Patterns](https://vercel.com/guides/serverless-ai-patterns)\n- [Long-Running Jobs with Inngest](https://www.inngest.com/docs/guides/long-running-jobs)\n- [Python on Vercel](https://vercel.com/docs/functions/runtimes/python)\n\n## 🎯 Next Steps\n\n1. **Explore the Code**: Start with `api/agents.py` and `src/inngest/functions.ts`\n2. **Run Locally**: Get the development environment running\n3. **Modify for Your Use Case**: Replace the newsletter example with your own AI workflow\n4. **Deploy**: Push to production on Vercel\n5. **Share**: Let us know what you build!\n\n### 🤝 Contributing\n\nWe welcome contributions! See our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n📦 **Repository**: [https://github.com/brookr/serverless-agents](https://github.com/brookr/serverless-agents)\n\n### Contributors\n\nAuthor: [@brookr](https://github.com/brookr)\n\nContributors:\n\n- [@chrisg220](https://github.com/chrisg220)\n- YOUR NAME HERE!\n\n---\n\nBuilt as a reference architecture for modern AI applications. Use this as a starting point for your own serverless agent projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrookr%2Fserverless-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrookr%2Fserverless-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrookr%2Fserverless-agents/lists"}