Engine Room

Signal management and campaign operations

Engine Room

The Engine Room is the configuration and management hub of AgencyOS, where you define signals, manage campaigns, and configure integrations.

Overview

The Engine Room provides the operational foundation for AgencyOS. Here you create and manage the building blocks (signals) that power your marketing operations.

Core Concepts

Signals

Signals are the atomic units of execution in AgencyOS. Each signal represents a discrete marketing operation.

Signal Properties:

• Name: Descriptive identifier
• Description: What the signal does
• Category: Organizational grouping
• ActivePieces Flow ID: Integration reference
• Input Schema: Required parameters
• Output Schema: Expected results

Campaigns

Campaigns are configured executions of signals, either one-time or recurring.

Campaign Properties:

• Name: Campaign identifier
• Signal: Which signal to execute
• Schedule: When to run (one-time or recurring)
• Configuration: Signal-specific parameters
• Status: Draft, active, paused, or completed

Signal Management

Creating a Signal

1. Navigate to Engine Room → Signals
2. Click "New Signal"
3. Fill in details:
   • Name (e.g., "LinkedIn Post Generator")
   • Description (e.g., "Generates professional LinkedIn posts")
   • Category (e.g., "Content Generation")
4. Configure integration:
   • ActivePieces Flow ID
   • Input/output schemas
5. Save signal

Signal Categories

Organize signals by category:

• Content Generation: Text, images, videos
• Distribution: Publishing to platforms
• Analytics: Performance tracking
• Automation: Workflow operations

Input/Output Schemas

Define what data signals need and produce:

// Input Schema Example
{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Post topic"
    },
    "tone": {
      "type": "string",
      "enum": ["professional", "casual", "technical"]
    },
    "length": {
      "type": "number",
      "minimum": 100,
      "maximum": 3000
    }
  },
  "required": ["topic"]
}

// Output Schema Example
{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Generated post content"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "word_count": { "type": "number" },
        "hashtags": { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}

Testing Signals

Before using signals in production:

1. Test execution with sample data
2. Verify output matches expectations
3. Check error handling with invalid inputs
4. Validate integration with ActivePieces

Campaign Management

Creating a Campaign

1. Navigate to Engine Room → Campaigns
2. Click "New Campaign"
3. Select signal to execute
4. Configure parameters:
   • Campaign name
   • Signal parameters
   • Schedule (if recurring)
5. Set status (draft or active)
6. Save campaign

Campaign Scheduling

One-Time Campaigns:

• Execute once at a specific time
• Useful for launches or events

Recurring Campaigns:

• Daily, weekly, or monthly execution
• Cron-style scheduling
• Automatic execution at specified times

// Schedule Examples
{
  type: "one-time",
  execute_at: "2026-02-01T10:00:00Z"
}

{
  type: "recurring",
  cron: "0 9 * * 1", // Every Monday at 9 AM
  timezone: "America/New_York"
}

Campaign Status

Draft: Not yet active, can be edited freely

Active: Running according to schedule

Paused: Temporarily stopped, can be resumed

Completed: Finished execution (one-time campaigns)

Integration Management

ActivePieces Integration

Configure connection to ActivePieces:

1. Set ActivePieces URL in environment variables
2. Add API key for authentication
3. Test connection in Engine Room settings
4. Map flows to signals

External Services

Configure API keys for external services:

• OpenAI: Content generation
• Anthropic: Alternative AI provider
• BannerBear: Visual asset generation
• Social platforms: Publishing integrations

Templates

Signal Templates

Pre-configured signal setups for common use cases:

• Blog Post Generator: AI-powered blog writing
• Social Media Scheduler: Multi-platform posting
• Email Campaign: Newsletter generation
• Ad Creative Generator: Banner and ad creation

Campaign Templates

Pre-configured campaign patterns:

• Weekly Content Batch: Generate week's content
• Daily Social Posts: Automated daily posting
• Monthly Newsletter: Recurring email campaigns
• Event Promotion: Time-bound campaign series

Best Practices

Signal Design

Keep Signals Focused

• One signal = one operation
• Compose multiple signals for complex workflows
• Avoid monolithic signals

Define Clear Schemas

• Explicit input requirements
• Documented output format
• Validation rules

Error Handling

• Graceful failure modes
• Meaningful error messages
• Retry logic where appropriate

Campaign Configuration

Test Before Activating

• Run test executions
• Verify output quality
• Check resource usage

Monitor Performance

• Track execution times
• Monitor success rates
• Review generated content

Iterate and Improve

• Refine parameters based on results
• Update schemas as needs evolve
• Archive unused signals

Security

Access Control

• Role-based permissions for signal/campaign management
• Approval workflows for sensitive operations
• Audit logs for all changes

API Key Management

• Secure storage of credentials
• Rotation policies for keys
• Scoped permissions for integrations

Monitoring and Analytics

Signal Performance

Track signal execution metrics:

• Success rate: Percentage of successful executions
• Average duration: Time to complete
• Error rate: Frequency of failures
• Cost per execution: Resource usage

Campaign Analytics

Monitor campaign effectiveness:

• Execution history: Past runs
• Output quality: Generated content review
• Resource usage: API calls, costs
• ROI metrics: Value generated

Troubleshooting

Signal Execution Fails

Check Integration:

• Verify ActivePieces flow exists
• Ensure flow is published
• Test flow independently

Validate Input:

• Check input matches schema
• Verify required fields present
• Test with minimal valid input

Review Logs:

• Check execution logs
• Look for error messages
• Verify external service status

Campaign Not Running

Check Schedule:

• Verify cron expression is correct
• Confirm timezone settings
• Check if campaign is active

Review Permissions:

• Ensure user has execution rights
• Verify API keys are valid
• Check service quotas

Advanced Features

Signal Composition

Chain multiple signals together:

{
  name: "Content Pipeline",
  steps: [
    { signal: "content-generator", output: "draft" },
    { signal: "content-reviewer", input: "draft", output: "reviewed" },
    { signal: "content-publisher", input: "reviewed" }
  ]
}

Conditional Execution

Execute signals based on conditions:

{
  signal: "content-publisher",
  condition: {
    field: "quality_score",
    operator: ">=",
    value: 0.8
  }
}

Parallel Execution

Run multiple signals simultaneously:

{
  parallel: [
    { signal: "linkedin-post-generator" },
    { signal: "twitter-post-generator" },
    { signal: "facebook-post-generator" }
  ]
}

Future Enhancements

Planned features for Engine Room:

• Visual flow builder for signal composition
• A/B testing for campaign optimization
• Machine learning for parameter tuning
• Marketplace for sharing signals