> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilebox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

export const AgentPrompt = ({children}) => {
  return <div className="tilebox-agent-chat" aria-label="Example agent chat prompt">
      <div className="tilebox-agent-chat-message">
        <div className="tilebox-agent-chat-avatar" aria-hidden="true">
          <Icon icon="user" iconType="solid" />
        </div>
        <div className="tilebox-agent-chat-content">
          <div className="tilebox-agent-chat-meta">You</div>
          <div className="tilebox-agent-chat-bubble">
            {children}
          </div>
        </div>
      </div>
    </div>;
};

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 theme={"system"}
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.

<AgentPrompt>
  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.
</AgentPrompt>

## Create or update the workflow project

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

<AgentPrompt>
  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.
</AgentPrompt>

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

<AgentPrompt>
  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.
</AgentPrompt>

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 theme={"system"}
tilebox cluster create "workflow-dev"
```

Add the cluster slug to `tilebox.workflow.toml`.

```toml theme={"system"}
[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 theme={"system"}
tilebox workflow build-release --debug
```

Then publish the release.

```bash theme={"system"}
tilebox workflow publish-release
```

## Deploy to the development cluster

Deploy the latest release the agent just published.

```bash theme={"system"}
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 theme={"system"}
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 theme={"system"}
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 theme={"system"}
Job submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90
```

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

```bash theme={"system"}
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 theme={"system"}
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.