Set up Activepieces with an AI agent

name: activepieces
description: Use when building AI automation workflows, creating agents that
  handle variable tasks, designing flows with triggers and actions, managing
  data in tables, integrating with 760+ apps, or setting up governance and
  security controls for automation platforms.
metadata:
  mintlify-proj: activepieces
  version: "1.0"

Activepieces Skill

Product Summary

Activepieces is an AI automation platform for building workflows, agents, and data tables with governance built in. Agents handle variable tasks using natural language instructions; flows execute deterministic sequences triggered by schedules, webhooks, or events; tables store structured data for flows and agents to reference. The platform supports 760+ integrations (Slack, Gmail, Google Sheets, Notion, HubSpot, Salesforce, OpenAI, etc.) and runs on your own infrastructure or Activepieces Cloud. Access the full documentation at https://www.activepieces.com/docs. Key entry points: Flows (trigger + actions), Agents (AI workers with tools), Tables (persistent data), MCP Server (connect Claude, Cursor, Copilot, Gemini CLI, Windsurf, Zed), API (REST endpoints for programmatic control).

When to Use

Reach for this skill when:

• Building flows: User asks to automate a sequence (e.g., "send Slack when new Gmail arrives")
• Creating agents: User needs AI to handle variable tasks (e.g., "triage support tickets" where each ticket differs)
• Managing data: User needs to store, query, or trigger on table records
• Integrating apps: User wants to connect services or build multi-step automations
• Setting up governance: Admin needs to control who builds what, which apps are available, where credentials live
• Using MCP: User wants to build flows from Claude, Cursor, or other AI clients
• Debugging runs: User needs to inspect why a flow failed or what data it produced
• Publishing safely: User needs approval gates or versioning for sensitive automations

Quick Reference

Core Concepts

Concept	Purpose	When to Use
Flow	Trigger + sequential actions	Deterministic, repeatable tasks (e.g., "every day at 9am, send report")
Agent	AI that decides which tools to use	Variable tasks (e.g., "handle this support ticket however it needs")
Table	Rows and columns of data	Store leads, invoices, decisions; trigger flows on new records
Piece	Integration with an app (Slack, Gmail, etc.)	Connect to external services; 760+ available
Connection	Authenticated credential for a piece	OAuth2, API key, or basic auth to a service
Trigger	Flow's starting point	Schedule, webhook, event, or new table record
Action	Step that runs after trigger	Call a piece, write to table, branch, run agent, etc.

Flow Building Essentials

• Trigger types: Schedule (cron), Webhook (HTTP POST), Event (piece-specific like "new Gmail"), Table (new/updated record)
• Data passing: Use {{step_name.field}} to reference previous step output; available in Data Selector
• Formulas: Type / in any text input to insert functions (combine, if, coalesce, format_date, etc.)
• Publishing: Draft mode is editable; publish to activate. Sensitive projects require approval.
• Versioning: Published versions are locked; drafts can be edited without affecting live flow

Agent Essentials

• Tools: Any piece action becomes a tool (e.g., "send Slack message", "create Google Sheet row")
• Knowledge: Upload files (PDF, DOCX, TXT, CSV) or link tables for grounding
• Project scope: Agent can only reach connections, flows, and tables in its project
• Structured output: Ask agent for specific fields (category, urgency, needs_human) to branch on in flows

Table Essentials

• Field types: Text, Number, Date, Date & Time, Dropdown (fixed options)
• Triggers: "New record" or "Updated record" can start flows
• In flows: Read records, write records, update records, delete records, clear table
• With agents: Tables become knowledge base for agent lookups and grounding

API & MCP

• Authentication: Bearer token in Authorization header (Platform/Enterprise only for API keys)
• Pagination: Seek-based with limit and cursor query params
• MCP Server: Enable in Settings → MCP Server, copy URL, add to Claude/Cursor/Copilot config
• MCP tools: Discovery (read-only), Flow Management, Flow Building, Router & Branching, Tables, Testing & Runs

Decision Guidance

Flow vs. Agent

Scenario	Use Flow	Use Agent
Logic is known and fixed	✓
Same input always produces same steps	✓
Task varies by situation		✓
Need to branch on prose/judgment		✓
Need deterministic audit trail	✓
Need to handle edge cases flexibly		✓

Trigger Type Selection

Trigger	Use When	Example
Schedule	Recurring at fixed times	Daily report at 9am
Webhook	External system pushes data	Typeform submission arrives
Event	Service-specific event	New Gmail, new Slack message
Table	Data changes in Activepieces	New lead added to table

Data Passing vs. Variables

Approach	Use When
{{step_name.field}}	Reference output from earlier steps in same flow
{{variables['NAME']}}	Store encrypted secrets or config once, reuse across flows
Formulas (combine, if, etc.)	Transform data before using it

Router vs. AI Router

Type	Use When
Conditional Router	Logic is clear and rule-based (e.g., if amount > 1000)
AI Router	Decision is judgment-based (e.g., "is this urgent?")

Workflow

Building a Flow

1. Understand the requirement: What triggers it? What should each step do? Where does data come from?
2. Choose a trigger: Schedule, webhook, event, or table record
3. Add actions: Click + to add steps; search for piece actions (Slack, Gmail, Google Sheets, etc.)
4. Configure each step: Fill in inputs; use Data Selector to reference previous steps
5. Use formulas: Type / to transform data (combine names, format dates, branch on conditions)
6. Test: Run the flow manually to check outputs
7. Publish: Click Publish to activate; sensitive projects require approval
8. Monitor: Go to Runs to inspect execution and debug failures

Creating an Agent

1. Identify the task: What job does the agent do? What varies each time?
2. Click New Agent: Choose project (or it goes to your personal project)
3. Pick a model: Select from available AI providers
4. Write the brief: Plain language description of the job
5. Add tools: Select which piece actions the agent can call
6. Add knowledge (optional): Upload files or link tables for grounding
7. Test: Chat with the agent to verify it understands the task
8. Use in flows: Drop the agent as a step and ask for structured output

Setting Up a Table

1. Create table: Click Tables, then New Table
2. Add fields: Text, Number, Date, Date & Time, or Dropdown
3. Import data (optional): Upload CSV or JSON template
4. Use in flows: Read records, write records, update records
5. Trigger flows: Enable "New record" or "Updated record" trigger
6. Use with agents: Add as knowledge source in agent editor

Connecting via MCP

1. Enable MCP Server: Settings → MCP Server → Toggle on → Copy URL
2. Add to client config: Paste URL into Claude, Cursor, Copilot, etc.
3. Authenticate: First use opens browser for OAuth
4. Build with AI: Ask Claude to create flows, manage tables, test runs

Common Gotchas

• Formulas use semicolons, not commas: combine(first; last; -) not combine(first, last, -)
• Empty strings need quotes: coalesce(""; fallback) not coalesce(; fallback)
• Published flows are locked: Edit in draft mode; publish creates a new version
• Agents are project-scoped: An agent can only reach connections, flows, and tables in its project
• Data Selector is your friend: Don't type {{step_name.field}} manually; use the Data Selector to avoid typos
• Connections are per-project: Two projects with the same Gmail connection name are two different mailboxes
• Tables need pgvector for knowledge: Agents can't use tables as knowledge base without pgvector extension
• Piece versions are pinned: Flows don't auto-upgrade; you upgrade explicitly in the builder
• Sensitive projects require approval: Publishing a flow in a Sensitive project needs review unless you're an admin
• MCP tools cost credits: ap_run_action costs 1 credit per call; flow runs are billed normally
• Secrets are write-only: API responses never contain variable values; only signed-in users can reveal them

Verification Checklist

Before submitting a flow or agent:

• Trigger is correct: Schedule, webhook, event, or table record as intended
• All steps have valid inputs: No red error badges; Data Selector shows available fields
• Formulas are syntactically correct: Preview panel shows expected output, no errors
• Connections are authenticated: No "Missing" or "Error" status in connection list
• Data flows correctly: Test run shows expected output at each step
• Sensitive data is handled: Credentials in variables, not hardcoded; secrets never logged
• Agent has tools and knowledge: If using agent, verify tools are selected and knowledge is available
• Approval gate is ready: If project is Sensitive, ensure approvers are assigned
• Versioning is clear: Published version is stable; draft has new changes
• Run history is clean: No repeated failures; debug any errors before publishing

Resources

• Comprehensive navigation: https://www.activepieces.com/docs/llms.txt — page-by-page reference for all docs
• Building flows: https://www.activepieces.com/docs/flows/building-flows
• Creating agents: https://www.activepieces.com/docs/agents/overview
• API reference: https://www.activepieces.com/docs/endpoints/overview

---

For additional documentation and navigation, see: https://www.activepieces.com/docs/llms.txt