Iterate on Workflow Releases with Agents

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.

bash

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.

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.

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.

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.

bash

tilebox cluster create "workflow-dev"

Add the cluster slug to tilebox.workflow.toml.

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.

bash

tilebox workflow build-release --debug

Then publish the release.

bash

tilebox workflow publish-release

Deploy to the development cluster

Deploy the latest release the agent just published.

bash

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.

bash

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.

bash

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

text

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

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

bash

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.

bash

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.