npm package: @paid-ai/create-paid-ai-agent
Description: Create paid AI agent projects with modern frameworks like AI SDK and LangGraph
Author: paid-ai
Latest version: 1.1.18

# Create Paid AI Agent

A powerful CLI tool for creating production-ready AI agent projects with modern frameworks like **Vercel AI SDK** and **LangGraph**. Similar to `create-react-app`, but specifically designed for building sophisticated, monetizable AI agents with built-in usage tracking and billing.

## Quick Start

```bash
# Create a new AI agent project (replace 'my-paid-agent' with your desired project name)
npx @paid-ai/create-paid-ai-agent my-paid-agent --api-key <your-paid-token>
```

## Prerequisites

- **Node.js**: Version 18.0.0 or higher
- **npm**: Version 8.0.0 or higher
- **OpenAI API Key**: For GPT-4o-mini and DALL-E access
- **Paid.ai Account**: For usage tracking and billing

## Getting Started

**First, create a Paid.ai account** to retrieve your paid token for usage tracking and billing:

1. Sign up at [https://app.paid.ai/](https://app.paid.ai/)
2. Go to **Developers**
3. Select **Generate API Key**

Then create your new project:

```bash
npx @paid-ai/create-paid-ai-agent <your-new-project-name> --api-key <your-paid-token>
```

**Parameters:**
- `<your-new-project-name>` - The name for your new AI agent project (this will be the directory name and project name)
- `<your-paid-token>` - Your Paid.ai API key from the Developers section

### Example

```bash
npx @paid-ai/create-paid-ai-agent my-awesome-agent --api-key abc123...
```

This creates a new project directory called `my-awesome-agent` and sets up your AI agent project.

This will:
1. **Ask you to choose an AI framework** (AI SDK or LangGraph)
2. **Ask you to choose a project type** (Fullstack or CLI)
3. **Setup an AI agent** with the specified name
4. **Generate a unique agent ID** for tracking - **save this agent ID for your .env file**

### Interactive Setup

The CLI will guide you through the setup process:

```
? Choose your AI framework:
  ❯ AI SDK (Recommended)
    LangGraph (Advanced)

? Choose your project type:
  ❯ Fullstack (Next.js + API routes)
    CLI Only (Coming Soon)

? Project name: my-ai-agent
```

## Options

### AI Frameworks

**AI SDK (Recommended)**
- **Vercel AI SDK v5** integration with Agent class
- **Built-in tool orchestration** and step counting
- **Streaming responses** for real-time chat experience
- **Easy deployment** to Vercel with serverless functions
- **Simplified development** with minimal boilerplate

**LangGraph (Advanced)**
- **LangChain LangGraph** support with StateGraph
- **Advanced agent workflows** with conditional routing
- **Explicit state management** with custom reducers
- **Fine-grained control** over agent behavior
- **Complex multi-step reasoning** capabilities

### Project Types

**Fullstack (Next.js + API routes)**
- **Complete web application** with frontend and backend
- **API routes** for agent endpoints and health checks
- **Built-in authentication** ready for user management
- **Real-time chat interface** with streaming responses
- **Production deployment** optimized for Vercel

**CLI Only (Coming Soon)**
- **Command-line interface** for automation
- **Perfect for integration** with existing tools
- **Lightweight deployment** options
- **Batch processing** capabilities

## Built-in Tools

All templates include four powerful tools for complete agent development:

### 1. **createElevatorPitch**
- Generates compelling elevator pitches for AI agents
- Structured object generation with Zod schemas
- Target audience customization
- Structured output with key points and call-to-action

### 2. **generateLogo**
- Creates logos using OpenAI's DALL-E image generation
- Image generation with OpenAI's DALL-E API
- Incorporates extracted vibes for consistent branding
- High-quality 1024x1024 images

### 3. **describeArchitecture**
- Provides comprehensive technical architecture recommendations
- Streaming text generation for real-time responses
- Language and framework suggestions
- Deployment considerations

### 4. **extractVibes**
- Extracts 3-10 brand descriptors from agent descriptions
- Silent tool handling and RAG-powered context from similar agents
- Uses RAG-powered context from similar agents
- Silent execution (AI SDK) or explicit routing (LangGraph)

## Environment Setup

1. **Copy the environment template:**
   ```bash
   cp .env.example .env
   ```

2. **Fill out your credentials:**
   ```bash
   # Edit .env.local file with your actual API keys
   OPENAI_API_KEY=sk-your-actual-openai-key
   AGENT_ID=your-actual-agent-id
   PAID_API_KEY=your-actual-paid-api-key
   ```

3. **Never commit `.env` to version control**

## Troubleshooting

### Common Issues

**1. OpenAI API Key Error**
```
Error: Invalid API key
```
- Verify your `OPENAI_API_KEY` in `.env.local`
- Ensure the key has sufficient credits
- Check API key permissions

**2. Paid.ai Integration Error**
```
Error: Failed to record usage
```
- Verify `AGENT_ID` and `PAID_API_KEY` in `.env.local`
- Check Paid.ai dashboard for account status
- Ensure agent ID matches your Paid.ai configuration

### Getting Help

- **Issues**: [GitHub Issues](https://github.com/paid-ai/create-paid-ai-agent/issues)
- **Discussions**: [GitHub Discussions](https://github.com/paid-ai/create-paid-ai-agent/discussions)
- **Documentation**: Check individual template READMEs for detailed guides

## License

MIT License - see [LICENSE](LICENSE) file for details.