agentkit-bayengage

# BayEngage Agent Kit

[![CI](https://github.com/yourusername/agentkit-bayengage/workflows/CI/badge.svg)](https://github.com/yourusername/agentkit-bayengage/actions/workflows/ci.yml)
[![Security](https://github.com/yourusername/agentkit-bayengage/workflows/Security/badge.svg)](https://github.com/yourusername/agentkit-bayengage/actions/workflows/security.yml)
[![Deploy](https://github.com/yourusername/agentkit-bayengage/workflows/Deploy/badge.svg)](https://github.com/yourusername/agentkit-bayengage/actions/workflows/deploy.yml)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)

A production-ready OpenAI Agent implementation for BayEngage email marketing automation, built with the `openai-agents-js` SDK.

## Features

- **Complete BayEngage API Integration** - Comprehensive tools for contacts, campaigns, templates, and automation
- **Multi-Agent Architecture** - Specialized agents for campaign management, data analysis, and general operations
- **Production-Ready** - Built-in error handling, retry logic, rate limiting, and request tracing
- **Type-Safe** - Full TypeScript implementation with Zod schema validation
- **Safety Guardrails** - Explicit confirmation required for sending campaigns and activating automation
- **Extensible** - Modular tool structure for easy customization and extension

## Quick Start

### Prerequisites

- Node.js 18+ or 20+
- BayEngage API credentials
- OpenAI API key

### Installation

```bash
npm install
```

### Configuration

1. Copy the environment template:

```bash
cp .env.example .env
```

2. Configure your credentials in `.env`:

```env
BAYENGAGE_API_KEY=your_api_key_here
BAYENGAGE_API_SECRET=your_api_secret_here
BAYENGAGE_API_URL=https://api.bayengage.com/v2
OPENAI_API_KEY=your_openai_api_key_here
PORT=3000
```

### Running the Server

```bash
npm start
```

The server will start at `http://localhost:3000`

## 📚 Examples & Documentation

**New to AgentKit?** Start with our comprehensive examples:

- **[Example Library](./examples/README.md)** - Complete examples directory
- **[Prompt Examples](./examples/prompts/)** - Natural language examples for beginners
- **[API Examples](./examples/api/)** - cURL, TypeScript, Python integration
- **[Workflow Scenarios](./examples/workflows/)** - Complete marketing automation flows
- **[Postman Collection](./examples/api/postman-collection.json)** - Interactive API testing

### Quick Example

```bash
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "List all my campaign segments"
  }'
```

**More examples:**
- See [examples/prompts/01-getting-started.md](./examples/prompts/01-getting-started.md) for your first steps
- Check [examples/api/chat-requests.sh](./examples/api/chat-requests.sh) for ready-to-use cURL commands
- Explore [examples/workflows/](./examples/workflows/) for complete automation scenarios

## Usage

### REST API

#### Chat with the Agent

```bash
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "List all my campaign segments"
  }'
```

#### Use Specialized Agents

```bash
# Campaign Manager Agent
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Create a campaign for Black Friday sale",
    "agent": "campaign_manager"
  }'

# Data Analyst Agent
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Analyze the performance of my last 5 campaigns",
    "agent": "data_analyst"
  }'
```

### Programmatic Usage

```typescript
import { bayEngageAgent } from './src/agent.js';

const stream = bayEngageAgent.run({
  prompt: 'Create a new contact with email john@example.com',
});

for await (const event of stream) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.delta);
  }
}
```

## Available Agents

### 1. BayEngage Marketing Agent (default)

General-purpose agent with access to all BayEngage features.

**Capabilities:**

- Contact management (create, update, retrieve, delete)
- Campaign creation, sending, and analytics
- Template management
- Marketing automation (drip campaigns, A/B tests, newsletters)
- Segment management

### 2. Campaign Manager Agent

Specialized agent focused on campaign operations with enhanced safety protocols.

**Best for:**

- Creating and sending campaigns
- Campaign performance analysis
- Audience targeting and segmentation
- Send time optimization

### 3. Data Analyst Agent

Analytics-focused agent for metrics and insights.

**Best for:**

- Campaign performance analysis
- Trend identification
- ROI calculations
- Benchmarking and recommendations

## Available Tools

### Contact Management

| Tool                       | Description                          |
| -------------------------- | ------------------------------------ |
| `bayengage_create_contact` | Create new contact with profile info |
| `bayengage_update_contact` | Update existing contact details      |
| `bayengage_get_contact`    | Retrieve contact information         |
| `bayengage_delete_contact` | Permanently delete a contact         |

### Campaign Management

| Tool                           | Description                                       |
| ------------------------------ | ------------------------------------------------- |
| `bayengage_list_segments`      | List all audience segments                        |
| `bayengage_create_campaign`    | Create campaign draft                             |
| `bayengage_send_campaign`      | Send or schedule campaign (requires confirmation) |
| `bayengage_get_campaign_stats` | Retrieve campaign analytics                       |
| `bayengage_list_campaigns`     | List all campaigns                                |
| `bayengage_delete_campaign`    | Delete campaign draft                             |

### Template Management

| Tool                        | Description              |
| --------------------------- | ------------------------ |
| `bayengage_list_templates`  | List all email templates |
| `bayengage_get_template`    | Get template details     |
| `bayengage_create_template` | Create new template      |
| `bayengage_update_template` | Update existing template |
| `bayengage_delete_template` | Delete template          |

### Marketing Automation

| Tool                               | Description                            |
| ---------------------------------- | -------------------------------------- |
| `bayengage_create_drip_campaign`   | Create automated email sequence        |
| `bayengage_activate_drip_campaign` | Activate drip campaign                 |
| `bayengage_create_ab_test`         | Create A/B test campaign               |
| `bayengage_start_ab_test`          | Start A/B test (requires confirmation) |
| `bayengage_create_newsletter`      | Create recurring newsletter            |
| `bayengage_pause_newsletter`       | Pause newsletter automation            |
| `bayengage_list_drip_campaigns`    | List all drip campaigns                |

## Examples

### Create and Send a Campaign

```typescript
// 1. Create campaign draft
const createResult = await bayEngageAgent.run({
  prompt: `Create a campaign named "Summer Sale 2025" with subject
    "50% Off Everything!" using template template_123 for segment seg_456`,
});

// 2. Review and confirm
// Agent will show campaign details and ask for confirmation

// 3. Send with confirmation
const sendResult = await bayEngageAgent.run({
  prompt: 'Yes, send the Summer Sale campaign now',
  threadId: createResult.threadId, // Continue conversation
});
```

### Analyze Campaign Performance

```typescript
const analysisResult = await dataAnalystAgent.run({
  prompt: `Analyze campaign campaign_789 and tell me:
    - How it performed vs benchmarks
    - W

[truncated…]