# Modo guia

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

Disponível a partir da 0.2.4

Conduza um agente por um fluxo em qualquer aplicação web e o Astral escreve o guia do usuário para você.

## O que você obtém

Um guia escrito a partir de uma execução gravada, na pasta da execução ao lado de `report.html`:

- `guide.md` e `guide.html` (uma página autocontida): um título, uma introdução, uma seção numerada por passo e uma instrução numerada para cada ação.
- Uma captura de tela por ação, tirada antes de um clique, com o alvo marcado.
- Uma seção final de **Resultado** com uma captura de tela de encerramento.
- Um link para a gravação: um MP4 no macOS, um PNG animado nos demais.
- Somente nomes de arquivo relativos, então a pasta pode ser movida ou compactada como está.

## Peça ao seu agente

Qualquer agente MCP conectado ao Astral pode fazer isso. Peça, por exemplo: _“escreva um guia do usuário para criar um cliente, em espanhol”_. Por trás está o prompt MCP `write-guide`, que o seu agente lista junto com os outros (veja [a referência de ferramentas](https://astrallab.dev/pt/docs/tools.md)). Seus argumentos:

- `task` (obrigatório): o que o guia ensina, como “como criar uma conta”.
- `lang`: o idioma do guia como código, `es` ou `en` (padrão `en`).
- `url`: onde o passo a passo começa (opcional: caso contrário, a aba atual).

O agente explora o fluxo, executa-o uma vez como [execução de teste](https://astrallab.dev/pt/docs/test-runs.md) com a opção `guide`, verifica o resultado e informa os arquivos.

## A opção guide

O prompt usa uma opção de `astral.test`, que você também pode definir por conta própria em um 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` aceita `lang`, `title` e `intro`. Ela ativa sozinha as capturas de tela por ação; acrescente `record: 'video'` para obter também uma gravação. O resultado da execução traz `guide: {md, html, lang}`.

## Idiomas

As legendas desenhadas na página e os rótulos do guia (Resultado, Ver a gravação, Captura de tela) são traduzidos para inglês e espanhol. Qualquer outro código de idioma recorre às legendas em inglês, enquanto os nomes dos passos, o título e a introdução permanecem no idioma em que o agente os escreveu. Dê a cada passo o nome que o usuário daria, como “Crie sua conta”, e não o que um teste daria.

## Senhas

Uma senha digitada nunca chega ao guia. A instrução diz “Type your password in «Password»” (ou “Escribe tu contraseña en «Password»”, em espanhol) e o valor não é gravado em nenhum arquivo.

## Passo a passo com falha

Se um passo falha, o guia ainda é escrito, mas começa com um aviso, “This walkthrough did not complete: step N failed. Do not publish this guide as it is.” (no idioma do guia), e o passo que falhou é marcado. Corrija o fluxo e execute-o de novo.

## Como ele se parece

O `guide.md` de uma execução real contra o app de demonstração DevLab (apenas o endereço foi substituído):

```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)
```

Os nomes dos campos vêm dos rótulos do próprio app, então um app em inglês gera «Email» dentro de frases em espanhol.

## Plataformas

Verificado somente no macOS. A gravação em MP4 é codificada no macOS; em outros sistemas, a gravação é um PNG animado. Windows e Linux não estão verificados para o modo guia.