Core Concepts

Core Concepts

This page provides a thorough explanation of every major concept in ThinkFleet. Understanding these building blocks will help you design effective automations and AI workflows.

Flows

A Flow is a directed sequence of steps that executes automatically in response to an event. Flows are the primary unit of automation in ThinkFleet.

Flow Lifecycle

Every flow goes through these states:

State	Description
Draft	Flow is being edited. It will not run automatically.
Published	Flow is live and will execute when triggered.
Disabled	Flow is paused. It will not execute but retains its configuration.

Flow Versions

Each time you publish a flow, ThinkFleet creates a new version. Previous versions are preserved, allowing you to:

• View the history of changes
• Roll back to a previous version if something breaks
• Compare what changed between versions

Flow Runs

A Run is a single execution of a flow. Each run records:

• The trigger data that started it
• The input and output of every step
• The execution duration
• Whether it succeeded or failed

You can inspect runs in the Runs tab to debug issues or verify behavior.

Triggers

A Trigger is the first step of every flow. It defines when the flow runs.

Trigger Types

Webhook Trigger

Fires when an HTTP request is sent to a unique URL. Useful for receiving events from external systems, form submissions, or custom integrations.

POST https://your-instance.thinkfleet.com/api/v1/webhooks/{flowId}

Schedule Trigger

Fires on a recurring schedule using cron expressions or simple intervals.

Every 15 minutes
Every day at 9:00 AM
Custom cron: 0 */2 * * 1-5   (every 2 hours on weekdays)

App Trigger

Fires when a specific event occurs in a connected application. For example:

• Gmail: New email received
• GitHub: New pull request opened
• Slack: New message in a channel
• Stripe: Payment completed

App triggers use either polling (checking periodically for changes) or webhooks (receiving real-time notifications from the app).

Actions

An Action is a step in a flow that performs work. Actions execute sequentially after the trigger fires.

Action Types

Piece Actions

Operations provided by a piece (connector). Examples:

• Send a Slack message
• Create a Jira ticket
• Insert a row in Google Sheets
• Query a database

Code Actions

Run custom JavaScript or TypeScript code for logic that pieces don't cover.

export const code = async (inputs) => {
  const items = inputs.data.filter(item => item.status === 'active');
  return {
    activeCount: items.length,
    items: items,
  };
};

Branch (Condition)

Routes execution down different paths based on conditions:

IF order.total > 100
  → Send VIP notification
ELSE
  → Send standard confirmation

Loop

Iterates over an array and executes child actions for each item:

FOR EACH item IN order.lineItems
  → Create invoice line
  → Update inventory

Data Referencing

Every step's output is available to subsequent steps using the {{stepName.path}} syntax:

{{trigger.body.customerName}}
{{step_1.response.id}}
{{loop.item.email}}

ThinkFleet's autocomplete helps you discover available fields as you type.

Pieces

A Piece is a connector package that integrates ThinkFleet with an external service. Each piece contains:

• Triggers — events from the service
• Actions — operations on the service
• Connection schema — how to authenticate with the service

Piece Categories

Category	Examples
Communication	Slack, Discord, Microsoft Teams, Email (SMTP)
CRM	Salesforce, HubSpot, Pipedrive
Productivity	Google Sheets, Notion, Airtable
Developer Tools	GitHub, GitLab, Jira, Linear
AI & ML	OpenAI, Anthropic, Google AI
Databases	PostgreSQL, MySQL, MongoDB
File Storage	Google Drive, Dropbox, S3
Marketing	Mailchimp, SendGrid, Brevo
Payment	Stripe, PayPal, Square

ThinkFleet ships with 800+ pieces and the library grows continuously.

Custom Pieces

If a piece doesn't exist for your service, you can build a custom piece using the ThinkFleet Piece SDK. Custom pieces have full access to the same APIs as built-in pieces.

Connections

A Connection stores the credentials needed to authenticate with an external service. Connections are reusable across flows and agents.

Authentication Types

Type	Description	Example
OAuth2	Redirect-based authorization	Google, Slack, GitHub
API Key	Static secret key	SendGrid, OpenAI
Basic Auth	Username + password	SMTP, legacy APIs
Custom	Piece-defined schema	Database connection strings

Connection Security

• Credentials are encrypted at rest using AES-256
• The encryption key is configured via AP_ENCRYPTION_KEY
• Connections are scoped to a project — they cannot be accessed across projects
• OAuth2 tokens are automatically refreshed when they expire

Connection References in Flows

When a flow step uses a connection, it references the connection by its external ID:

{{connections['my-slack-connection']}}

This means renaming a connection doesn't break existing flows.

Agents

An Agent is an AI-powered assistant that can converse with users and take actions using tools. Agents use large language models (LLMs) to reason about requests and decide which tools to invoke.

Agent Types

Type	Description
Chatbot	Conversational assistant focused on answering questions. Typically paired with a knowledge base.
Agent	Autonomous agent that can plan, use tools, and take multi-step actions to accomplish goals.

Agent Components

• System Prompt — Instructions that define the agent's personality and behavior
• Tools — Actions the agent can take (flows, pieces, MCP services)
• Knowledge Base — Documents the agent can search for information
• Memory — Per-user conversation history and semantic recall
• Persona — A preset configuration (role, tools, system prompt) for common use cases

How Agent Execution Works

1. User sends a message
2. The agent's LLM processes the message with the system prompt and available tools
3. If the LLM decides to use a tool, ThinkFleet executes it and returns the result
4. The LLM generates a final response incorporating tool results
5. The conversation is stored in memory for future context

Crews

A Crew is a team of agents that collaborate to handle complex, multi-step tasks. Crews enable:

• Task Delegation — A router agent classifies incoming tasks and delegates them to specialized agents
• Kanban Board — Tasks move through stages (To Do → In Progress → Done)
• Specialization — Each agent in the crew has its own tools, knowledge, and persona
• Handoffs — Agents can pass tasks to other agents when the work falls outside their expertise

Example Crew

A customer support crew might include:

Agent	Role	Tools
Router	Classifies incoming tickets	Task classification
Billing Agent	Handles billing questions	Stripe, invoicing flows
Technical Agent	Resolves technical issues	Jira, GitHub, knowledge base
Escalation Agent	Handles VIP or complex cases	All tools + human-in-the-loop

Next Steps

• Create your first flow
• Set up an AI agent
• Browse integrations