Flow triggers and nodes

Triggers

Drag a trigger from the palette onto the canvas, or start from a template that already has one. A trigger fires the published version of the flow; edits to the draft do not change what fires until you publish again.

Schedule

Type a cron expression or plain words such as every weekday at 9; the inspector shows the next three firings so you can check it. The time zone is an IANA name, UTC when you leave it empty. Your plan sets the shortest interval a schedule may use; a schedule tighter than that is a readiness problem and blocks publishing. If the platform was down when a firing was due, the missed-run policy decides whether it is skipped (the default) or run once on recovery.

Webhook

Each webhook trigger gets its own URL, /api/flows/hooks/<triggerId>, and a secret you rotate from the inspector; the secret is shown once, and only its last characters stay visible afterwards. Every request must be signed:

POST /api/flows/hooks/<triggerId>
Content-Type: application/json
x-akili-signature: t=1760250000,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

{ "customer": "cus_123", "amount": 4900 }

• t must be within 300 seconds of the server clock, and a signature seen again within 600 seconds answers 409, so a replayed request never starts a second run.
• A valid request answers 202 with the run id. Send an Idempotency-Key header to make a retried delivery return the first run instead of starting another.
• The payload reaches your steps as trigger.body, trigger.headers and trigger.receivedAt. Add a field map (for example customer → body.data.customer_id) to expose only the names you need as trigger.customer.
• Press Listen to open a ten-minute window: the next signed request is stored as the trigger's sample and does not start a run, and the sample feeds step tests.

Event

Pick one platform event; an optional filter expression over trigger.* skips firings that do not match. The events available today:

• message.completed
• credit.threshold
• spend_cap.warning
• webchat.spend_cap.warning
• flow.run.completed
• flow.run.failed
• knowledge.document.indexed
• stripe.checkout.completed
• stripe.subscription.updated
• stripe.subscription.deleted
• stripe.invoice.payment_failed
• slack.message
• social.post.metrics_updated
• rss.item

For rss.item you also give a feed URL; a poller checks it every 15 minutes. Events the catalog lists as not yet available show as such in the palette and are a readiness problem if a draft uses them.

Agent

An agent trigger turns the flow into a chat tool. Give it a snake_case tool name (reserved and already-taken names are refused at publish), a description the agent reads to decide when to call it, and the agents that may call it (up to 50). The tool waits inline for up to 60 seconds; a run that takes longer answers with its run id, and the agent can read the result later with the shared flow_status tool. A flow started this way shows its run summary and any approval card in the chat that started it.

Manual

Define the flow's inputs as a JSON Schema and the Run bar builds a form from it. A manual run is attributed to the person who started it, which is what lets steps use your personal connections. API keys with the flows:run scope start manual runs through POST /flows/:id/runs, 60 per minute.

Nodes

The palette lists every node with a readiness state for you: ready, needs a connection, not in your plan, not granted to you, or not available in this deployment. Every node can set a timeout and retries (0 to 5 extra attempts, fixed or exponential backoff), and every node has a failure handle you can wire to an error branch.

Agents and tools

App actions

app.action is one node with a connector, an action and the action's parameters. The launch actions:

An app action runs as the flow owner (your own connection, manual runs only) or as an agent that holds a connection for that app. Readiness checks that the connection exists, belongs to the agent, is for the right app and was granted the scopes the action needs. Other Microsoft 365 and Dataverse actions go through mcp.call for now.

Content and messaging

Logic and other flows

A condition's edges are yes and no; a loop's are each and done; an approval's are its four outcomes. An outcome with no edge is a readiness problem, because the run would fail the moment it was taken.

Pass data between steps

Any text field in a node accepts {{ path }} tokens, resolved when the step runs. The path starts from one of five roots:

• trigger — what started the run: the webhook body and headers, the event payload, or the agent's arguments. With no payload it is the trigger kind and the time it fired.
• inputs — the manual run form, or the input a parent flow passed in.
• steps.<id> — an earlier step's output, status and credits. Node ids are letters, digits, underscores and hyphens; rename a node and its id stays.
• run and env — the run's own metadata and the values the platform exposes.

Summarise this for {{ trigger.body.customer }}: {{ steps.fetch.output | json }}
Due {{ steps.plan.output.dueDate | date }} — {{ steps.tags.output | join }}
{{ inputs.channel | default }}

Four filters follow a pipe: json serializes an object, date formats an instant, default substitutes a fallback and join flattens an array. A field that is exactly one token keeps the value's type, so an array or an object passes through intact rather than as text. A step's output above 1 MB fails the step rather than being truncated.

Runs-as: whose identity a step uses

Agent turns, skills, tool calls, MCP calls and app actions have a Runs as field in the inspector with three tiers:

• Owner (the default) — the flow owner's credentials and connections. Fine for manual runs; for unattended triggers it only works where the workspace, not you personally, provides the credential.
• Agent — the agent's own credential, granted to it in the agent builder. This is what makes a scheduled, webhook or event-driven flow able to send mail or post to Slack.
• Workspace — a workspace-level credential. App actions have no workspace connections yet, so readiness refuses that combination.

A tool call with no runs-as inherits the run's, so a tool step in an agent-triggered run keeps running as the agent. When no credential of the chosen tier can serve a step unattended, the inspector shows a readiness problem that names the tool, the tier and the reason, and publishing is refused until you fix it.

Good to know

• A step that no trigger reaches. Readiness flags it, because it would be skipped on every run. Wire it in or delete it.
• Default instructions left on an agent step. An advisory reminds you the step still carries the palette's placeholder; it does not block publishing.
• Loops and credits. A loop runs its branch once per item, so a credit cap on the step inside the loop, not on the flow, is what bounds the spend.
• Tools that only the owner can own. Image generation and canvas tools run as the owner only, because an agent or the workspace cannot own the file they produce.
• Reading the other pages. Flows covers the builder, publishing and limits; Runs and approvals covers what happens after a trigger fires.