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

# Run an agent

> Trigger a run, follow its progress, pass input, and unblock it when it needs a person.

## Start a run

```bash theme={null}
jstm agent run failed-payment-digest
```

The run uses the agent's current stage. A pilot-staged agent runs as pilot; a live-staged agent runs live. To override:

```bash theme={null}
jstm agent run failed-payment-digest --mode dry_run
```

<Warning>
  Without `--mode`, a run on a live-staged agent has real side effects. Pass `--mode dry_run` explicitly when you want a safe run of an agent that is already in production.
</Warning>

## Pass input

```bash theme={null}
jstm agent run failed-payment-digest --input '{"date":"2026-08-03","include_retries":false}'
```

`--input` takes a JSON string and defaults to `{}`. The fields an agent accepts come from its spec — `jstm agent view <agent> --definition` shows them.

If you omit a required input, the run raises an input request rather than failing.

## Follow the progress

Progress streams as the run executes:

```text theme={null}
▶ run started
  ✓ Fetch failed payments since 2026-08-02
  ✓ Group by failure reason
  ▶ Post digest to #billing
```

Add `--verbose` to see an output preview for each completed step:

```bash theme={null}
jstm agent run failed-payment-digest --verbose
```

The stream times out after 300 seconds. The run itself keeps going — rejoin it with `jstm agent run show`.

## When the run needs you

If the agent reaches a point that requires a person, it pauses and prints how to unblock it:

```text theme={null}
  joystream input-requests show 9b74e2a1-33cd-4f80-a5e6-1d20b8f7c4aa
  joystream input-requests submit 9b74e2a1-33cd-4f80-a5e6-1d20b8f7c4aa --values '{...}'
```

Read the request first to learn the field names:

```bash theme={null}
jstm input-requests show 9b74e2a1-33cd-4f80-a5e6-1d20b8f7c4aa
```

Then answer it:

```bash theme={null}
jstm input-requests submit 9b74e2a1-33cd-4f80-a5e6-1d20b8f7c4aa \
  --values '{"approver":"dana@acme.com"}'
```

You can address the request by agent instead of by id, when the agent has exactly one open request:

```bash theme={null}
jstm input-requests submit failed-payment-digest --values '{"approver":"dana@acme.com"}'
```

## Avoid duplicate runs

When something might retry — a script, a webhook handler — pass an idempotency key:

```bash theme={null}
jstm agent run failed-payment-digest \
  --input '{"date":"2026-08-03"}' \
  --idempotency-key digest-2026-08-03
```

Re-sending the same key won't start a second run.

## After the run

```bash theme={null}
jstm agent run show failed-payment-digest/runs/12
```

This gives you status, stories, output, any rejection reason, and provenance — the exact spec, agent, package, and deployment versions that ran.

See [Review runs and tickets](/guides/review-runs-and-tickets) for reading results in depth.

## Scripting a run

```bash theme={null}
jstm agent run failed-payment-digest --input '{"date":"2026-08-03"}' --json
```

Results go to stdout and diagnostics to stderr, so the JSON is safe to pipe:

```bash theme={null}
jstm agent run failed-payment-digest --json | jq -r '.status'
```

## See also

* [Runs and work](/concepts/runs-and-work) — what a run produces.
* [`jstm agent run`](/cli/agent-run) — full reference.
* [Blocked or failing runs](/troubleshooting/runs)