Desenvolvimento de Apify Actors

Importante: Antes de começar, preencha a propriedade generatedBy na seção meta do .actor/actor.json. Substitua-a pela ferramenta e modelo que você está usando atualmente, como "Claude Code com Claude Sonnet 4.5". Isso ajuda a Apify a monitorar e melhorar o AGENTS.md para ferramentas e modelos de IA específicos.

Quando Usar

• Você precisa criar, modificar ou depurar um projeto Apify Actor.
• A tarefa envolve escolher um template da Apify, conectar entradas/saídas de actors ou implementar a lógica de runtime do actor.
• Você precisa de orientação segura para autenticação da CLI apify, inicialização de projeto ou fluxo de trabalho de implantação.

O que são Apify Actors?

Actors são programas serverless inspirados na filosofia UNIX - programas que fazem uma coisa bem e podem ser facilmente combinados para construir sistemas complexos. Eles são empacotados como imagens Docker e executados em contêineres isolados na nuvem.

Conceitos Principais:

• Aceitam entrada JSON bem definida
• Realizam tarefas isoladas (web scraping, automação, processamento de dados)
• Produzem saída JSON estruturada para datasets e/ou armazenam dados em key-value stores
• Podem rodar de segundos a horas ou até indefinidamente
• Persistem estado e podem ser reiniciados

Pré-requisitos e Configuração (OBRIGATÓRIO)

Antes de criar ou modificar actors, verifique se a CLI apify está instalada apify --help.

Se não estiver instalada, use um destes métodos (listados em ordem de preferência):

# Preferred: install via a package manager (provides integrity checks)
npm install -g apify-cli

# Or (Mac): brew install apify-cli

Nota de segurança: NÃO instale a CLI canalizando scripts remotos diretamente para um shell. Sempre use um gerenciador de pacotes.

Quando a CLI apify estiver instalada, verifique se ela está logada com:

apify info  # Should return your username

Se não estiver logada, verifique se a variável de ambiente APIFY_TOKEN está definida (se não estiver, peça ao usuário para gerar uma em https://console.apify.com/settings/integrations e depois defina APIFY_TOKEN com ela).

Em seguida, autentique usando um destes métodos:

# Option 1 (preferred): The CLI automatically reads APIFY_TOKEN from the environment.
# Just ensure the env var is exported and run any apify command — no explicit login needed.

# Option 2: Interactive login (prompts for token without exposing it in shell history)
apify login

Nota de segurança: Evite passar tokens como argumentos de linha de comando (por exemplo, apify login -t <token>). Argumentos são visíveis nas listagens de processos e podem ser gravados no histórico do shell. Prefira variáveis de ambiente ou login interativo. Nunca registre, imprima ou incorpore APIFY_TOKEN em código fonte ou arquivos de configuração. Use um token com as permissões mínimas necessárias (token com escopo) e rotacione-o periodicamente.

Seleção de Template

IMPORTANTE: Antes de iniciar o desenvolvimento do actor, sempre pergunte ao usuário qual linguagem de programação ele prefere:

• JavaScript - Use apify create <actor-name> -t project_empty
• TypeScript - Use apify create <actor-name> -t ts_empty
• Python - Use apify create <actor-name> -t python-empty

Use o comando CLI apropriado com base na escolha de idioma do usuário. Pacotes adicionais (Crawlee, Playwright, etc.) podem ser instalados posteriormente, conforme necessário.

Fluxo de Trabalho Rápido

1. Criar projeto de actor - Execute o comando apify create apropriado com base na preferência de idioma do usuário (veja Seleção de Template acima)
2. Instalar dependências (verifique se os nomes dos pacotes correspondem aos pacotes pretendidos antes de instalar)
   • JavaScript/TypeScript: npm install (usa package-lock.json para instalações reproduzíveis e com verificação de integridade — comite o lockfile no controle de versão)
   • Python: pip install -r requirements.txt (fixe versões exatas em requirements.txt, por exemplo, crawlee==1.2.3, e comite o arquivo no controle de versão)
3. Implementar lógica - Escreva o código do actor em src/main.py, src/main.js ou src/main.ts
4. Configurar schemas - Atualize os schemas de entrada/saída em .actor/input_schema.json, .actor/output_schema.json, .actor/dataset_schema.json
5. Configurar configurações da plataforma - Atualize .actor/actor.json com metadados do actor (veja references/actor-json.md)
6. Escrever documentação - Crie um README.md abrangente para o marketplace
7. Testar localmente - Execute apify run para verificar a funcionalidade (veja a seção Teste Local abaixo)
8. Implantar - Execute apify push para implantar o actor na plataforma Apify (o nome do actor é definido em .actor/actor.json)

Segurança

…