---
title: "Flow Agents: Triggers, Variables, Workflow Action and Public API"
description: "Configure Flow Agent start triggers, use custom values and variables, run agents from the Invoke Agent Studio Agent workflow action, and call agents through the Public API."
url: https://help.aesthetixcrm.com/en/articles/2233-flow-agents-triggers-variables-workflow-action-and-public-api
collection: "Agent Studio"
updated: 2026-11-20
language: en
---

# Flow Agents: Triggers, Variables, Workflow Action and Public API

Configure Flow Agent start triggers, use custom values and variables, run agents from the Invoke Agent Studio Agent workflow action, and call agents through the Public API.

Flow Agents are the canvas-built agents in **AI Agents > Agent Studio > Flow Agents**. This guide covers four ways to start and feed an existing flow agent: Start triggers on the canvas, variables and custom values that personalize it, the **Invoke Agent Studio Agent** workflow action, and the Public API for outside software. New agents are created as Managed Agents; existing flow agents keep running and can still be edited here. See Agent Studio Overview: Managed Agents, Flow Agents, Conversational AI and Ask AI for the difference.

> **HIPAA caution:** AI features are not approved for processing Protected Health Information (PHI). Do not put PHI into agent instructions, prompts, files, memory, knowledge, variables, workflow messages, API inputs or test data. Variables such as contact fields and form answers can carry patient details, so only map non-sensitive fields into an agent.

## Flow Agent Triggers

A Flow Agent trigger is an event listener attached to the agent's **Start** node. When a supported event happens, the agent starts immediately with no external API call or manual step. Triggers are optional and additive: agents invoked by API keep working, and a trigger only runs for agents where you add one.

### Trigger types

<table style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p><strong>Trigger</strong></p></th><th colspan="1" rowspan="1"><p><strong>Starts the agent when</strong></p></th><th colspan="1" rowspan="1"><p><strong>Configuration</strong></p></th><th colspan="1" rowspan="1"><p><strong>Data the agent receives</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p><strong>Form submitted</strong></p></td><td colspan="1" rowspan="1"><p>Any selected form is submitted</p></td><td colspan="1" rowspan="1"><p>Choose one or more forms, or click <strong>Add new</strong> to create one</p></td><td colspan="1" rowspan="1"><p>The submitted form fields as variables for later nodes</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Lead tag</strong></p></td><td colspan="1" rowspan="1"><p>A selected tag is added to or removed from a contact</p></td><td colspan="1" rowspan="1"><p><strong>Tag action</strong>: Tag added or Tag removed. Select the specific tag or create one with <strong>Add new</strong></p></td><td colspan="1" rowspan="1"><p>Contact context, including existing tags and custom fields</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Chat message</strong></p></td><td colspan="1" rowspan="1"><p>A new inbound message arrives through connected chat widgets or providers</p></td><td colspan="1" rowspan="1"><p>None. Add the trigger and publish</p></td><td colspan="1" rowspan="1"><p>Message text, sender details and conversation context</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Workflows</strong></p></td><td colspan="1" rowspan="1"><p>A workflow runs the Invoke Agent Studio Agent action</p></td><td colspan="1" rowspan="1"><p>See the workflow action section below</p></td><td colspan="1" rowspan="1"><p>Input variables and the Message from the workflow</p></td></tr></tbody></table>

Typical uses: instant nurture or routing after a consult form, VIP onboarding or re-engagement when a tag changes, instant replies or FAQ deflection for chat, and structured enrichment from a workflow.

### Set up a trigger

1.  In the left sidebar click **AI Agents**, open **Agent Studio**, then click **Flow Agents**.
    
2.  Click the name of an existing agent to open it.
    
3.  On the canvas, use **Add New Node** (or find the starting area of the flow).
    
4.  In the node picker, choose **Start trigger** under **Flow Control**. A trigger tile is added.
    
5.  In the **Select trigger** panel, pick **Form submitted**, **Lead tag**, **Chat message** or **Workflows**.
    
    ![](https://files.us.gleap.ai/pf/g/640067b236b432d4bc3c20bb-Rqfb3L3F88TdIYYCn3qGcW9vPfF2GNpjOGIw9Mn74w3u8WHIRj55XiivYxg6TBMmqPkPSQ78OLA.png?v=1&k=us1&s=api&e=1795348800&sig=dXqip2dUkKXiv9st95qGpMHuOmVgHdvYMJ7DqP3Atk0)
6.  Complete the settings that appear: select forms, choose the tag action and tag, or nothing for chat.
    
7.  Connect the Start trigger to the first node of the flow.
    
8.  **Test** to simulate the selected trigger and see exactly which variables and payload the agent receives. No live contacts are affected.
    
9.  **Save** to store your work as a Staging version. Nothing goes live yet. Save after each configuration step.
    
10.  **Publish** to push the agent and its trigger live so real events start it immediately. Publish only after successful tests. If the agent is mapped to other features such as Ask AI, it generally must be in Production to be selectable.
     

### Notes and limits

-   If you do not see a form or tag in a dropdown, confirm you are in the correct account and that the asset exists, then refresh the builder.
    
-   When bulk-adding tags for testing, use a small test segment first to avoid launching many agent runs at once.
    
-   Chat triggers work with the chat widgets and providers already connected to your account.
    
-   Only Production versions run for live events.
    

## Custom Values and Variables

A variable is a placeholder in double curly braces that is replaced with real data when the agent runs. For example, `Hi {{contact.first_name}}` becomes `Hi John`. You can use variables anywhere you type text in the flow editor: AI Agent prompts, Text Generation nodes, tool inputs, message cards and conditional logic fields. Click the dropdown arrow in a text field to insert one, or type `{{` and pick from the list.

If a variable has no value or its source was deleted, it returns blank. It does not cause an error or stop the agent. Placeholders are case-sensitive, so use the exact key names shown in the variable picker.

### Variable catalog

<table style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p><strong>Category</strong></p></th><th colspan="1" rowspan="1"><p><strong>What it pulls</strong></p></th><th colspan="1" rowspan="1"><p><strong>Example syntax</strong></p></th><th colspan="1" rowspan="1"><p><strong>Notes</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p><strong>Account</strong></p></td><td colspan="1" rowspan="1"><p>Business details from your account settings: business name, phone number, address, website, logo URL</p></td><td colspan="1" rowspan="1"><p><code>Welcome to {{account.name}}. Call us at {{account.primary_phone}}.</code></p></td><td colspan="1" rowspan="1"><p>Updates automatically when settings change</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Custom Values</strong></p></td><td colspan="1" rowspan="1"><p>Reusable key and value pairs you define in <strong>Settings &gt; Custom Values</strong></p></td><td colspan="1" rowspan="1"><p><code>For help, email {{custom_values.support_email}}</code></p></td><td colspan="1" rowspan="1"><p>Change the value once and every agent using it updates</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Right Now</strong></p></td><td colspan="1" rowspan="1"><p>Live date and time: full date, current time, day of week, month, year</p></td><td colspan="1" rowspan="1"><p><code>Today is {{right_now.date}}.</code></p></td><td colspan="1" rowspan="1"><p>Uses your account's timezone</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Form Data</strong></p></td><td colspan="1" rowspan="1"><p>Each field of the submitted form</p></td><td colspan="1" rowspan="1"><p><code>You selected {{form.service_type}}</code></p></td><td colspan="1" rowspan="1"><p>Populates only when the agent was started by a Form submitted trigger</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Contact</strong></p></td><td colspan="1" rowspan="1"><p>Fields from the CRM contact record, including standard and custom contact fields</p></td><td colspan="1" rowspan="1"><p><code>{{contact.first_name}}</code>, <code>{{contact.last_name}}</code>, <code>{{contact.email}}</code></p></td><td colspan="1" rowspan="1"><p>Picks up record changes on the next run</p></td></tr></tbody></table>

Supported sources are these five. Opportunity and task fields are not currently available as variable sources.

### Contact variables vs runtime variables

-   **Contact variables** pull saved CRM data. Use them when the information already exists on the contact before the conversation starts.
    
-   **Runtime variables** hold temporary values collected during the current run, such as the output of an API Call node. Use them when the value is gathered during the conversation. They appear in the variable picker for later steps.
    

### Set up and use variables

1.  **Create custom values.** Go to **Settings > Custom Values**, select **Add Custom Value**, enter a name and value, and click **Create**.
    
2.  Go to **AI Agents > Agent Studio**, open **Flow Agents**, and open or edit an agent.
    
3.  Click inside any prompt or message field, click the dropdown arrow or type `{{`, choose a category and click a variable.
    
    ![](https://files.us.gleap.ai/pf/g/640067b236b432d4bc3c20bb-dc1uZFd12w9jwrshBbjpzUTen2sJBoIf78kakbhPE67yerXRtRw2pSVyi22IStcvifUVMsdHVY9.png?v=1&k=us1&s=api&e=1795348800&sig=lcJj7lu9zv9b0sn2dS6Q49XtpbSWkMEXkqx-xhXoOkU)
4.  Click **Save**, then **Test**, run a sample conversation and confirm the variables resolve. If a value is blank, check that the data exists on the contact or in account settings.
    
    ![](https://files.us.gleap.ai/pf/g/640067b236b432d4bc3c20bb-mgSKNjjuLdIKJL5VSGLun7ipgsXMZsloO1wJfG8z7KcDrmPcVaLPDBqaoz1CqhfLR5J8HCxaCcQ.png?v=1&k=us1&s=api&e=1795348800&sig=t-yXMynBJ1yHBcKhpS6-Dk4ANlJVRdITUrr1Z2BLImU)
5.  Promote the agent to Production when it works.
    
    ![](https://files.us.gleap.ai/pf/g/640067b236b432d4bc3c20bb-GqRFtc8ruczhR9z2XZLtnxcCaJr5vVTXdzHTMjb7wsV9opXocQHTZD6bIJpfoKVOgxUKW91ir30.png?v=1&k=us1&s=api&e=1795348800&sig=dX-DTozgrZ5G_BaNwF3_jzT5UfkxUGOYW3dgHW7l3Dc)

Workflows that use the **AI Agent** action can also update custom values directly with the **Update Custom Value** tool, so values can be written during a run.

## Invoke Agent Studio Agent Workflow Action

**Invoke Agent Studio Agent** is a workflow action under **Marketing > Workflows** that runs a Production agent from inside a workflow, waits for the response and makes it available to later steps. It is useful for summaries, lead qualification, content generation, routing and structured output.

### Prerequisites

-   An AI plan with Agent Studio access on your account.
    
-   The agent is published to **Production**. Draft and Staging versions do not appear in the action's selector.
    
-   The agent was built with the **Workflows** start trigger.
    
-   Permission to edit workflows and AI agents.
    

### Build the agent and add the action

1.  In Agent Studio open the flow agent, set the Start trigger to **Workflows**, and configure its instructions, tools and input variables for the data you will pass in.
    
2.  Test the output format, then click **Publish to Production**.
    
3.  Go to **Marketing > Workflows**, open or create a workflow and click **\+ Add Action**.
    
4.  Under **Agent Studio**, select **Invoke Agent Studio Agent**.
    
    ![](https://files.us.gleap.ai/pf/g/640067b236b432d4bc3c20bb-K1p1ZCpPjfp6d9dZKPbNQafw6hrJOAT8Avnmku4ziMiuFBkCAa05lH13BN3K6r2IRSQJzMggQbd.png?v=1&k=us1&s=api&e=1795348800&sig=T2iEwq9lNrLTGKh0AOLn1QsNqurqWr4ddWuLdmDknng)
5.  Configure the action and click **Save Action**.
    
    ![](https://files.us.gleap.ai/pf/g/640067b236b432d4bc3c20bb-IVjhRhmgk21QmZJ3Cu3UFChKedO4ZUPlm0ostdo3oPsfPAtrp63iGVu6gT6P1CNn6AHONIB36mm.png?v=1&k=us1&s=api&e=1795348800&sig=yaSVSuEso_QdzK8YAFSvPbdApqrHbTS2y_5TCLTdUhU)

### Action settings

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p><strong>Setting</strong></p></th><th colspan="1" rowspan="1"><p><strong>Required</strong></p></th><th colspan="1" rowspan="1"><p><strong>What it does</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p><strong>Action name</strong></p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>A clear label such as "Lead Message Analyzer". Helps when a workflow has several AI steps</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Select Agent</strong></p></td><td colspan="1" rowspan="1"><p>Yes</p></td><td colspan="1" rowspan="1"><p>The Production agent to run. If it is missing, confirm it is in Production, built with the Workflows trigger, and refresh the builder</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Message</strong></p></td><td colspan="1" rowspan="1"><p>Optional, recommended</p></td><td colspan="1" rowspan="1"><p>Free-text instructions for this run. Accepts merge fields, for example "Analyze the most recent message from {{contact.name}} and give a short summary and next actions"</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Input Variables</strong></p></td><td colspan="1" rowspan="1"><p>Required for any required agent inputs</p></td><td colspan="1" rowspan="1"><p>Map workflow values or static text to the agent's named inputs. Missing required inputs can make the action fail</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Store Output As</strong></p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Saves the full agent response as a custom value for later steps</p></td></tr></tbody></table>

### Behavior and limits

-   The agent runs in the background when the workflow reaches the step, and the workflow continues with the result.
    
-   Agents must respond within **60 seconds**.
    
-   If the agent errors, the action fails and the error shows in the workflow log. Handle failures with workflow logic when needed.
    
-   Runs are metered the same as running the agent in Agent Studio, with no separate workflow surcharge.
    
-   You can test in Draft mode; contacts process once the workflow is published.
    
-   You can add several Invoke Agent Studio Agent actions in one workflow, in sequence or separate branches.
    

### Using the output downstream

-   Save a summary or result to a custom field or note.
    
-   Branch with If/Else using values the agent returns.
    
-   Insert the response into email, SMS, WhatsApp or internal notifications.
    
-   Send the full response to a webhook or outside service.
    

Best practices: keep prompts short and pass detail through mapped variables; return plain text when the output goes into a message or note and structured JSON when it drives branching or updates; rename each action clearly; publish agent changes to Production before expecting them in the selector; and review the execution log alongside the Agent Studio test output when mapping fails. Do not map PHI into inputs or the Message.

## Public API

The Public API lets your own software list, read, run and manage Production agents without logging in to Aesthetix CRM. Each request is tied to one account (location) and must carry an OAuth 2.0 bearer token or a Private Integration Token (PIT). Only agents that are **Active** in the **Production** lifecycle stage are reachable. Responses are structured JSON.

### Supported actions

Create Agent, List Agents, Get Agent, Update Agent, Update Agent Metadata, Delete Agent, Promote to Production and Publish, and Execute Agent. Read actions use read-only access; create, update, publish, execute and delete require write access. Scopes and parameters vary by endpoint, so check the current API reference.

### Core endpoints

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p><strong>Action</strong></p></th><th colspan="1" rowspan="1"><p><strong>Request</strong></p></th><th colspan="1" rowspan="1"><p><strong>Details</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p><strong>List Agents</strong></p></td><td colspan="1" rowspan="1"><p><code>GET /agent-studio/public-api/agents</code></p></td><td colspan="1" rowspan="1"><p>Required query parameter <code>locationId</code>. Optional <code>limit</code> and <code>offset</code>. Returns every active agent for the account</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Get Agent</strong></p></td><td colspan="1" rowspan="1"><p><code>GET /agent-studio/public-api/agents/{agentId}</code></p></td><td colspan="1" rowspan="1"><p>Required <code>locationId</code>. Returns name, status, tool nodes, variables, lifecycle stage and more</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Execute Agent</strong></p></td><td colspan="1" rowspan="1"><p><code>POST /agent-studio/public-api/agents/{agentId}/execute</code></p></td><td colspan="1" rowspan="1"><p>Body: <code>{ locationId, input, executionId? }</code>. Returns the full output as one JSON payload</p></td></tr></tbody></table>

For multi-turn conversations, the first Execute call omits `executionId`; the response returns one, and you pass it on later calls to continue the same thread. An `executionId` expires after 30 minutes of inactivity, after which you start a new session.

Some older Agent Studio endpoints remain available but are marked **deprecated**. Build new integrations on the current endpoints, since deprecated ones may be replaced or removed.

### Authentication

-   **OAuth 2.0:** include the access token as `Authorization: Bearer {access_token}`. Exchange an authorization code for a token by calling `POST /oauth/token` with `grant_type=authorization_code`. Store tokens securely and renew them with the standard `refresh_token` grant.
    
-   **Private Integration Token (PIT):** a simpler option for server-to-server calls. Generate it in the developer settings, scope it to your account, and send it in the same Authorization header. A PIT is limited to the account it was created for.
    

### Set up the Public API

1.  Make sure the agents you want to expose are in Production and the account has Agent Studio enabled.
    
2.  Go to **Settings > Developer** (or the developer settings area in your account) and create a Private Integration or OAuth app.
    
3.  Copy the Client ID and Client Secret (OAuth) or the PIT value.
    
4.  For OAuth, exchange the authorization code for an access token and store it securely.
    
5.  Test with List Agents:
    

```javascript
curl -H "Authorization: Bearer {token}" "https://services.leadconnectorhq.com/agent-studio/public-api/agents?locationId={locationId}"
```

6.  Save the `agentId` values you plan to run, then execute an agent:
    

```javascript
curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "locationId":"abc123", "input":{ "prompt":"Write a social post announcing our spring skin-care event"} }' \
  https://services.leadconnectorhq.com/agent-studio/public-api/agents/{agentId}/execute
```

7.  Store the returned `executionId` if you want multi-turn conversations.
    

### Limits

-   **Rate limit:** 300 API requests per minute per account across all Agent Studio endpoints.
    
-   **No streaming:** Execute Agent returns one JSON object after completion.
    
-   **Missing `locationId`:** returns HTTP 400 ("locationId is required").
    
-   Call the API from your backend, not client-side JavaScript, to protect the bearer token.
    

## Frequently Asked Questions

**Can I create a new Flow Agent with a Start trigger?**

No. New agents are created as Managed Agents. Existing flow agents can still be opened, edited and managed from the Flow Agents page.

**Will my existing flow agent triggers keep working?**

Yes. They continue to run normally, and triggers do not change how API-invoked agents run.

**Why is my agent missing from the workflow action dropdown?**

Only Production agents built with the Workflows trigger appear. Confirm the status, publish if needed, then refresh the builder and reopen the action.

**Why is a Form Data variable blank?**

Form variables fill only when the agent was started by a Form submitted trigger. In other cases they return blank.

**Can I use opportunity or task fields as variables?**

Not currently. The supported sources are Account, Custom Values, Right Now, Form Data and Contact.

**What is the timeout for the workflow action?**

The agent must respond within 60 seconds.

**Does running an agent from a workflow cost extra?**

No separate surcharge. It is metered the same as running the agent from Agent Studio.

**Can I stream responses from the Public API?**

Not yet. Execute Agent returns a single JSON object when the run completes.

**Does my agent have to be in Production for the API?**

Yes. Only agents that are Active in the Production stage can be listed, read or executed through the Public API.

**Can I pass patient details into variables, messages or API inputs?**

No. AI features are not approved for PHI. Map only non-sensitive fields and use generic test data.
