Skip to main content
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.

​
Create or update the workflow project

For a new workflow project, ask the agent to initialize the project before editing task code. For an existing workflow project, ask the agent to keep the project centered on one reusable Runner definition. 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.