Advanced

Writing prompts for unattended agents

A chat prompt is a conversation opener - you can correct it as it goes. A workflow prompt is a standing instruction that has to survive events you didn't anticipate, with nobody watching. The difference matters.

Say what to do when nothing should happen

Most workflow runs should be uneventful. An agent that feels obliged to act will find something to do. Give it permission to stop:

When a pull request is opened in acme/api, review the diff for changes to
authentication or billing code.

If you find any, comment on the PR naming the files and why they need a
second reviewer. Otherwise do nothing - do not comment, do not label.

A run that decides no action is required still succeeds. It just has no side effects.

Make it verify rather than assume

Agents are instructed to gather context with tools and to stop with a clear error rather than guess. Prompts that lean into this are more reliable:

Before posting, check whether a digest for this week already exists in the
channel. If one does, stop.

Be concrete about the destination

Name the channel, the repository, the table. If you'd rather not hardcode it, put it in a variable and refer to it by name - variables are passed into every run as context.

Post the digest to the Slack channel named in the DIGEST_CHANNEL variable.

Ask for the shape of output you want

Helios classifies a run's output as markdown, plainText, or json based on what the agent produced. If you need structured data, ask for it:

Return a JSON array of objects with keys `repo`, `prCount`, and `riskyFiles`.

See runs and outputs.

Persisting state between runs

Every workflow has a durable workspace at ~/workspace, shared by all of its runs. Use it to carry state forward:

Keep a file at ~/workspace/seen.json listing the issue numbers you've already
processed. Skip any issue already in that list, and add each new one you
handle.

Anything written outside ~/workspace - under $TMPDIR, for instance - disappears when the run ends. See sandboxes.

Testing a prompt before you schedule it

Dispatch the workflow manually. A manual run can carry an arbitrary JSON input payload, which the agent receives as trigger context - so you can hand it a copy of a real GitHub webhook body and see exactly how it behaves, without waiting for the event.

Then read the run's transcript. It records every tool call the agent made and everything that came back. When an agent does the wrong thing, the transcript almost always shows a prompt that was ambiguous rather than a model that was wrong.

Driving Helios from your own code

The API

Everything the UI does is available over the Helios API, authenticated with an API key scoped to helios. You can create and update workflows, dispatch runs with an input payload, poll run status, and read outputs.

Triggering from another system

A webhook trigger is usually the simplest integration point: your system signs a request with the trigger's secret and POSTs a JSON body, and the agent receives it as context. Signing is HMAC-SHA256 over "<timestamp>.<rawBody>".

From another agent

Helios is exposed over MCP, so an agent you run elsewhere can search the Helios API and call it. See MCP servers.

Debugging

The run failed with a timeout. Runs have a 30-minute limit. Narrow the task, or split it across several workflows.

The run failed before it started. The workflow has no prompt, or your organization has exhausted its credits.

The agent couldn't reach a service. Check the integration is connected and, for Slack and for GitHub organization installs, that the triggering user has authorized it individually. See authentication.

The agent acted on an event it should have ignored. Filters narrow which events reach the agent, but the prompt is the second filter. Say plainly what should be ignored.