Introducing a new way to review your PRs.

Read the announcement

twentyhq / twenty

The open alternative to Salesforce, designed for AI.

View on GitHub

22 documents · Updated Nov 20, 2026

docs / automation-and-ai

Automation and AI capabilities

Automation and AI capabilities help each workspace turn business events into repeatable work and assisted decisions. Workflows coordinate data actions, logic functions, and AI agents. Installed applications extend these capabilities with workspace data, access rules, external connections, and user-facing features.

Capability model

The platform joins four capability groups. A workflow coordinates a business process. A logic function runs controlled server work. An AI agent uses a language model and permitted tools to produce an answer or take an action. An installed application packages these capabilities for a workspace.

CapabilityPurposeRelationship
WorkflowsStart and coordinate repeatable processesUse data actions, logic functions, and AI agents
Logic functionsRun custom work for a workflow or direct eventUse workspace context and application services
AI featuresHelp users and workflows understand data and act on itUse models, context, tools, approvals, and usage limits
Installed applicationsAdd data, behavior, access rules, connections, and user-facing featuresSupply functions, agents, workflows, providers, and UI parts

The shared workflow model lets one process combine fixed rules with custom code and model output. This keeps record updates, branching, waits, messages, external calls, logic functions, and AI agents in one automation path. See Workflow execution for the run path and AI applications for the deeper AI and application model.

Workflow automation

Workflows respond to a manual action, a webhook, a record event, a schedule, or another incoming request. Each step can pass its result to later steps, so a workflow can carry workspace data through a full business process.

Workflow lifecycle

The workflow lifecycle moves a connected draft through validation and activation before it can receive events. The same release boundary applies when an authorized AI tool creates or changes a workflow.

  1. A draft defines one trigger and a connected set of steps.
  2. The platform resolves record, field, account, function, and agent references.
  3. Validation checks the graph, settings, data paths, and required application access.
  4. Activation publishes one usable version for dispatch.
  5. A manual action, webhook, record event, or schedule starts a durable run.

This diagram shows how a workflow becomes live automation.

flowchart LR
    A[Draft trigger and steps] --> B[Connected workflow graph]
    B --> C[Reference and output checks]
    C --> D[Published active version]
    D --> E[Event dispatch]
    E --> F[Durable workflow run]

Workflow definitions use universal identifiers so an application can refer to the same objects, fields, roles, functions, and agents in different workspaces. A workflow can be visible to the workspace or private to its creator. Application-owned workflows are changed through application synchronization rather than direct workspace edits. A changed application definition produces a new published version when needed. Existing runs keep the definition that they started with.

References: packages/…/workflow.entity.ts• L42-88 packages/…/workflow-version.entity.ts• L24-105 packages/…/core-workflow-lifecycle.workspace-service.ts• L130-305 packages/…/core-workflow-access.service.ts• L32-65

Workflow visibility

Workflow visibility controls which members can discover and use a workflow. Workspace-visible workflows are available to workspace members. Private workflows are available only to their creator, and the same rule protects their versions and steps.

Application boundaries add a second check. An application can start only workflows that its access rules reach, while application-managed workflows remain read-only to direct member edits.

References: packages/…/is-core-workflow-visible-to-user.util.ts• L1-14 packages/…/build-core-workflow-visibility-where.util.ts• L1-18 packages/…/core-workflow-access.service.ts• L67-195 packages/…/core-workflow-mutation.workspace-service.ts• L368-456

Workflow triggers

Triggers convert an external event into workflow work. The main trigger types are manual actions, schedules, record events, and webhooks.

Record-event triggers can name an object, action, watched fields, a condition, and batch behavior. The platform resolves these references before dispatch and only admits data that the workflow or its application may read. This keeps a trigger from exposing records merely because the event exists.

A webhook starts work only when the target workspace exists and the workflow has an active published version with a webhook trigger. The endpoint returns the resulting run identity after dispatch.

References: packages/…/workflow-trigger.controller.ts• L50-159 packages/…/core-workflow-lifecycle.workspace-service.ts• L553-594 packages/…/from-workflow-trigger-manifest-to-trigger-or-throw.util.ts• L154-263 packages/…/call-database-event-trigger-jobs.job.ts• L53-124

Workflow runs

A workflow run is the durable record of one process attempt. The runner queues the work with its workspace and application scope, then uses step results to choose the next actions. When a member starts a run in the web client, the client creates an optimistic run record, listens for live run updates, sends the run request, and opens the run record for review.

Before a step runs, the platform restores a workspace execution context. This context carries the owning application, workflow identity, initiator, and permissions. A manual run can act for its member; another run acts for the application. The platform checks that a usable role and application boundary remain available.

Branches and iterators select later steps. A form, event, tool approval, or AI question can pause the run. The platform stores the pause before it waits, then resumes the same run after the matching answer or event. Queue limits, usage admission, retries, stale-run handling, and cleanup keep admission and recovery bounded.

Read Workflow execution for queue behavior, step state, waits, retries, permissions, and function execution.

References: packages/…/workflow-execution-context.service.ts• L41-168 packages/…/workflow-execution-context.type.ts• L6-13 packages/…/workflow-executor.workspace-service.ts• L87-309 packages/…/workflow-executor.workspace-service.ts• L463-543 packages/…/useRunWorkflowVersion.tsx• L70-166

Logic functions

Logic functions give applications a controlled way to run custom server work. A workflow can call a function as an action. A direct route, schedule, database event, application lifecycle hook, health check, or application tool can also call it.

Execution boundary

All entry paths use one workspace-aware execution boundary. The platform resolves the function and its application, checks application state and usage limits, then runs the function with the correct application and delegated member context.

Database events are matched to active functions by event name. Readable events are filtered before the function is queued. Conditions and watched fields then reduce the event to the payload that the function receives. Batch mode groups events only when they share one authorization context.

References: packages/…/call-database-event-trigger-jobs.job.ts• L59-185 packages/…/find-logic-functions-triggered-by-event-name.ts• L6-31 packages/…/transform-event-batch-to-event-payloads.ts• L20-123

Workflow code steps

Workflow code steps let a workflow run custom code with its current application and user context. New steps can carry source directly. Older steps can still refer to a stored function, so the platform keeps both forms usable for existing runs.

The step resolves only its input against workflow data. The source or stored function remains inside the owning application boundary. Build errors become step errors and the run keeps a log that can be inspected later.

References: packages/…/code.workflow-action.ts• L41-177 packages/…/code-step-runner.service.ts• L33-135

AI assistance

AI features let a user ask questions about workspace data or let a workflow ask an agent to work on data from earlier steps. An agent combines a persona, a selected model, workspace context, a response shape, and permitted tools. Permissions, approvals, pauses, credits, and usage records keep this work bounded and visible.

AI chat and agents

AI chat is a conversation surface for workspace context, files, records, skills, model choice, and tool actions. It supports shared channels and private direct messages. A thread can link to records, quoted messages, and participants. The member can see streamed work while retaining control of actions.

The chat client sends a message with its relevant context and shows an optimistic local message while the server queues or streams the response. The durable agent run can start from chat, a workflow, an application API call, or a record trigger. It returns text or structured output, or it pauses for a question or approval. A continued run rebuilds the current caller and application context instead of trusting old permissions.

Agent runs can act as their owning application or as a selected workspace member. The actor context carries the current member roles and workspace permissions, so a continuation does not keep stale access from the earlier turn.

References: packages/…/useAiChat.ts• L97-367 packages/…/AiChatStreamSubscriptionEffect.tsx• L18-88 packages/…/agent-runner.service.ts• L169-247 packages/…/agent-actor-context.service.ts• L62-221 packages/…/agent-chat-channel-access.service.ts• L25-65

Chat channels and sharing

Chat channels group agent conversations for a workspace. Access requires the AI permission and a role that is listed on the channel, or a role with access to all agent chat channels. Thread record sharing then controls who can read or reply to a specific conversation.

When a channel changes, its grants are rebuilt. When a channel is removed, its threads move to another valid channel before deletion so the conversations keep a readable home.

References: packages/…/is-agent-chat-channel-open-to-roles.util.ts• L1-14 packages/…/agent-chat-channel.service.ts• L61-204 packages/…/agent-chat-sharing.service.ts• L167-215 packages/…/agent-chat-sharing.service.ts• L785-831

Agent definitions

An agent definition sets the agent's prompt, model, response format, active state, and optional triggers. It can also target a role, which gives the agent a defined access boundary when it acts for an application or workflow.

Application ownership controls which parts of an agent can be changed. A workspace can update allowed properties, but it cannot rename an agent owned by another application.

References: packages/…/from-create-agent-input-to-flat-agent.util.ts• L24-107 packages/…/from-update-agent-input-to-flat-agent-to-update.util.ts• L129-230 packages/…/is-workflow-related-object.util.ts• L1-17

Agent workflow steps

An AI agent workflow step asks a model to work from the current workflow context. It can use permitted workspace tools and return named output fields for later steps. Named fields give later steps a stable shape instead of requiring them to parse free text.

If the agent asks a question or proposes a tool action, the step becomes pending and the workflow waits. The agent run carries its persona, application boundary, object scope, and field scope through the pause and resume cycle. A workflow agent uses the run's current permissions when it resumes.

References: packages/…/ai-agent.workflow-action.ts• L48-187 packages/…/build-workflow-agent-run-execution-context.util.ts• L7-21 packages/…/agent-actor-context.service.ts• L100-221 packages/…/is-workflow-related-object.util.ts• L6-17

AI tool approvals

AI actions that can change workspace data or send a message use a human approval boundary. The member reviews the proposed target and inputs before the action is accepted. The approval result becomes part of the agent or workflow outcome.

The proposal records the target and the fields that may change. Approval can edit only those proposed fields. The system re-reads a proposed record before an update and refuses the action if the record changed. It fixes the proposed email account and record target so approval cannot silently retarget the side effect. If the proposal cannot be read back, approval does not run it.

Record changes can be reviewed as grouped create, update, or delete proposals. The member can approve selected records or reject a group. The response is sent to the conversation that started the proposal, even if the member has opened another thread.

This boundary is important for email, record changes, and publication of an AI-built component. It separates an agent's suggestion from a side effect in the workspace.

References: packages/…/propose-tool-call.pausing-tool.ts• L65-157 packages/…/propose-tool-call.pausing-tool.ts• L240-347 packages/…/build-email-proposal.util.ts• L12-41 packages/…/AiChatRecordApprovalDeck.tsx• L37-87 packages/…/AiChatToolCallApprovalCard.tsx• L10-41

AI component builder

The AI component builder lets a member ask chat to create a workspace widget for a dashboard or record page. The agent creates a temporary preview with sample data. The member can inspect the result and browser errors before approving one exact revision for publication.

The saved component uses the normal application data access and permissions. Publication makes it available to the widget picker. It does not place the widget automatically.

References: packages/…/ai-front-component-tool.service.ts• L28-66 packages/…/publish-front-component.tool.ts• L8-37 packages/…/ui-documentation.json• L1 packages/…/AiChatFrontComponentPreviewContent.tsx• L35-90

Model use and limits

Chat and agents choose language models by speed, capability, and cost. The model catalog spans several providers and records context size, output limits, supported input types, reasoning support, effort choices, price, and measured performance. A member can select a model tier. If no tier is selected, the server can use the workspace chat tier.

Credit limits can stop a model step or cause a safe fallback. The user-facing result distinguishes provider setup problems, context limits, connection loss, and allowance limits.

References: packages/…/ai-models.json• L1-30 packages/…/ai-providers.json• L1-32 packages/…/ai-model-benchmarks.json• L1-31 packages/…/useAiChatModelId.ts• L8-26 packages/…/AiModelPicker.tsx• L25-63 packages/…/agent-step-loop.service.ts• L183-215 packages/…/AiChatErrorRenderer.tsx• L18-51

Installed applications

An installed application is a workspace-level package that binds data, behavior, access rules, external connections, and user-facing features into the product. It can supply objects and fields, roles, functions, workflows, agents, skills, providers, tools, widgets, and validation rules.

Application manifest

The manifest is the shared contract for an application. It gives the platform stable universal identifiers for application entities, plus the relationships needed to install and sync them into a workspace.

The manifest can describe:

  • Data objects, fields, indexes, views, and page layouts.
  • Roles, permissions, row rules, and validation rules.
  • Logic functions, workflows, agents, skills, and event triggers.
  • Connection and messaging providers, MCP servers, and application variables.
  • Front components, navigation, command, settings, and timeline features.

The platform converts the manifest into a workspace change plan. It validates references and dependencies before applying the plan. A pre-install function can prepare an application before the full metadata sync. A failed plan does not silently leave a partially valid application definition.

References: packages/…/compute-application-manifest-all-universal-flat-entity-maps.service.ts• L72-87 packages/…/application-manifest-migration.service.ts• L46-179 packages/…/manifestType.ts• L40-68

Application workflows

Applications can package workflows as part of the same contract as their data and functions. A manifest workflow must have a name, one supported trigger, and steps that resolve to valid workspace references.

Supported application workflow triggers include manual actions, schedules, record events, and webhooks. Step definitions can call functions and agents, change or find records, collect form input, apply conditions, send messages, and create calendar events. The manifest keeps these definitions portable while the workspace resolves local IDs and connected accounts during sync.

References: packages/…/from-workflow-manifest-to-universal-flat-workflow-or-throw.util.ts• L78-126 packages/…/from-workflow-step-manifest-to-action-or-throw.util.ts• L15-238 packages/…/from-workflow-trigger-manifest-to-trigger-or-throw.util.ts• L239-263

Application roles and authorization

Applications do not receive workspace access by implication. An application can declare a default role. The workspace then creates or updates a grant role that copies the requested access into the application's boundary.

User consent is tracked separately from the application's role. Authorization records identify the user, workspace, application, scopes, and revocation state. Token refresh checks that record, the user's current workspace membership, and the issuing application before it renews access.

References: packages/…/application-grant-role.service.ts• L31-122 packages/…/application-grant-role-lookup.service.ts• L57-117 packages/…/application-authorization.service.ts• L16-168 packages/…/oauth.service.ts• L360-445

Application connections

Connection providers let an application connect a workspace to an external service. The provider owns the authorization flow and can use application functions to identify an account and run connect or disconnect work.

The platform supports three provider forms:

ProviderPurpose
OAuthUses client details declared by the application
OAuth discoveryFinds and stores a provider client for a workspace
CustomLets application code own the authorization and callback exchange

The authorization flow carries workspace and user context through a short-lived state. OAuth flows also bind the browser that started sign-in and can use PKCE. The callback verifies that state, exchanges the code, identifies the external account, and stores the connected account inside the application boundary.

References: packages/…/connectionProviderManifestType.ts• L7-25 packages/…/connection-provider-oauth-flow.service.ts• L58-218 packages/…/connection-provider-custom-flow.service.ts• L45-184 packages/…/connection-provider-oauth-client.service.ts• L22-71

Application event triggers

Applications can react to record events through logic functions, workflows, and agents. A manifest names the object, action, watched fields, condition, and optional batch mode. The sync process resolves these references against the workspace before the trigger can run.

Event delivery filters unreadable records and fields, skips inactive applications, and applies application queue limits. Batch delivery groups events by the user context that caused them, so one function job does not mix different authorization identities.

References: packages/…/agentTriggerType.ts• L10-48 packages/…/resolve-database-event-trigger-manifest-settings-or-throw.util.ts• L1-120 packages/…/call-database-event-trigger-jobs.job.ts• L84-209

Application health and user surfaces

An application can expose a health check through a logic function. The platform turns the result into a small status with an optional explanation and repair action. Missing functions, execution errors, and invalid results become an unknown status.

Applications can also expose front components, inbox actions, MCP servers, navigation, and settings surfaces. These features use the application's normal data access and reviewed permissions. AI chat can preview and publish a front component, but publication still follows the application boundary.

References: packages/…/application-health-check.service.ts• L35-157 packages/…/define-mcp-server.ts• L8-44 packages/…/application-iframe-media-permission.service.ts• L31-107

Capability relationships

The product path is composable. An installed application supplies workspace-aware functions, agents, data, providers, rules, tools, and UI. A workflow chooses when to call those features. AI can use workspace context and permitted tools during a user chat or workflow run.

Starting pointUsesProduces
Record, schedule, user, or request eventWorkflow trigger and connected stepsA business process with a run record
Workflow step or direct eventLogic functionCustom data, a side effect, or an error
User chat, workflow AI step, or application API callAgent persona, model, tools, permissions, and workspace contextText, structured output, a paused run, or a tool action
AI component requestDraft preview, sample data, browser feedback, and approvalA saved workspace widget
Installed applicationMetadata, functions, agents, providers, rules, tools, and UIA workspace extension

The child pages separate the two deep paths: Workflow execution covers queue-backed automation and function runs. AI applications covers chat, agents, tools, approvals, and application boundaries.

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to application manifests must keep universal identifiers and all cross-entity references aligned across sync, workflow conversion, roles, providers, and application settings.
  • Changes to record-event trigger contracts must keep object lookup, watched fields, conditions, action names, batch mode, and legacy event forms aligned for workflows, functions, and agents.
  • Changes to workflow visibility must keep member lookup, version access, application reachability, creator ownership, and both ORM and raw-query predicates aligned.
  • Changes to workflow lifecycle must preserve one active published version, stale-edit detection, activation locks, manual command entries, schedule entries, and automated-trigger cache invalidation.
  • Changes to workflow conversion must preserve the one-trigger contract, supported step types, local reference resolution, output schemas, active-version identity, and reproducibility checks.
  • Changes to workflow execution context must preserve the owning application, initiator, delegated member identity, role checks, and the permissions used again after an AI pause.
  • Changes to manual workflow run handling must keep the optimistic run record, live update subscription, run mutation input, and run detail view aligned.
  • Changes to workflow side-effect actions must preserve workflow input resolution, actor context, connected-account selection, and the action's required account capability.
  • Changes to AI agent definitions must keep application ownership, editable properties, role targets, workflow-related object rules, and universal identifiers aligned.
  • Changes to AI approval proposals must keep fixed targets, proposed-field limits, record conflict checks, email account binding, unreadable-proposal handling, and exact component revisions aligned.
  • Changes to AI chat channels or thread sharing must preserve AI permission checks, role grants, record sharing, channel migration, and thread access.
  • Changes to AI model catalogs must keep provider credentials, model identifiers, supported inputs, effort options, cost data, benchmark data, and deprecated-model handling aligned.

Important failure modes

TriggerConsequenceGuard
A manifest has an unknown object, field, role, function, agent, or connected account referenceInstallation or workflow publication stopsUniversal-identifier resolvers validate references before the workspace plan runs
A workflow definition has no name, more than one trigger, or an unsupported stepThe application workflow cannot be reproduced or publishedManifest conversion and schema validation reject the definition
A record-event trigger watches an invalid field or uses a condition without a readable objectThe trigger is rejected or no function job is createdTrigger lookup and watched-field resolution validate the object and field contract
An event contains records outside an application's read scopeAutomation could act on data that the application cannot readReadable-event filtering runs before trigger payloads enter the queue
A private workflow is requested by another member or an unreachable applicationThe workflow appears missing or the start is refusedVisibility checks and application reachability checks run before access or dispatch
A workflow webhook has no active published webhook versionThe request cannot start a runThe webhook controller checks workspace, published version, trigger type, and active status
A workflow version changes during an edit or activationThe change is rejected and the caller must reloadExpected-content checks and workflow lifecycle locks serialize writes
A workflow run has no usable role or its target belongs to another applicationThe step is refusedThe execution context and application step permission checks validate the run before execution
A workflow step exceeds usage limits or cannot be queued for retryThe step is refused or the run can failUsage admission, durable step state, and retry enqueue handling settle the result
An application grant role is missing or cannot be rebuiltThe application has no intended workspace accessGrant-role lookup, migration validation, and application ownership checks guard the role
A user revokes application access or loses workspace membershipRefresh and introspection reject the user tokenAuthorization coverage and current membership checks run before renewal
An OAuth callback has stale state, the wrong browser, or a changed clientThe connection is not completedExpiring state, browser nonce checks, client re-resolution, and PKCE checks stop the callback
OAuth discovery stores a rejected or unusable clientLater sign-in can fail with an invalid clientRedirect, metadata, client usability, and invalid-client recovery checks control stored clients
A connection callback is repeated for the same external accountThe account can be duplicated or overwrittenCallback state age checks and a workspace lock make persistence repeat-safe
A logic-function event exceeds application queue limitsThe event is skipped and recorded as throttledApplication enqueue throttling and repeated-event logs make the loss visible
A member lacks AI permission or a channel roleThe chat channel or thread is hiddenAI permission, channel role, and record-sharing checks run before access
An AI tool proposal changes an unproposed field, target, account, or stale recordThe side effect is not runApproval schemas, fixed targets, record re-read checks, and exact revision checks keep proposals bounded
An approved proposal cannot be read back or an email is invalidThe agent reports failure without running the side effectProposal parsing and email input validation fail closed
AI or workflow work exceeds credits, loses its stream, or waits foreverThe run stops without a final resultCredit checks, stream recovery, durable pause state, and continuation limits settle the run

Key files

FileWhy to read it
packages/…/workflow.entity.tsShows workflow identity, visibility, ownership, and published-version pointers.
packages/…/workflow-version.entity.tsShows the version states and the one-active-version contract.
packages/…/core-workflow-access.service.tsShows member visibility and application reachability checks.
packages/…/core-workflow-lifecycle.workspace-service.tsShows validation, activation, deactivation, schedule updates, and manual trigger updates.
packages/…/core-workflow-version-write.service.tsShows safe draft writes and automated-trigger cache updates.
packages/…/workflow-trigger.controller.tsShows the public webhook contract and active-version checks.
packages/…/useRunWorkflowVersion.tsxShows the web client path for optimistic manual runs, live updates, and opening the run record.
packages/…/call-database-event-trigger-jobs.job.tsShows readable-event admission, throttling, and function job creation.
packages/…/agent-runner.service.tsShows the durable agent turn, pause, continuation, and outcome flow.
packages/…/agent-actor-context.service.tsShows application and workspace-member actor contexts for agent runs.
packages/…/propose-tool-call.pausing-tool.tsShows the approval contract, fixed targets, conflict checks, and fail-closed outcomes.
packages/…/agent-chat-channel-access.service.tsShows role-based channel access.
packages/…/agent-chat-sharing.service.tsShows thread record access and member sharing checks.
packages/…/ai-models.jsonShows the model catalog and the limits used for model selection.
packages/…/ai-providers.jsonShows provider credentials and provider-specific model entries.
packages/…/application-manifest-migration.service.tsShows how an application manifest becomes a validated workspace change plan.
packages/…/compute-application-manifest-all-universal-flat-entity-maps.service.tsShows the broad application contract for data, workflows, functions, agents, providers, permissions, and UI.
packages/…/application-grant-role.service.tsShows how an application's requested role becomes a workspace grant role.
packages/…/application-authorization.service.tsShows the durable user consent and revocation boundary for application access.
packages/…/connection-provider-oauth-flow.service.tsShows the external account sign-in and callback flow.
docs/workflow-execution.mdProvides the detailed workflow queue, execution, and function guide.
docs/ai-applications.mdProvides the detailed chat, agent, tool, approval, and application guide.