Skip to main content
A loop is a list of steps. Steps can be large or small, but the best practice is for each step to contain a piece of named work you might have in a step process you’re writing for another human, like “Find new signups” or “Score each lead against our ICP.” You rarely write steps by hand. Tell the Songbird agent how you accomplish your use case today, and it breaks the work into repeatable steps for you. You can then read, edit, reorder, or rename any step, in the loop editor (or by asking an agent to do it for you!).

​
Anatomy of a step

Instructions

What the step should do and what it should hand back, in plain English. When a step needs judgment (reading survey replies, weighing signals, drafting a summary), AI follows these instructions.

Tools

The specific tools this step is allowed to use, such as “search HubSpot records” or “search the web.” A step can only use the tools provided to it. Giving a loop tool access in a step doesn’t give the AI access to every tool from that provider.

Deterministic code

Code that runs exactly as written on every run, with no AI deciding whether or how to run it. Today this means SQL and HogQL queries, with more languages and actions to come.

Stop condition

An optional rule that ends the run early, such as “stop if there are no new signups.” Nothing below it runs, and no messages are posted to Slack. Songbird helps reduce noise, raising only the cases that deserve your attention.

​
Example: Lead triage

A loop that triages new product signups every 3 hours and posts a card to #customer-signals for each signup worth reaching out to: Notice that only the research step can reach the open web, and only one of the last steps can write to the CRM. That separation is the point: private CRM data and untrusted web content never meet in the same step—a critical design to have good security posture in the AI era.

​
How results flow between steps

Each step produces one result. A later step uses an earlier result by naming it, for example “Using the CRM history, score each signup…”. You can also create specific, named variables in steps for use later on in the loop.

​
How Songbird runs steps

When you save a loop, Songbird compiles it: it checks every step, works out which results each step depends on, and flags problems such as a missing tool, a reference to a step that comes later, or a stop condition that can’t be decided from the data available. Ask the Songbird agent to fix any problems (it asks for your input and decisions, where it’s unclear what the best fix should be). At run time, the compiled loop runs like this:
  • Same steps, same order. Every run follows the compiled plan. Nothing is re-planned on the fly.
  • Independent steps run in parallel. In the example above, the company lookup and the CRM history can run at the same time.
  • Writes and stops run in order. A step that can change data, or that has a stop condition, waits for every step above it and finishes before any step below it starts. So a stop condition always takes effect before a later write.
A stop condition ends the run successfully, but it doesn’t undo work that already happened above it. Put it above any write it should prevent.

​
Test runs and live runs

Test run

Runs the current draft against real data and shows each step’s result. Test runs never write to your systems or post to Slack.

Live run

Runs the published version when its trigger fires. Writes and Slack posts happen for real. Before you publish, Songbird lists every system the loop will write to so someone signs off first.
Every live run is recorded step by step, including each step’s inputs, tool calls, and result, so you can trace exactly what happened and why.

​
Versions

Editing a loop changes its draft. The live loop keeps running the last published version until you publish again. Each publish is saved as a version, so you can see what changed and when.

​
The last step: defining the presentation

Steps do the work. How the result reads in Slack is set separately, in the loop’s presentation: the post format (message, card, carousel, or chart), an optional thread reply for detail, and writing instructions such as “lead with the count, then one card per signup.” The presentation can select, arrange, shorten, and format results, but it can’t do new research or write to your systems. Changing how a post reads never changes what the loop does. See Loops in Slack.

​
Common questions

As many as there are distinct units of work. One step can gather and interpret several results, so you don’t need a step per tool call. The Songbird agent picks a sensible split and you can merge or divide steps any time.
No. A step can only use the tools written into it, and only through connections you’ve made available to the loop. 
The run stops and is marked as failed, and the run record shows which step failed and why. Steps below it don’t run.
Yes. In an event-triggered loop, a step can read the event that started the run, such as the Slack message or GitHub PR that matched the trigger. See Triggers.