AI Agents in Activepieces

Activepieces is AI-first, providing native AI capabilities that let you build intelligent workflows capable of reasoning, decision-making, and multi-step task execution. With support for multiple AI providers and a powerful agent framework, you can create automations that go far beyond simple if-then logic.

What are AI Agents?

AI agents in Activepieces are intelligent automation components that can:

Reason through problems: Analyze situations and determine the best course of action
Use tools: Call other Activepieces actions, APIs, and MCP servers to accomplish tasks
Iterate until complete: Keep working on a task until it’s successfully done
Extract structured data: Parse unstructured text into organized information
Make decisions: Choose different workflow paths based on AI analysis
Generate content: Create text, images, and other media

AI agents can handle complex, multi-step tasks that would traditionally require extensive programming and conditional logic.

AI Piece

Activepieces includes a powerful AI piece with multiple actions:

Text Actions

Ask AI

Generate text using AI models:

{
  type: 'PIECE',
  settings: {
    pieceName: '@activepieces/piece-ai',
    actionName: 'ask_ai',
    input: {
      prompt: 'Summarize this customer feedback: {{trigger.body.feedback}}',
      aiProvider: {
        provider: AIProviderName.OPENAI,
        model: 'gpt-4',
        apiKey: '{{connections.openai}}'
      },
      temperature: 0.7,
      maxTokens: 500
    }
  }
}

Use cases:

Summarize documents
Generate emails and messages
Create product descriptions
Answer questions
Translate text

Summarize Text

Condense long content:

{
  actionName: 'summarize_text',
  input: {
    text: '{{steps.fetch_article.output.content}}',
    maxLength: 200,
    aiProvider: { /* provider config */ }
  }
}

Image Generation

Generate images from text descriptions:

{
  actionName: 'generate_image',
  input: {
    prompt: 'A modern logo for a tech startup',
    aiProvider: {
      provider: AIProviderName.OPENAI,
      model: 'dall-e-3',
      apiKey: '{{connections.openai}}'
    },
    size: '1024x1024',
    quality: 'high'
  }
}

Use cases:

Generate social media images
Create product mockups
Design marketing materials
Visualize concepts

Utility Actions

Classify Text

Categorize text using AI:

{
  actionName: 'classify_text',
  input: {
    text: '{{trigger.body.message}}',
    categories: ['urgent', 'normal', 'low-priority'],
    aiProvider: { /* provider config */ }
  }
}

Use cases:

Triage support tickets
Categorize emails
Route messages to teams
Content moderation

Extract Structured Data

Parse unstructured text into structured JSON:

{
  actionName: 'extract_structured_data',
  input: {
    text: '{{trigger.body.email}}',
    schema: {
      name: 'string',
      email: 'string',
      company: 'string',
      requestType: 'string',
      urgency: 'string'
    },
    aiProvider: { /* provider config */ }
  }
}

Output:

{
  "name": "John Smith",
  "email": "john@example.com",
  "company": "Acme Corp",
  "requestType": "technical_support",
  "urgency": "high"
}

Use cases:

Extract data from emails
Parse invoices and receipts
Process form submissions
Structure customer feedback

Agent Actions

Run Agent

The most powerful AI action - agents that can use tools and reason through complex tasks:

{
  actionName: 'run_agent',
  input: {
    prompt: 'Find all customers who haven\'t been contacted in 30 days and send them a personalized re-engagement email',
    aiProviderModel: {
      provider: AIProviderName.ANTHROPIC,
      model: 'claude-3-5-sonnet-20241022',
      apiKey: '{{connections.anthropic}}'
    },
    agentTools: [
      {
        type: 'PIECE',
        toolName: 'search_database',
        pieceMetadata: {
          pieceName: '@activepieces/piece-postgres',
          actionName: 'execute_query'
        }
      },
      {
        type: 'PIECE',
        toolName: 'send_email',
        pieceMetadata: {
          pieceName: '@activepieces/piece-sendgrid',
          actionName: 'send_email'
        }
      },
      {
        type: 'FLOW',
        toolName: 'generate_email_content',
        externalFlowId: 'email-generator-flow'
      },
      {
        type: 'MCP',
        toolName: 'analyze_customer',
        serverUrl: 'https://mcp.example.com',
        protocol: 'sse'
      }
    ],
    structuredOutput: [
      {
        displayName: 'Customers Contacted',
        type: 'number'
      },
      {
        displayName: 'Emails Sent',
        type: 'number'
      },
      {
        displayName: 'Errors',
        type: 'array'
      }
    ]
  }
}

The agent will:

Understand the task from the prompt
Decide which tools to use and in what order
Query the database for inactive customers
Generate personalized email content for each
Send the emails
Return structured results

AI Providers

Activepieces supports multiple AI providers through the Vercel AI SDK:

Supported Providers

Based on the source code, Activepieces integrates with:

OpenAI: GPT-4, GPT-4 Turbo, GPT-3.5, DALL-E
Anthropic: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku
Google: Gemini Pro, Gemini Pro Vision
Google Vertex AI: Vertex Gemini models
Azure OpenAI: Azure-hosted OpenAI models
Replicate: Open source models
OpenRouter: Access to multiple providers
Custom OpenAI-compatible: Any OpenAI-compatible API

Provider Configuration

// OpenAI
{
  provider: AIProviderName.OPENAI,
  model: 'gpt-4-turbo',
  apiKey: '{{connections.openai_key}}',
  baseURL?: 'https://api.openai.com/v1' // Optional
}

// Anthropic
{
  provider: AIProviderName.ANTHROPIC,
  model: 'claude-3-5-sonnet-20241022',
  apiKey: '{{connections.anthropic_key}}'
}

// Google
{
  provider: AIProviderName.GOOGLE,
  model: 'gemini-pro',
  apiKey: '{{connections.google_ai_key}}'
}

// Azure OpenAI
{
  provider: AIProviderName.AZURE,
  model: 'gpt-4',
  apiKey: '{{connections.azure_key}}',
  resourceName: 'my-azure-resource',
  deployment: 'gpt-4-deployment'
}

// Custom OpenAI-compatible
{
  provider: AIProviderName.OPENAI_COMPATIBLE,
  model: 'llama-3-70b',
  apiKey: '{{connections.custom_api_key}}',
  baseURL: 'https://api.custom-llm.com/v1'
}

Agent Tools

Agents can use various types of tools to accomplish tasks:

Piece Tools

Call any Activepieces piece action:

{
  type: 'PIECE',
  toolName: 'search_customers',
  pieceMetadata: {
    pieceName: '@activepieces/piece-postgres',
    actionName: 'execute_query',
    packageType: 'REGISTRY',
    pieceVersion: '0.25.6',
    actionDisplayName: 'Execute Query'
  }
}

Flow Tools

Execute another flow as a tool:

{
  type: 'FLOW',
  toolName: 'process_order',
  externalFlowId: 'order-processing-flow-123'
}

MCP Tools

Call external MCP servers:

{
  type: 'MCP',
  toolName: 'external_service',
  serverUrl: 'https://mcp.external-service.com',
  protocol: 'sse',
  auth: {
    type: 'bearer',
    token: '{{connections.external_token}}'
  }
}

Building AI Workflows

Example 1: Intelligent Customer Support

// Flow: "AI Customer Support Agent"
{
  trigger: {
    type: 'WEBHOOK',
    settings: { /* webhook config */ }
  },
  actions: [
    // Step 1: Classify the support request
    {
      name: 'classify_request',
      actionName: 'classify_text',
      input: {
        text: '{{trigger.body.message}}',
        categories: ['bug_report', 'feature_request', 'billing', 'technical_support', 'general_inquiry']
      }
    },
    // Step 2: Extract structured information
    {
      name: 'extract_info',
      actionName: 'extract_structured_data',
      input: {
        text: '{{trigger.body.message}}',
        schema: {
          customerName: 'string',
          issueDescription: 'string',
          affectedFeature: 'string',
          urgency: 'string'
        }
      }
    },
    // Step 3: Run agent to handle the request
    {
      name: 'handle_request',
      actionName: 'run_agent',
      input: {
        prompt: `Handle this {{steps.classify_request.output.category}} request:
                Customer: {{steps.extract_info.output.customerName}}
                Issue: {{steps.extract_info.output.issueDescription}}
                
                Search our knowledge base, create a ticket if needed, and draft a response.`,
        agentTools: [
          // Tool to search knowledge base
          {
            type: 'FLOW',
            toolName: 'search_knowledge_base',
            externalFlowId: 'kb-search-flow'
          },
          // Tool to create ticket
          {
            type: 'PIECE',
            toolName: 'create_ticket',
            pieceMetadata: {
              pieceName: '@activepieces/piece-zendesk',
              actionName: 'create_ticket'
            }
          }
        ]
      }
    },
    // Step 4: Send response
    {
      name: 'send_response',
      actionName: 'send_email',
      input: {
        to: '{{trigger.body.email}}',
        subject: 'Re: Your Support Request',
        body: '{{steps.handle_request.output.response}}'
      }
    }
  ]
}

Example 2: Content Generation Pipeline

// Flow: "AI Content Generator"
{
  trigger: {
    type: 'SCHEDULE',
    settings: {
      cronExpression: '0 9 * * 1' // Every Monday at 9 AM
    }
  },
  actions: [
    // Step 1: Agent researches topic
    {
      name: 'research_topic',
      actionName: 'run_agent',
      input: {
        prompt: 'Research the latest trends in {{workflow.topic}} and identify 3 interesting angles for blog posts',
        agentTools: [
          {
            type: 'PIECE',
            toolName: 'web_search',
            pieceMetadata: {
              pieceName: '@activepieces/piece-google',
              actionName: 'search'
            }
          }
        ],
        structuredOutput: [
          {
            displayName: 'Topics',
            type: 'array'
          }
        ]
      }
    },
    // Step 2: Generate content for each topic
    {
      name: 'generate_posts',
      type: 'LOOP',
      settings: {
        items: '{{steps.research_topic.output.topics}}',
        loopActions: [
          {
            actionName: 'ask_ai',
            input: {
              prompt: 'Write a 500-word blog post about: {{loop.item}}',
              temperature: 0.8
            }
          },
          {
            actionName: 'generate_image',
            input: {
              prompt: 'Featured image for blog post: {{loop.item}}'
            }
          }
        ]
      }
    },
    // Step 3: Publish to CMS
    {
      name: 'publish',
      type: 'LOOP',
      settings: {
        items: '{{steps.generate_posts.output}}',
        loopActions: [
          {
            pieceName: '@activepieces/piece-wordpress',
            actionName: 'create_post',
            input: {
              title: '{{loop.item.title}}',
              content: '{{loop.item.content}}',
              featuredImage: '{{loop.item.image}}'
            }
          }
        ]
      }
    }
  ]
}

AI SDK Integration

Activepieces uses the Vercel AI SDK (ai package) for AI operations:

import { streamText, generateText } from 'ai';
import { createAIModel } from './common/ai-sdk';

// Create AI model from provider config
const model = createAIModel({
  provider: AIProviderName.ANTHROPIC,
  model: 'claude-3-5-sonnet-20241022',
  apiKey: apiKey
});

// Generate text
const result = await generateText({
  model,
  prompt: 'What is Activepieces?',
  temperature: 0.7,
  maxTokens: 500
});

// Stream text (for real-time responses)
const stream = await streamText({
  model,
  prompt: 'Write a story...',
  temperature: 0.9
});

Agent Execution Flow

When an agent runs:

Parse prompt: Understand the task and goals
Plan approach: Decide which tools to use
Execute steps: Call tools iteratively
Evaluate results: Check if task is complete
Iterate if needed: Continue until success or max steps
Return output: Provide structured results

From the source code:

interface AgentTask {
  status: AgentTaskStatus;        // RUNNING, COMPLETED, FAILED
  steps: AgentStep[];             // Individual tool calls
  output?: AgentOutput;           // Final structured output
  error?: string;                 // Error if failed
}

enum AgentTaskStatus {
  RUNNING = 'RUNNING',
  COMPLETED = 'COMPLETED',
  FAILED = 'FAILED'
}

Best Practices

Clear Prompts

Write detailed, specific prompts. Include context, constraints, and expected output format.

Structured Output

Define structured output schemas so you can reliably use agent results in subsequent steps.

Limit Tools

Give agents only the tools they need. Too many tools can confuse the AI.

Test Iterations

Test with different prompts and tool combinations to find what works best.

Monitor Costs

AI API calls cost money. Monitor usage and optimize prompts to reduce token consumption.

Fallback Logic

Add error handling and fallback paths for when AI responses don’t meet expectations.

AI + MCP: Powerful Combination

Combine AI agents with MCP servers for ultimate flexibility:

Build flows with AI actions
Expose flows as MCP tools
Use in Claude Desktop/Cursor
AI assistants can call your AI-powered workflows

This creates a powerful cycle where:

AI assistants use your workflows
Your workflows use AI to be intelligent
Everything is connected through MCP

This is the future of automation: AI-powered workflows that are themselves accessible to AI assistants.

Example Use Cases

Smart Email Processing

Classify, extract data, and route emails intelligently based on content and context.

Content Moderation

Analyze user-generated content for policy violations, spam, or inappropriate material.

Customer Analytics

Analyze customer feedback, identify trends, and generate insights automatically.

Document Processing

Extract structured data from invoices, receipts, contracts, and other documents.

Lead Qualification

Analyze leads, enrich data, and route to appropriate sales reps.

Content Creation

Generate blog posts, social media content, and marketing materials at scale.

Smart Routing

Route tickets, messages, and tasks to the right team based on AI analysis.

Data Enrichment

Enhance records with additional information from various sources.

Next Steps

MCP Integration - Connect AI agents to Claude and Cursor
Build Workflows - Learn flow structure and triggers
Create Pieces - Build AI-powered integrations
API Reference - Programmatic access to AI features

Getting Started

Core Concepts

​AI Agents in Activepieces

​What are AI Agents?

​AI Piece

​Text Actions

​Ask AI

​Summarize Text

​Image Generation

​Utility Actions

​Classify Text

​Extract Structured Data

​Agent Actions

​Run Agent

​AI Providers

​Supported Providers

​Provider Configuration

​Agent Tools

​Piece Tools

​Flow Tools

​MCP Tools

​Building AI Workflows

​Example 1: Intelligent Customer Support

​Example 2: Content Generation Pipeline

​AI SDK Integration

​Agent Execution Flow

​Best Practices

Clear Prompts

Structured Output

Limit Tools

Test Iterations

Monitor Costs

Fallback Logic

​AI + MCP: Powerful Combination

​Example Use Cases

Smart Email Processing

Content Moderation

Customer Analytics

Document Processing

Lead Qualification

Content Creation

Smart Routing

Data Enrichment

​Next Steps

AI Agents in Activepieces

What are AI Agents?

AI Piece

Text Actions

Ask AI

Summarize Text

Image Generation

Utility Actions

Classify Text

Extract Structured Data

Agent Actions

Run Agent

AI Providers

Supported Providers

Provider Configuration

Agent Tools

Piece Tools

Flow Tools

MCP Tools

Building AI Workflows

Example 1: Intelligent Customer Support

Example 2: Content Generation Pipeline

AI SDK Integration

Agent Execution Flow

Best Practices

AI + MCP: Powerful Combination

Example Use Cases

Next Steps