Python and FlowRunner

TL;DR

• Python is where your automation logic lives: the script, the service, the model call, the algorithm you wrote. FlowRunner is what you add around it: triggers from 2,100+ integrations, approval steps that wait days for a person on email, Slack, WhatsApp, phone, or a Form, retries, schedules, and a record of every run that the rest of the team can read.
• Your Python stays where it runs today. FlowRunner runs JavaScript, not Python, so it calls your code over HTTP or MCP, and your code calls FlowRunner through the Call Flow API.
• The split that works: Python does the parts only code can do. FlowRunner does the plumbing you’d otherwise rebuild next to every script.
• For a one-off script or a research notebook, Python on its own is enough, and this page says so below.

What Python is for

Python is the language most automation scripts and AI agents are written in. It’s open source, free under the Python Software Foundation License, and it has a library for nearly anything you need to parse, compute, or call. If the job is data work, a model, or an algorithm of your own, Python is the right place for it, and nothing on this page argues otherwise.

The language has no opinion about when a script runs, what happens when a call fails, or who gets told. That comes from the runtime you pick, and most teams pick one of these:

• cron or a systemd timer on a server. Time-based runs and nothing else. Retries, history, and alerts are whatever the script writes.
• GitHub Actions schedule. Cron inside CI, with run logs. GitHub’s docs say the shortest interval is once every 5 minutes, scheduled runs can be delayed under high load, and in a public repository they’re disabled after 60 days without activity.
• Apache Airflow. Workflows “defined entirely in Python,” built for batch workflows with a clear start and end. You host the scheduler, workers, and metadata database, or buy a managed version.
• AWS Lambda. Event-driven functions billed per use. A standard function times out at 15 minutes at most. Lambda durable functions go further: they checkpoint and replay, retry steps, wait for a time period or an external callback, and an execution can run up to a year.
• A FastAPI or Flask service. HTTP endpoints, so other systems can call your Python. FastAPI’s own docs suggest BackgroundTasks for small jobs and a queue such as Celery with Redis or RabbitMQ for heavy ones.

Each of these is a good answer to “where does my code run.” None of them answers “how does the finance lead approve this from Slack on Thursday,” and that’s the gap the rest of this page is about.

What FlowRunner adds around it

Look at any Python automation that has been in production for a year and you’ll find the same extra code around the real logic. A webhook receiver with signature checks. OAuth tokens for three SaaS apps, and the refresh logic for each. Retry loops around every outside call. A table that holds state while someone decides, a Slack message with a link, a small page to answer on, and code to pick the job back up. Logs only the author reads.

FlowRunner is that layer, already built:

• Triggers from 2,100+ integrations. A flow starts when an email with an attachment arrives in Gmail, a Shopify order comes in, a DocuSign envelope is completed, or a row is added to a Google Sheet. You connect the account once per workspace, and FlowRunner holds the auth. The catalog has 56,000+ callable actions (as of September 2026) for the steps after the trigger.
• Approval steps that wait. A flow sends the request on email, Slack, WhatsApp, phone, or a Form with a public link, so the person answering needs no account and no access to your code. The run waits for the answer: up to 30 days on Free, Starter, and Growth, and up to a year on Professional and above. A run that waits three days is still one execution.
• Retries and error paths. The HTTP Request block has a Retry Policy for status codes like 429 and 5XX and for network errors, with fixed or exponential backoff and jitter. A Handle Error block gives any step a failure path, so a bad call can alert someone and carry on.
• A record of every run. Each run shows every block’s input and output. Log history is 24 hours on Free and Starter, 7 days on Growth, 30 on Professional, 90 on Business, and unlimited on Enterprise. From Professional, the audit log records who changed which flow and when.
• Schedules. Once, every few seconds, daily, weekly, monthly, or a cron expression, with a start and an expiry, on any flow schedule.
• Unlimited users and a canvas. Every plan includes unlimited users, so the ops lead and the controller can open the flow, see what it does, and check last night’s runs without asking you.

FlowRunner also has its own AI agents, which run on your own model keys (BYOK) and can call your Python as a tool. More on that below.

How they work together

The rule is simple: your code runs where it runs today. FlowRunner either calls it, or gets called by it. Here are the patterns that come up most. The Python guide has the code for each.

Your script hands off the part with a person in it. A nightly job reconciles payments and finds three that don’t match. Instead of emailing a CSV, it starts an approval flow with the non-blocking Call Flow API and gets an executionId back at once. The flow asks the controller on Slack, waits, and POSTs the decision to your endpoint. Your script never holds a process open, and the request, the answer, and the time it came are on the run record.

FlowRunner calls your service. Your FastAPI service scores leads, parses contracts, or runs a model nobody else can. A flow calls it with the HTTP Request block, retries on 5XX, and takes the result into the next steps: update a record, notify the owner, ask a person when the score is borderline. For a job that runs for minutes, your service answers right away and calls the flow’s External Callback when it’s done, and the waiting run picks up from there.

A business event starts your code. You don’t want to host another webhook receiver and keep a Shopify or Zendesk token fresh. A flow catches the event with that app’s trigger, cleans the payload, and calls your endpoint with only the fields your code needs. If the job runs on a timer instead, a FlowRunner schedule can call the same endpoint, and the schedule sits next to the run history.

Your functions become tools for an AI agent. Wrap a few functions in an MCP server with the official MCP Python SDK, put it at a public URL, and register it in FlowRunner with a token or OAuth 2.0. A FlowRunner AI Agent can then call your pricing function or your inventory lookup when it decides it needs one, and it can call a human-review flow as a tool in the same run.

Your service becomes blocks the whole team can use. If people outside engineering should use your service in their own flows, wrap its API in a custom extension: one JavaScript module, deployed with the FlowRunner CLI, with npm packages shipped in the deploy. npx flowrunner init-claude installs two Claude Code agents that write the extension and its tests. The service itself stays in Python; the extension is a thin client for it.

When you don’t need FlowRunner

Adding a platform has a cost, and some Python never needs one:

• A one-off script. You run it by hand, read the output, and move on.
• Notebooks and research. Exploration, analysis, model experiments. Nothing to trigger, nobody to ask.
• Jobs with no apps and no people. A cron job that cleans a directory or rotates a file, where you check failures yourself, is fine on cron.
• Batch data pipelines on Airflow. Airflow is built for scheduled batch workflows with a clear start and end, and a team that runs it well should keep it there.
• A machine-to-machine wait. If a Lambda durable function waits on a callback from another system and no person is ever involved, it already has what it needs.

Add FlowRunner when the job crosses into business apps and people: an event in a SaaS app starts it, someone outside engineering decides part of it, or someone other than you needs to see what happened.

Feature comparison

Dimension	Python on its own	Python with FlowRunner
Where the logic runs	Your runtime: server, container, CI, serverless, Airflow	The same runtime, unchanged. FlowRunner doesn’t run Python
Triggers from SaaS apps	A webhook receiver, signature checks, and OAuth refresh you write per app	2,100+ integrations with the account connected once per workspace
Waiting for a person	You store state, send the message, build the answer page, and resume	A flow asks on email, Slack, WhatsApp, phone, or a Form and waits up to 30 days (Free, Starter, Growth) or a year (Professional and above)
Long waits	Lambda durable functions up to a year; otherwise a live process or your own state table	The run waits inside FlowRunner; your code gets the answer by HTTP
Retries on outside calls	A retry library or your own loop, per call	Retry Policy on the HTTP Request block; Handle Error for a failure path
Schedules	cron, GitHub Actions (every 5 minutes at most), Airflow	Keep yours, or a FlowRunner schedule calls your endpoint
Run history	Whatever the script logs	Every block’s input and output per run; 24 hours to unlimited by plan
Who can see it	The author, and whoever has server access	Unlimited users on every plan, on a canvas they can read
AI agents	Your own code and SDK	Your code plus FlowRunner AI Agents on your keys, which can call your MCP server and a human-review flow as tools
Cost	Your runtime	Your runtime plus FlowRunner: Free at 100 executions a month, Starter from $5; one run is one execution