Workflows
Build workflows from a description or change them step by step, read them in full, undo a change, run, pause and publish them, or give them an endpoint.
A workflow is an automation: a trigger, the steps it runs through its integrations and agents, and what it outputs. NoClick's builder (the one in the app) builds and changes it from what you describe, from your code or from the app, and people who know the process can open it there and change it too. Your code runs it and reads the result, without copying the steps into code.
Build one from a description
import noclick
brief = noclick.Workflow.create(
"Morning brief",
instructions="Every weekday at 8, email me today's calendar and the unread emails that need a reply.",
)
result = brief.latest_build.wait(timeout=900)
print(result.summary) # what the builder says it made
print([step.name for step in result.steps]) # ["Every weekday at 8", "Read the calendar", ...]create makes the workflow in your account and, with instructions, starts a WorkflowBuild: an operation whose wait() gives the builder's summary and the workflow's steps once it's done, or raises noclick.AnswerRequired when the builder asks something. A name is unique in your account: create with one you already have raises noclick.Conflict.
Change a workflow the same way, by describing the change. The builder reads the workflow as it stands, including what someone changed in the app:
brief.build("Also post the brief to #team on Slack").wait(timeout=900)A build keeps the workflow's description and its steps' names true to what it changed: move the brief from 8 to 9 and the step named "Every weekday at 8" is renamed with it.
One build runs at a time per workflow; another raises noclick.Conflict until it's done.
Publish its app
A workflow with an interface (a page, a form, a dashboard) can go live at its own address. publish() puts it live as it stands, and wait() gives the URL:
site = noclick.Workflow.from_name("Morrow Bakehouse site")
build = site.publish(subdomain="morrow", title="Morrow Bakehouse")
print(build.wait().published["url"]) # https://morrow.noclick.appLeave out subdomain to publish again at the address it has. To change it and put the change live in one go, pass publish to the build: site.build("Add our Saturday hours", publish=True). unpublish() takes it down; to move a live app without publishing what changed since, build with publish={"action": "rename", "subdomain": "morrow-bakery"}. Publishing puts something on the internet, so a connected app needs the deploy capability to do it.
When the builder asks
The builder asks rather than guesses: which channel, what time, which account. While it waits, the build is awaiting_human and question says what it needs. next_question() returns as soon as there is one, and answer() takes the answers by input id:
build = brief.build("Also post the brief on Slack")
while (question := build.next_question(timeout=900)) is not None:
if not question.answerable_from_code:
print("A person answers this:", question.answer_url)
break
build.answer({"channel": "#team"}, message="Keep it under five lines")
print(build.wait(timeout=900).summary)An input of type credential (an account to connect) or env (secret values) is a person's to answer: send them to answer_url, a page where they connect it or type it in, and the build goes on once they do. answer(skip=True) goes on without answering.
wait() never sits on a question you haven't seen: it raises noclick.AnswerRequired (AnswerRequired in TypeScript) with the build's question. Answer it, or send a person to its answer_url, and call wait() again: it waits through that question for its answer.
build = brief.build("Also post the brief on Slack")
try:
result = build.wait(timeout=900)
except noclick.AnswerRequired as asked:
print("A person answers this:", asked.question.answer_url)
result = build.wait(timeout=3600)
print(result.summary)From an agent, the MCP server's workflows_save tool does the same: build or change a workflow by name, answer what it asks, then wait.
Change it step by step
A workflow is a graph of steps, and your code can change it the way the app's canvas does, one step at a time, with no builder in between. graph() reads its whole definition: its name, description and settings, and its steps:
brief = noclick.Workflow.from_name("Morning brief")
graph = brief.graph()
for step in graph.steps:
print(step.id, step.type, step.name, step.settings)
print(graph.edges) # [{"id": ..., "from": "every_morning", "to": "summarize", "kind": "data", "handle": None}, ...]
print(graph.version) # 12Settings are as stored, never a secret: a key, a token or a password is left out, and writing the step back without it keeps it. Each step's withheld names the paths left out (api_key, auth.password, headers[0].value), as graph.settings_withheld does for the workflow's own settings (a variable's secret value, variable_definitions[1].value). The accounts connected to a step are in connections, by id. Notes on the canvas are in graph.notes.
version is the workflow's version: every change to its definition moves it on, and so do NoClick's own records of a trigger's registration. brief.version is the one this handle last read or wrote, and the workflow's read (Workflow.get) carries it too.
Each change is one call, applied at once as a version of its own:
send = brief.add_step(
"automation-gmail", operation="send_email_message", name="Send the summary",
settings={"to": "team@acme.com", "subject": "Today", "body": "{{ $('summarize').text }}"},
)
brief.step("summarize").connect(send)
send.update(settings={"subject": "Today's brief"})
print(send.verdict) # {"config_valid": False, "missing_required": ["credentials"]}: connect a Gmail account to itadd_stepgives the new step anidmade from its type unless you pass one.brief.step("summarize")is a handle to the step whose id issummarize; it sends nothing until you change it or read a field.- A change is judged as the app's builder judges one: a step type, operation or value that can't be raises
noclick.InvalidRequestnaming it, and nothing changes. A step that isn't ready to run yet is saved anyway, as on the canvas, and itsverdictsays what it needs. updatemergessettingsinto what the step has and never touches what you leave out;enabled=Falseswitches it off.patchchanges part of a long text, like an agent's instructions.connect(other, kind="tools")gives an agent the step's operations as tools.set_connectionattaches an account connected in the app.mockgives a step an output for test runs.removetakes it out, with its edges.- What a change did on its own is in the step's
notes: a model resolved to its full id, or the settings that went when an agent moved to another harness. - A trigger's schedule or webhook registers, moves or stops with the change, as when you change it in the app.
The workflow one of your agents runs on is read here, and changes through the agent (agent.update): an edit or a restore of it raises noclick.PermissionDenied, its agent_id naming the agent.
Several changes at once
edit() collects changes and sends them as one batch when the block ends: they land as one version, or none of them do. Pass if_version, the version you read, and the batch is refused with noclick.Conflict if the workflow changed since (in the app, by the builder, from another process of yours). The error carries the workflow as it stands, so your code decides again from what's there:
graph = brief.graph()
for attempt in range(3):
summarize = graph.step("summarize")
try:
with brief.edit(if_version=graph.version) as e:
post = e.add_step("automation-slack", operation="send_message_to_channel", name="Post it",
settings={"channel": "#team", "text": "{{ $('summarize').text }}"})
e.connect(summarize, post)
print(e.result.summary) # added 'Post it'; connected 'Summarize' to 'Post it'
break
except noclick.Conflict as changed:
graph = changed.graph # the workflow as it stands: decide again from itA batch takes each change a step's own methods make, under the change's name (add_step, update_step, patch_step, remove_step, connect, disconnect, set_connection, mock_step, unmock_step, move), and the workflow's own: update_workflow, add_note, define_variable, add_test_run, and layout to lay it out again. A step it adds has its id already, so later changes in the batch can name it. One change that can't apply raises noclick.InvalidRequest naming it (its field is ops[1].id for the batch's second), and nothing of the batch lands; a block that raises sends nothing. Use async with in async code. Changes made one call at a time never check a version: they apply to the workflow as it is.
A batch that can't be undone from its versions alone, one that removes a step holding an app, conversations or files, waits for the account's owner when an agent, a connected app or a deployed app's code sends it: it raises noclick.ApprovalRequired, nothing of it lands until they approve, and NoClick applies it then: the error's operation settles with the batch's answer, so there's nothing to send again.
Undo a change
Every change lands in the workflow's history: who made it, from where (source: api, canvas, builder, coordinator and the rest) and what changed. Each version of the history has a number of its own, history_version, which never changes; an edit answers the one it landed in.
- A change from your code is a version of its own, so it's undone on its own: nobody else's change is ever in it. Your key's next changes from the same place join it for five minutes from its first; after that, or once anyone else changes the workflow, the next is a new version. The builder's, an MCP client's and NoClick's assistant's changes are kept apart the same way.
- Saves in the app's canvas within five minutes of a session's first are one version, whoever made them;
authorslists everyone who edited in it, itsauthorfirst. - Moving things on the canvas is no version.
restore puts a version back, its name, description and settings with its steps, as a new version that never joins another, so a restore is undone the same way:
for version in brief.versions(limit=5):
print(version.history_version, version.source, version.summary, version.created_at)
latest, before = brief.versions(limit=2)
brief.restore(history_version=before.history_version)
print(brief.last_edit.summary) # restored version 11version_at(11) reads one with the definition it holds: its graph has the name, description, settings and steps as they were. Pass if_version, the workflow's version you read, and the restore is refused like a batch when the workflow changed since. Versions are kept 90 days.
Run a workflow
import noclick
intake = noclick.Workflow.from_name("order-intake")
run = intake.run({"order_id": "o_1042", "rush": True}).wait()
print(run.status) # succeeded
print(run.outputs["summary"]) # what its step named "summary" producedfrom_name refers to the workflow by its name in the app, and sends nothing until the first call. If two workflows share the name it raises noclick.Conflict: rename one, or use noclick.Workflow.from_id. Given description=, it gets the workflow, then sets that description on it when it differs; nothing else is touched.
run takes the workflow's inputs as a dict and returns an operation straight away. wait() gives a WorkflowRun once the run finishes: its status, its outputs, and when it started and finished. outputs holds what its final steps produced, each step that finished with nothing after it running, by the step's name in the app (its id when it has none or shares it with another final step).
A run starts where the workflow's trigger does, and runs only what that trigger leads to:
- its Run trigger, if it has one: the one the app's Run button starts;
- else its one trigger a run can start from code: a webhook or a form, which get your inputs as what was sent to them, so the run is the one a request to the webhook's URL or a submitted form would start; a schedule, which fires now; or an integration it polls, which checks now.
A workflow with no trigger runs every step. A switched-off trigger starts nothing. One that starts only on events an integration sends, like a Slack message, or from several triggers and no Run trigger to say which, raises noclick.ActionRequired: add a Run trigger in the app where runs from code should start.
What it takes
A workflow's inputs is a JSON schema of what its trigger takes: a form's fields, with their types and which are required; any JSON object for a webhook; and nothing, an empty schema, for the rest.
intake = noclick.Workflow.from_name("order-intake")
print(intake.inputs) # {"type": "object", "properties": {"order_id": {"type": "string"}, ...}, "required": ["order_id"]}A form field that keeps a value in the app, its default or one saved in the form, isn't required: left out, the run uses that value. Inputs that don't match raise noclick.InvalidRequest naming the field, before anything runs. A workflow whose trigger takes nothing runs with run().
When it fails
What would stop a run is refused before anything runs: noclick.NeedsConnection for a step with no account connected (connect one to it in the app), noclick.ActionRequired for one that isn't set up, and noclick.SpendCapExceeded or noclick.PaymentRequired once a cap or the balance is reached.
A run that fails later raises its error from wait(), naming the step that failed and saying why in that step's own words; next_step links to the run in the app, where you can see what each step did.
try:
intake.run({"order_id": "o_1042"}).wait()
except noclick.Error as error:
print(error.message, error.details.get("step"))A failed run, the ones a schedule or a webhook started included, also sends a workflow.run.failed event. An agent can watch over your workflows with it, look into each failure and pause one that keeps failing:
ops = noclick.Agent.from_name("ops")
ops.add_trigger(noclick.OnPlatformEvent("workflow.run.failed", conversation="workflow-{data.workflow_id}",
message="A workflow failed. Find out why; pause it if it's useless."))Don't wait on it
A long run doesn't need your process to stay up. Keep the operation's id and come back to it, or have a webhook tell you when it's done (operation.succeeded and operation.failed, with the run in data.result):
op = intake.run({"order_id": "o_1042"}, idempotency_key="order-o_1042")
job_id = op.id
run = noclick.Operation.from_id(job_id).wait()idempotency_key makes a retried request start one run, not two.
A run can wait inside the workflow too. While a step waits for someone's approval, its operation is awaiting_human; while it waits out a delay, or for an agent on a coding harness (Claude Code, Codex and the rest) to answer, it stays running. When the agent answers, the rest of the workflow runs as part of the same run, and its outputs include what came after the agent.
Run it for a user
A workflow belongs to your account, but a run can be recorded for a user, like any other call. The run counts toward that user's spend cap and shows under the user in activity. Its steps still use the connections attached to them in the app.
with noclick.as_user("acme"):
run = intake.run({"order_id": "o_1042"}).wait()Recent runs
for run in intake.runs(status="failed", user_filter=noclick.ALL_USERS):
print(run.started_at, run.source, run.error)To see what each step did in one run, read it by id. steps comes in the workflow's order, each with its status (succeeded, failed or skipped), its error and what it produced (long lists and text cut short):
run = intake.get_run(run.id)
for step in run.steps:
print(step.name, step.status, step.error or step.output)runs() lists the 20 most recent runs however they started: source is api and endpoint for runs from your code, schedule, trigger for an event (a webhook, an email, a message to its agent) and app for one started in the NoClick app. Pass limit= for more. Outside as_user you read the runs recorded for your account, which are every run not started from code for a user; user_filter reads your users'.
Give it an endpoint
endpoint = intake.endpoint(public=True)
print(endpoint.method, endpoint.url)endpoint() turns on the workflow's HTTP endpoint: POST the inputs as a JSON body and the response is the run's outputs, or the run's error. It waits up to 30 seconds for the run; a longer one answers 202 with the run's operation, which GET {url}/runs/{operation id} answers like the call would have once it's done (or noclick.Operation.from_id waits on, with a secret key).
curl -X POST "$URL" -H "Authorization: Bearer $NOCLICK_API_KEY" -H "Content-Type: application/json" \
-d '{"order_id": "o_1042"}'A private endpoint (public=False, the default) needs a secret key with the workflows scope, like any API call. A public endpoint also takes a publishable key that lists it, so a web page can call it without a secret, and each visitor is rate limited. Calling endpoint() again with public= changes it; without it, it keeps what it is.
Find workflows
for workflow in noclick.Workflow.list():
print(workflow.name, workflow.access, workflow.updated_at, workflow.app_url)Your keys read every workflow your account can open in the app: its own, and those shared with it, with a team workspace it belongs to, or through a shared folder. access says which: owner, editor or viewer. Changing, building, running, pausing and deleting take owning a workflow and paying for it: one in a team workspace someone else owns bills them, so it's changed and run in the app, and one shared with you is its owner's to change. Either refuses with noclick.PermissionDenied. from_name finds your own workflow by that name before one shared with you.
Read one in full
One workflow reads with everything about it:
intake = noclick.Workflow.get("2e3a9296-1bf5-4088-a20d-7c31937380c4")
for step in intake.steps:
print(step.name, step.enabled, step.settings, step.connection, step.trigger)
print(intake.readiness) # {"status": "needs_setup", "meaning": ..., "issues": [{"step": "ticket", "code": ..., "message": ...}]}
print(intake.edges, intake.urls, intake.paused)- Each step's
settingsare what it's set to in the app, never a secret (keys, tokens and passwords are left out), and long values are cut short. connectionisNonefor a step that takes no account, else whether one isattachedandhealthy(Nonewhen NoClick can't tell), with ahintwhen it isn't.- A trigger's
triggersays what keeps it from firing (error,paused_reason) and when it fires next (next_run); other steps haveNone. edgessay how steps are wired,kindtoolsfor a step an agent uses as a tool.readinessis whether it's set up to run: itsstatus, what thatmeaningis in a sentence, and the issues in the way, a step whose last run failed among them.waiting_for_inputis the usual state of a new automation that's on: its triggers are registered and it runs the next time one fires. Registered isn't tested:unverifiednames each step no run has completed yet.versionis its version, the one an edit checks withif_version. Notes on the canvas aren't steps here;graph().notesreads them.urlsare where it answers: itsendpoint, its publishedapp, a hostedmcpserver. A hosted MCP link connects to Claude Code, Codex, Cursor or any other MCP client the way a hosted MCP server's URL does.
A list leaves the steps out; read one workflow for them. This view is for reading at a glance, its long values cut short; graph() reads every step's settings as stored, to change them.
The workflow an agent you made runs on isn't listed, but reads by its id (the agent's workflow_id), with agent_id naming the agent, so what was added to it in the app shows: see What was added to it in the app. It changes and runs as the agent.
Pause and resume
digest = noclick.Workflow.from_name("Hourly digest")
digest.pause("Too noisy over the weekend")
digest.resume()pause() switches off each of the workflow's triggers that's on, with your reason beside them in the app: nothing starts it on its own (schedules, webhooks, events) until you resume(), which switches back on only what the pause switched off, never a trigger someone turned off by hand. Runs you start from code still run.
Trash and restore
delete() moves a workflow to the trash: its schedules and webhooks stop at once. restore() brings it back within 30 days, and they register again:
noclick.Workflow.from_id("2e3a9296-1bf5-4088-a20d-7c31937380c4").restore()Limits and billing
A build is AI usage, as building in the app is. A run is billed like the steps it runs: model tokens, tool runs and the rest, as in Spend and limits, to the key and user that started it. What a run does after it waited (an approval, a delay, an agent's answer) is billed to your account but doesn't count toward the key's or the user's cap. Inputs are up to 256 KB.
See the reference for Workflow.create, Workflow.build, Workflow.graph, Step, Workflow.edit, Workflow.versions, Workflow.publish, Workflow.run, Workflow.runs, Workflow.get_run, Workflow.pause, Workflow.restore and Workflow.endpoint.