Modo guia

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). 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 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:

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

# 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 «[email protected]» 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.