# Modalità guida

> Fonte: https://astrallab.dev/it/docs/guides

Disponibile dalla 0.2.4

Fai percorrere a un agente un flusso in qualsiasi applicazione web e Astral scrive la guida per l’utente al posto tuo.

## Cosa ottieni

Una guida scritta a partire da un’esecuzione registrata, nella cartella dell’esecuzione accanto a `report.html`:

- `guide.md` e `guide.html` (una pagina autonoma): un titolo, un’introduzione, una sezione numerata per passaggio e un’istruzione numerata per ogni azione.
- Uno screenshot per azione, scattato prima di un clic, con il bersaglio evidenziato.
- Una sezione finale **Risultato** con uno screenshot di chiusura.
- Un link alla registrazione: un MP4 su macOS, un PNG animato altrove.
- Solo nomi di file relativi, così la cartella si può spostare o comprimere così com’è.

## Chiedilo al tuo agente

Qualsiasi agente MCP collegato ad Astral può farlo. Chiedigli, per esempio: _«scrivi una guida per l’utente per creare un cliente, in spagnolo»_. Dietro c’è il prompt MCP `write-guide`, che il tuo agente elenca insieme agli altri (vedi [il riferimento degli strumenti](https://astrallab.dev/it/docs/tools.md)). I suoi argomenti:

- `task` (obbligatorio): cosa insegna la guida, come «come creare un account».
- `lang`: la lingua della guida come codice, `es` o `en` (predefinito `en`).
- `url`: da dove inizia il percorso (facoltativo: altrimenti la scheda corrente).

L’agente esplora il flusso, lo esegue una volta come [esecuzione di test](https://astrallab.dev/it/docs/test-runs.md) con l’opzione `guide`, controlla il risultato e riporta i file.

## L’opzione guide

Il prompt usa un’opzione di `astral.test`, che puoi impostare anche tu stesso in uno script:

```js
await astral.test('Create a customer', async () => {
  await astral.step('Open the customers page', () =>
    astral.navigate({url: 'http://127.0.0.1:4555/'}));
  // ...the rest of the flow
}, {
  record: 'video',
  guide: {lang: 'es', title: 'Crear un cliente', intro: 'Cómo dar de alta un cliente nuevo.'}
});
```

`guide` accetta `lang`, `title` e `intro`. Attiva da sola gli screenshot per azione; aggiungi `record: 'video'` per ottenere anche una registrazione. Il risultato dell’esecuzione include `guide: {md, html, lang}`.

## Lingue

Le didascalie disegnate sulla pagina e le etichette della guida (Risultato, Guarda la registrazione, Screenshot) sono tradotte per inglese e spagnolo. Qualsiasi altro codice di lingua ricade sulle didascalie in inglese, mentre i nomi dei passaggi, il titolo e l’introduzione restano nella lingua in cui l’agente li ha scritti. Dai a ogni passaggio il nome che gli darebbe l’utente, come «Crea il tuo account», non quello che gli darebbe un test.

## Password

Una password digitata non arriva mai alla guida. L’istruzione dice «Type your password in «Password»» (o «Escribe tu contraseña en «Password»» in spagnolo) e il valore non viene scritto in nessun file.

## Percorsi falliti

Se un passaggio fallisce, la guida viene comunque scritta ma inizia con un avviso, «This walkthrough did not complete: step N failed. Do not publish this guide as it is.» (nella lingua della guida), e il passaggio fallito è contrassegnato. Correggi il flusso e rieseguilo.

## Che aspetto ha

Il `guide.md` di un’esecuzione reale sull’app dimostrativa DevLab (è sostituito solo l’indirizzo):

```markdown
# Cómo crear una cuenta

Esta guía te lleva por el registro paso a paso.

## 1. Abre la página de registro

1. Ve a https://your-app.example/register

   ![Captura de pantalla](01-step1-navigate.png)

## 2. Rellena tus datos

1. Escribe «Ana Guía» en «Name»

   ![Captura de pantalla](03-step2-type.png)

2. Escribe «ana@devlab.test» en «Email»

   ![Captura de pantalla](04-step2-type.png)

3. Escribe tu contraseña en «Password»

   ![Captura de pantalla](05-step2-type.png)

4. Escribe tu contraseña en «Confirm password»

   ![Captura de pantalla](06-step2-type.png)

## 3. Crea la cuenta

1. Haz clic en «Create account»

   ![Captura de pantalla](08-step3-click-before.png)

## Resultado

![Resultado final](10-step3-final.png)

[Ver la grabación](recording.mp4)
```

I nomi dei campi provengono dalle etichette dell’app stessa, quindi un’app in inglese dà «Email» all’interno di frasi in spagnolo.

## Piattaforme

Verificato solo su macOS. La registrazione MP4 viene codificata su macOS; sugli altri sistemi la registrazione è un PNG animato. Windows e Linux non sono verificati per la modalità guida.