Como Usar a API e SDK do Amazon Nova Act

A Amazon Nova Act é uma prévia de pesquisa lançada pela Amazon Inteligência Geral Artificial (AGI) que permite que desenvolvedores construam agentes capazes de realizar ações dentro de navegadores da web. Essa tecnologia combina instruções em linguagem natural com scripts em Python e automação Playwright para navegar em sites, clicar em botões, preencher formulários e extrair dados de forma dinâmica.

Diferente das ferramentas de automação da web tradicionais que dependem de scripts frágeis e códigos específicos de sites, a Nova Act usa IA para interagir com os sites de maneira mais adaptativa, ajudando-a a lidar com mudanças nas interfaces web sem necessidade de manutenção constante.

💡

Você está procurando simplificar seu fluxo de trabalho de desenvolvimento de API? Apidog se destaca como a alternativa definitiva ao Postman, oferecendo um conjunto abrangente de ferramentas para design, depuração, teste e documentação de APIs — tudo em uma plataforma unificada.

botão

Com sua interface intuitiva, recursos colaborativos e poderosas capacidades de automação, o Apidog reduz significativamente o tempo de desenvolvimento enquanto melhora a qualidade da API.

botão

Requisitos

Antes de começar com a Amazon Nova Act, você precisa:

Sistema Operacional: MacOS ou Ubuntu (Windows não é suportado atualmente)
Python: Versão 3.10 ou superior
Conta Amazon: Para gerar uma chave de API
Requisito de Localização: A Amazon Nova Act está atualmente disponível apenas como uma prévia de pesquisa nos EUA

Obtendo Sua Chave de API da Amazon Nova Act

Para usar a Amazon Nova Act:

Navegue até nova.amazon.com/act e faça login com sua conta Amazon
Selecione "Act" na seção Labs do painel de navegação
Gere uma chave de API
Se o acesso não for imediato, você pode ser colocado em uma lista de espera e notificado por e-mail quando o acesso for concedido

Instalação

Uma vez que você tenha sua chave de API:

# Instale o SDK
pip install nova-act

# Defina sua chave de API como uma variável de ambiente
export NOVA_ACT_API_KEY="sua_chave_api"

Nota: Na primeira vez que você executar a Nova Act, pode levar de 1 a 2 minutos para iniciar, enquanto instala os módulos do Playwright. Execuções subsequentes iniciarão mais rapidamente.

Uso Básico

Vamos começar com um exemplo simples diretamente da documentação:

from nova_act import NovaAct

with NovaAct(starting_page="https://www.amazon.com") as nova:
    nova.act("pesquisar uma cafeteira")
    nova.act("selecionar o primeiro resultado")
    nova.act("rolar para baixo ou para cima até ver 'adicionar ao carrinho' e então clicar em 'adicionar ao carrinho'")

Este script irá:

Abrir o Chrome e navegar até a Amazon
Pesquisar por cafeteiras
Selecionar o primeiro resultado
Encontrar e clicar no botão "Adicionar ao Carrinho"

Modo Interativo

A Nova Act pode ser usada interativamente para experimentação:

# Iniciar shell Python
$ python
>>> from nova_act import NovaAct
>>> nova = NovaAct(starting_page="https://www.amazon.com")
>>> nova.start()
>>> nova.act("pesquisar uma cafeteira")

Após a primeira ação ser concluída, continue com o próximo passo:

>>> nova.act("selecionar o primeiro resultado")

Note que, de acordo com a documentação, a Nova Act não suporta atualmente o iPython; utilize a shell padrão do Python.

Estratégias de Promptagem Efetivas

A documentação oficial enfatiza a divisão de tarefas em passos menores para maior confiabilidade:

1. Seja Específico e Claro

❌ NÃO

nova.act("Do meu histórico de pedidos, encontre meu pedido mais recente do India Palace e reordene-o")

✅ FAÇA

nova.act("Clique no ícone do menu hamburger, vá para o Histórico de Pedidos, encontre meu pedido mais recente do India Palace e reordene-o")

2. Quebre Tarefas Complexas em Passos Menores

❌ NÃO

nova.act("reserve um hotel que custa menos de $100 com a maior classificação estelar")

✅ FAÇA

nova.act(f"pesquisar hotéis em Houston entre {startdate} e {enddate}")
nova.act("ordenar por média de avaliação de clientes")
nova.act("clique em reservar no primeiro hotel que custa $100 ou menos")
nova.act(f"preencher meu nome, endereço e data de nascimento de acordo com {blob}")

Extraindo Dados de Páginas Web

A Nova Act suporta a extração de dados estruturados usando modelos Pydantic:

from pydantic import BaseModel
from nova_act import NovaAct, BOOL_SCHEMA

class Livro(BaseModel):
    titulo: str
    autor: str

class ListaDeLivros(BaseModel):
    livros: list[Livro]

def obter_livros(ano: int) -> ListaDeLivros | None:
    """Obter os melhores livros do NYT do ano e retornar como um ListaDeLivros."""
    with NovaAct(starting_page=f"https://en.wikipedia.org/wiki/List_of_The_New_York_Times_number-one_books_of_{ano}#Fiction") as nova:
        resultado = nova.act(
            "Retornar os livros na lista de Ficção",
            schema=ListaDeLivros.model_json_schema()
        )
        
        if not resultado.matches_schema:
            # A resposta da act não correspondeu ao esquema
            return None
            
        # Parsear o JSON no modelo pydantic
        lista_de_livros = ListaDeLivros.model_validate(resultado.parsed_response)
        return lista_de_livros

Para respostas booleanas simples, use o BOOL_SCHEMA embutido:

resultado = nova.act("Estou logado?", schema=BOOL_SCHEMA)
if resultado.matches_schema:
    if resultado.parsed_response:
        print("Você está logado")
    else:
        print("Você não está logado")

Processamento Paralelo com Múltiplas Sessões de Navegador

A documentação do GitHub confirma que a Nova Act suporta processamento paralelo com múltiplas sessões de navegador:

from concurrent.futures import ThreadPoolExecutor, as_completed
from nova_act import NovaAct, ActError

# Acumule resultados aqui
todos_os_livros = []

# Defina o número máximo de sessões paralelas do navegador
with ThreadPoolExecutor(max_workers=10) as executor:
    # Obtenha livros de vários anos em paralelo
    futuro_para_livros = {
        executor.submit(obter_livros, ano): ano
        for ano in range(2010, 2025)
    }
    
    # Colete resultados
    for futuro in as_completed(futuro_para_livros.keys()):
        try:
            ano = futuro_para_livros[futuro]
            lista_de_livros = futuro.result()
            if lista_de_livros is not None:
                todos_os_livros.extend(lista_de_livros.livros)
        except ActError as exc:
            print(f"Pulando o ano {ano} devido ao erro: {exc}")

Autenticação e Estado do Navegador

Para sites que requerem autenticação, a Nova Act oferece opções para usar perfis existentes do Chrome:

import os
from nova_act import NovaAct

user_data_dir = "caminho/para/meu/perfil_chrome"
os.makedirs(user_data_dir, exist_ok=True)

with NovaAct(
    starting_page="https://amazon.com/", 
    user_data_dir=user_data_dir,
    clone_user_data_dir=False
) as nova:
    input("Faça login nos seus sites, então pressione enter...")

Há também um script auxiliar embutido para esse propósito:

python -m nova_act.samples.setup_chrome_user_data_dir

Tratamento de Informações Sensíveis

A documentação alerta especificamente sobre o tratamento de dados sensíveis:

# Faça login corretamente
nova.act("digite o nome de usuário janedoe e clique na caixa de senha")

# Use Playwright diretamente para dados sensíveis
nova.page.keyboard.type(getpass())  # getpass() coleta a senha de forma segura

# Continue após as credenciais serem inseridas
nova.act("fazer login")

Aviso de Segurança: A documentação observa que capturas de tela feitas durante a execução capturarão qualquer informação sensível visível.

Recursos Adicionais

Trabalhando com Captchas

resultado = nova.act("Há um captcha na tela?", schema=BOOL_SCHEMA)
if resultado.matches_schema and resultado.parsed_response:
    input("Por favor, resolva o captcha e pressione enter quando terminar")

Baixando Arquivos

with nova.page.expect_download() as download_info:
    nova.act("clique no botão de download")
    
# Salve permanentemente
download_info.value.save_as("meu_arquivo_baixado")

Gravando Sessões

nova = NovaAct(
    starting_page="https://example.com",
    logs_directory="/caminho/para/logs",
    record_video=True
)

Exemplo do Mundo Real: Busca de Apartamentos

O artigo do dev.to demonstra um exemplo do mundo real de encontrar apartamentos perto de uma estação de trem. Aqui está a estrutura central desse exemplo:

from concurrent.futures import ThreadPoolExecutor, as_completed
import pandas as pd
from pydantic import BaseModel
from nova_act import NovaAct

class Apartamento(BaseModel):
    endereco: str
    preco: str
    quartos: str
    banheiros: str

class ListaDeApartamentos(BaseModel):
    apartamentos: list[Apartamento]

class CaltrainBiking(BaseModel):
    biking_time_hours: int
    biking_time_minutes: int
    biking_distance_miles: float

# Primeiro encontre apartamentos
with NovaAct(starting_page="https://zumper.com/", headless=headless) as client:
    client.act(
        "Feche qualquer banner de cookies. "
        f"Pesquise por apartamentos perto de {caltrain_city}, CA, "
        f"então filtre por {bedrooms} quartos e {baths} banheiros."
    )
    
    # Extraia listagens de apartamentos com esquema
    resultado = client.act(
        "Retorne a lista atualmente visível de apartamentos",
        schema=ListaDeApartamentos.model_json_schema()
    )
    
# Em seguida, verifique as distâncias de bicicleta em paralelo
with ThreadPoolExecutor() as executor:
    # Envie tarefas paralelas para verificar a distância de bicicleta até a estação de trem
    futuro_para_apartamento = {
        executor.submit(add_biking_distance, apartamento, caltrain_city, headless): apartamento 
        for apartamento in all_apartments
    }
    
    # Processar resultados
    for futuro in as_completed(futuro_para_apartamento.keys()):
        # Coletar e processar resultados
        pass

# Ordene e exiba resultados
apartamentos_df = pd.DataFrame(apartamentos_com_bike)

Este exemplo demonstra como a Nova Act pode:

Extrair dados estruturados de sites
Processar várias sessões de navegador em paralelo
Combinar informações de diferentes fontes

Limitações Conhecidas

De acordo com a documentação, a Nova Act possui as seguintes limitações:

Apenas Navegador: Não pode interagir com aplicativos não relacionados a navegador
Confiabilidade Limitada: Pode ter dificuldades com prompts de alto nível
Restrições de UI: Não pode interagir com elementos escondidos atrás de mouseovers
Modais de Navegador: Não pode interagir com modais de janela do navegador, como solicitações de permissão
Limitação Geográfica: Atualmente disponível apenas nos EUA
Status de Pesquisa: Este é um preview experimental, não um serviço de produção

Opções do Construtor NovaAct

A documentação lista estes parâmetros para inicializar a NovaAct:

NovaAct(
    starting_page="https://example.com",  # Obrigatório: URL para começar
    headless=False,                       # Se o navegador deve ser executado visivelmente ou não
    quiet=False,                          # Se deve suprimir logs
    user_data_dir=None,                   # Caminho para o perfil do Chrome
    nova_act_api_key=None,                # Chave da API (pode usar variável de ambiente em vez disso)
    logs_directory=None,                  # Onde armazenar logs
    record_video=False,                   # Se deve gravar a sessão
    # Outras opções conforme documentado
)

Conclusão

A Amazon Nova Act representa uma abordagem inovadora para automação de navegadores, combinando IA com técnicas tradicionais de automação. Embora ainda esteja em prévia de pesquisa com algumas limitações, oferece uma direção promissora para tornar a automação da web mais confiável e adaptável.

A principal vantagem da Nova Act é sua capacidade de desfazer interações complexas do navegador em etapas discretas e confiáveis, usando instruções em linguagem natural, que podem ser combinadas com código Python para fluxos de trabalho de automação flexíveis e poderosos.

Como esta é uma prévia de pesquisa disponível apenas nos EUA, espere mudanças e melhorias contínuas. Para as informações mais atuais, consulte sempre a documentação oficial em GitHub e nova.amazon.com/act.