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

# Draft an agent with chat

> Create or edit an agent spec in the plan chat, then commit it.

This guide walks through drafting an agent spec in `jstm agent plan` and committing it. The chat is where you plan. Committing is a separate, explicit step.

## Prerequisites

* The `jstm` CLI, logged in. `jstm whoami` should show your workspace.
* A real interactive terminal. The chat won't run in a pipe or in CI.

<Steps>
  <Step title="Start a new draft">
    ```bash theme={null}
    jstm agent plan --new
    ```

    The chat opens with `What should this agent do?`. Describe the agent in plain language and press <kbd>Enter</kbd>:

    ```text theme={null}
    Fetch my Stripe invoices every morning and email me a summary.
    ```

    Joyvis replies with a draft and follow-up questions. Keep refining over as many turns as you like.

    <Tip>
      Press <kbd>Ctrl</kbd>+<kbd>J</kbd> to add a newline without sending. <kbd>Shift</kbd>+<kbd>Enter</kbd> also works in some terminals, but <kbd>Ctrl</kbd>+<kbd>J</kbd> always works. Press <kbd>Enter</kbd> to send.

      With the input empty, press <kbd>↑</kbd> to recall your previous messages and <kbd>↓</kbd> to go back. Press <kbd>PgUp</kbd> and <kbd>PgDn</kbd> to scroll the transcript.
    </Tip>
  </Step>

  <Step title="Resume an existing draft">
    Every session has an id, shown when you exit. To continue a draft later:

    ```bash theme={null}
    jstm agent plan 5f3a5c81-2d44-4e0b-9a17-0c9d3b7e9b21
    ```

    Your previous conversation replays into the chat and Joyvis keeps full context. New turns continue the same session, so what you commit later includes everything you discussed.

    If you lost the id, `jstm agent plan list` shows your sessions.
  </Step>

  <Step title="Exit — your work stays a draft">
    Leave the chat any way you like: type `done`, `quit`, `exit`, or `save` and press <kbd>Enter</kbd>, or press <kbd>Ctrl</kbd>+<kbd>C</kbd> or <kbd>Ctrl</kbd>+<kbd>D</kbd>.

    <Warning>
      None of these commit. Even typing `save` only exits. Exiting always leaves your spec as a draft — nothing is created or changed yet.
    </Warning>

    On exit you see:

    ```text theme={null}
      Session: 5f3a…-9b21 — spec is DRAFT (not committed).
      Resume editing:  jstm agent plan 5f3a…-9b21
      Commit the spec: jstm agent plan done 5f3a…-9b21
    ```

    Copy the session id. You need it for the next step.
  </Step>

  <Step title="Commit the draft into an agent">
    When the spec is ready, run the explicit commit command:

    ```bash theme={null}
    jstm agent plan done 5f3a5c81-2d44-4e0b-9a17-0c9d3b7e9b21
    ```

    You see `✓ spec committed`. This is the only step that creates or updates the agent. If you skip it, nothing changes — the draft waits for you.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                     | What's happening                                                                                                      |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `requires an interactive terminal`          | You're not in a real TTY — piped output or CI. Run it in a normal terminal.                                           |
| `Specify a form: ... --new ... or ... <id>` | You ran a bare `jstm agent plan`. Choose `--new` or pass a session id.                                                |
| `Could not determine active workspace`      | Run `jstm whoami` and make sure a workspace is active.                                                                |
| An error block appears mid-chat             | A turn failed, often a network blip. The chat stays open — try again. Your session is intact.                         |
| Resume shows an error and a fresh draft     | The id couldn't be loaded, either not found or no access. Your existing work isn't lost; you're starting a new draft. |

## Next steps

* [Build your first agent](/guides/build-your-first-agent) — the full path from draft to a run.
* [Planning an agent in chat](/features/agent-plan-chat) — how the chat works.
* [`jstm agent plan`](/cli/agent-plan) — full reference.