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

# Agent inputs

> How an agent declares what it needs, what happens when something is missing, and how a run resumes once you supply it.

An agent declares the inputs it accepts as part of its spec. At run time, JoyStream validates what you supplied against that declaration.

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

To see what an agent accepts:

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

## When something is missing

A run that lacks a required value does not guess and does not fail. It raises an **input request** and pauses.

```mermaid theme={null}
flowchart LR
    A[Run starts] --> B{Required input present?}
    B -- yes --> C[Continue]
    B -- no --> D[Raise input request<br/>Run pauses]
    D --> E[Person submits values]
    E --> C
```

This matters for agents that run unattended. A scheduled run that hits a decision only a person can make surfaces that decision as a request rather than making it badly.

## Request states

| Status                | Meaning                                                         |
| --------------------- | --------------------------------------------------------------- |
| `open`                | Waiting for values                                              |
| `partially_submitted` | Some fields supplied, others outstanding                        |
| `satisfied`           | Everything supplied. The run continues                          |
| `cancelled`           | Cancelled by a person. The run does not proceed past that point |
| `expired`             | Timed out                                                       |

Submitting to a request that is already satisfied, cancelled, or expired is rejected rather than silently ignored.

## Answering a request

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

Read the request before submitting — it names the fields and what each expects. Values are validated against the declaration, so a wrong shape is rejected with an error naming the problem rather than being passed through.

When an agent has exactly one open request, you can address it by agent instead of by request id:

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

If there is no open request, or more than one, this errors instead of guessing.

## Cancelling

```bash theme={null}
jstm input-requests cancel 9b74e2a1-… --reason "Superseded by manual close"
```

The reason is recorded with the cancellation, so the run's history explains why it stopped rather than just that it did.

## During an interactive run

`jstm agent run` prints the exact `show` and `submit` commands when it hits a blocked request, so you can unblock without looking anything up.

## See also

* [`jstm input-requests`](/cli/input-requests) — full reference.
* [Run an agent](/guides/run-an-agent)
* [Blocked or failing runs](/troubleshooting/runs)