Iterate on Workflow Releases with Agents

Use a coding agent with the Tilebox command-line tool to edit, publish, deploy, run, and debug Python workflow releases.

This guide shows the recommended loop for AI-assisted workflow development. The agent edits Python workflow code, publishes a release, deploys it to a development cluster, starts a release runner, submits a test job, and inspects logs or spans before iterating.

Use this loop when you want the code under test to match the artifact that release runners execute.

Prerequisites

Set up the Tilebox command-line tool and skills in the environment where your agent runs.

curl -fsSL https://install.tilebox.com/wizard.sh | sh
export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"

Ask the agent to inspect the command-line tool before changing resources.

You

Load the Tilebox workflow skills. Inspect tilebox agent-context workflow --output-schema and tilebox agent-context runner start --output-schema. Do not modify Tilebox resources yet.

Create or update the workflow project

For a new workflow project, ask the agent to initialize the project before editing task code.

You

Inspect tilebox agent-context workflow init --output-schema. Then initialize a new Tilebox workflow project with tilebox workflow init --name "<workflow-name>". After initialization, update the generated runner.py with the workflow tasks.

For an existing workflow project, ask the agent to keep the project centered on one reusable Runner definition.

You

Update this Python workflow project. Keep task classes in src/<package>/tasks.py, export runner = Runner(tasks=[...]) from src/<package>/runner.py, and keep tilebox.workflow.toml pointing at that runner object.

The direct runner path and release runner path should use the same Runner object. Direct execution uses runner.connect_to(Client(), cluster=...); release execution uses tilebox.workflow.toml and tilebox runner start.

Use a development cluster

Create a development cluster if you do not already have one.

tilebox cluster create "workflow-dev"

Add the cluster slug to tilebox.workflow.toml.

[targets.dev]
clusters = ["workflow-dev-abc123"]

Build and publish a release

Ask the agent to build locally first when it needs detailed validation output.

tilebox workflow build-release --debug

Then publish the release.

tilebox workflow publish-release

Deploy to the development cluster

Deploy the latest release the agent just published.

tilebox workflow deploy-release --latest --target dev

This updates cluster deployment state. It does not submit a job.

Start a release runner

In another terminal, start a release runner for the development cluster.

tilebox runner start --cluster workflow-dev-abc123 --debug

Keep this runner running while the agent iterates. It can run multiple deployed releases for the cluster and reacts when the agent deploys a new release.

Submit and inspect a test job

Submit a root task to the same cluster.

tilebox job submit \
  --name my-workflow-test \
  --task tilebox.com/example/ProcessScene \
  --version v1.0 \
  --cluster workflow-dev-abc123 \
  --input '{"scene_id":"S2A_001"}' \
  --wait

Job submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90

Inspect logs and spans when the job fails or takes longer than expected.

tilebox job logs <JOB_ID>
tilebox job spans <JOB_ID>

Iterate safely

For compatible fixes, keep the task identifier name and major version stable. Publish and deploy the fix, then retry the failed job.

tilebox workflow publish-release
tilebox workflow deploy-release --latest --target dev
tilebox job retry <JOB_ID>

For breaking input or behavior changes, bump the task major version and submit a new test job.