O Nosso Website, Construído
com Workflows de IA Agêntica

O desafio

A craftable software precisava de um novo website. O antigo site em Gatsby estava desactualizado, difícil de manter e não comunicava o que nos diferencia. Precisávamos de articular o nosso posicionamento — uma consultora de engenharia sénior, aumentada por IA, sediada em Portugal — e construir um site que posicionasse bem nos motores de busca, convertesse visitantes e fosse recomendado por motores de pesquisa com IA.

Em vez de seguir um cronograma tradicional de agência, usámos a nossa própria metodologia de engenharia agêntica — entregando ~60% mais rápido, com mais segurança, quality gates e performance. Este projecto serviria também como prova de conceito: se conseguíssemos construir o nosso próprio site de produção desta forma, poderíamos fazê-lo para clientes.

Análise competitiva e posicionamento

Antes de escrever uma única linha de código, estudámos como outras consultoras de software — particularmente as do espaço europeu de nearshoring — apresentavam os seus serviços, estruturavam o seu conteúdo e se posicionavam. Analisámos as suas páginas de indústria, descrições de serviços e formatos de caso de estudo para perceber o que o mercado esperava e onde nos podíamos diferenciar.

Três coisas destacaram-se da análise:

• A maioria dos concorrentes era genérica. Listavam tecnologias e serviços sem os ligar a problemas específicos de indústria. Decidimos ir a fundo em menos indústrias — Healthcare, Fintech, Retail Tech, TravelTech — com frameworks regulatórios, casos de uso e tech stacks adaptados a cada uma.
• A IA era um buzzword, não uma metodologia. Os concorrentes mencionavam IA no marketing mas não explicavam como a usavam na entrega. Decidimos fazer da engenharia agêntica o nosso diferenciador principal e ser transparentes sobre o modelo de colaboração humano-IA.
• A profundidade de conteúdo era uma vantagem competitiva. As consultoras bem posicionadas nos rankings tinham páginas detalhadas e com autoridade — não resumos de brochura. Precisávamos de profundidade: detalhes de capacidades, especificidades regulatórias e casos de uso concretos para AR/VR, IA/ML e governança de dados.

Skills de IA especializadas

Uma inovação chave neste projecto foi o uso de skills de IA especializadas — conjuntos de instruções construídos com propósito que davam ao agente de IA expertise de domínio para tarefas específicas. Em vez de depender de uma IA generalista, criámos seis perfis de especialista que o agente podia activar a pedido:

Estas skills significaram que o agente de IA não escrevia apenas código — trazia conhecimento especializado a cada tarefa. Quando o engenheiro pedia uma auditoria de página, o agente podia alternar entre perspectivas de SEO, GEO, acessibilidade e segurança, cada uma com os seus próprios checklists e standards.

Optimização SEO & GEO

A visibilidade nos motores de pesquisa foi uma preocupação central desde o primeiro dia — não apenas SEO tradicional, mas também Generative Engine Optimisation (GEO) para garantir que motores de pesquisa com IA também surfaçam e recomendem a craftable software.

SEO tradicional

• Dados estruturados — schemas JSON-LD para Organisation, Service, FAQPage e ItemList em cada página relevante
• HTML semântico — hierarquia correcta de headings, landmark regions e navegação acessível
• Optimização de meta tags — títulos e descrições únicos e ricos em keywords para cada página nas duas línguas
• Performance — arquitectura static-first com Astro, lazy loading de imagens e entrega via CDN CloudFront
• Segurança na migração — mapeamento de redirects dos URLs antigos do Gatsby para preservar equidade de pesquisa existente

Generative Engine Optimisation (GEO)

• Clareza de entidades — naming, descrições e atributos consistentes para que modelos de IA construam um knowledge graph preciso da craftable software
• Fundamentação de afirmações — cada afirmação de capacidade é suportada por tecnologias específicas, frameworks ou standards de compliance, não linguagem de marketing vaga
• Profundidade de conteúdo — páginas de indústria detalhadas com especificidades regulatórias (HIPAA, PCI DSS, GDPR, FCA) que modelos de IA reconhecem como autoritativas
• Respostas estruturadas — secções FAQ, pontos de comparação e framing claro de problema-solução que assistentes de IA podem extrair e citar
• Presença multi-idioma — traduções completas em português para captar recomendações de IA em mercados lusófonos

O workflow agêntico

O processo seguiu o nosso modelo standard de entrega agêntica. Um engenheiro sénior actuou como orquestrador — tomando decisões estratégicas, criativas e de negócio — enquanto agentes de IA com skills especializadas tratavam da implementação.

Decisões humanas

O engenheiro humano deteve cada escolha estratégica: o framework (Astro), a identidade visual, que indústrias destacar, o posicionamento competitivo, o tom de voz e a ordem das secções em cada página. Quando o agente propunha um layout ou copy, o engenheiro revisava-o à luz da análise competitiva e aprovava, ajustava ou rejeitava.

Execução dos agentes de IA

Uma única instrução desencadeava alterações coordenadas em templates de página, ficheiros de tradução i18n, componentes de navegação, fixtures de teste e CSS — tudo numa passagem, em inglês e português. O agente activava a skill especializada relevante para cada tarefa:

• Invocou a skill UI/UX para reordenar secções da homepage com base em princípios de arquitectura de persuasão
• Activou a skill SEO para gerar schemas JSON-LD e auditar meta tags após cada alteração de conteúdo
• Usou a skill GEO para estruturar conteúdo para descobribilidade por IA — definições de entidades, afirmações fundamentadas e formatação FAQ
• Executou a skill QA para correr testes de acessibilidade Playwright após alterações estruturais e corrigir violações imediatamente
• Aplicou a skill de cybersecurity para rever headers de segurança e validar o formulário de contacto contra riscos de injecção
• Consultou a skill Astro/AWS para decisões de arquitectura de deployment e infraestrutura optimizada em custo

Como funcionou na prática

Uma sessão típica: o engenheiro revisava o site no browser, comparava com a análise competitiva e dava uma instrução de alto nível. O agente de IA executava um plano — frequentemente alterando 10 a 20 ficheiros — e o engenheiro revisava o resultado em minutos.

Quando o engenheiro decidiu que as páginas de indústria precisavam de mais profundidade para competir, o agente pesquisou frameworks regulatórios comuns, standards de compliance e casos de uso de tecnologia para cada vertical, e produziu páginas detalhadas com breakdowns de capacidades, tech stacks e secções de compliance nas duas línguas.

Quando algo corria mal — um servidor de desenvolvimento em cache, uma imagem que falhava o download, um logo invisível no seu fundo — o agente diagnosticava a causa raiz e corrigia-a. O papel do humano era definir direcção e detectar problemas; o agente descobria porquê e como resolvê-los.

Assistente LLM na página de contacto e guardrails de segurança

A página de contacto inclui um assistente de IA que responde a perguntas sobre a craftable usando OpenAI (GPT-4o-mini). Implementámo-lo com uma abordagem agêntica e segurança em primeiro lugar: a skill de cybersecurity definiu o modelo de ameaças e aplicámos guardrails em camadas para o assistente permanecer no escopo e seguro em produção.

Processo LLM e configuração do modelo

• Prompt estruturado — Um system prompt fixo descreve o papel e o âmbito do assistente (serviços, preços, MCP, segurança, contacto). O input do utilizador nunca é concatenado no system prompt; apenas a mensagem actual e limpa é enviada.
• Todas as línguas permitidas — O assistente aceita prompts em qualquer língua. A mensagem original do utilizador é sempre enviada ao modelo para as respostas poderem ser na língua do utilizador. A detecção de injecção corre em separado: para input maioritariamente não latino usamos translate-then-check (traduzir para inglês, aplicar a blocklist em inglês); para input latino usamos a blocklist EN+PT.
• Contexto gerido no servidor — O cliente envia só a última mensagem do utilizador e um id de sessão. O histórico de conversa não é confiável do cliente; o servidor envia um único turno por pedido para evitar prompt injection via mensagens falsas de assistente.
• Restrições do modelo — GPT-4o-mini com temperatura baixa (0.3), máx. 300 tokens por resposta, sem tools ou function calling para o assistente não executar acções.
• Observabilidade — Cada pedido é traçado no Langfuse quando configurado: prompts, respostas, uso de tokens e latência ficam visíveis para debug e controlo de custos. Avaliações e alertas opcionais (pico de custo, taxa de erro) podem sinalizar alucinações ou respostas fora do tema.

Guardrails de segurança (defesa em profundidade)

• Validação de input — HTML e caracteres de controlo são removidos; o comprimento é limitado a 500 caracteres. Defesa multilingue contra injecção: para input maioritariamente latino usamos uma blocklist EN+PT (“ignore previous instructions”, “jailbreak”, “ignorar instruções anteriores”, etc.); para input maioritariamente não latino (ex. árabe, tailandês) traduzimos para inglês e aplicamos a blocklist em inglês (translate-then-check). O modelo recebe sempre a mensagem original do utilizador — a validação nunca altera o que o LLM vê. Todo o input é normalizado para Unicode NFC e payloads de alta entropia (ex. blobs base64) são rejeitados antes de chegarem ao modelo.
• Sanitização de output — Cada resposta do LLM é escapada em HTML antes de ser enviada ao cliente.
• Rate limits — Limite por IP (10 pedidos/minuto), limite por sessão (5 mensagens) e circuit breaker de tokens por sessão (20k tokens) previnem abuso.
• Cloudflare Turnstile — Verificação opcional no servidor quando configurada, com menor fricção para utilizadores legítimos. Fallback FAQ — Se a chave da API faltar ou a chamada falhar, o assistente usa um FAQ estático; as respostas são também sanitizadas.

Langfuse e configuração OpenAI (ChatGPT)

Usamos o SDK da OpenAI com o observeOpenAI do Langfuse para cada conclusão ser traçada. No Langfuse vemos o prompt, a resposta do modelo, uso de tokens e latência; o dashboard permite inspeccionar prompts, afinar o system message, adicionar avaliações (ex. factual grounding) e alertas opcionais (pico de custo, taxa de erro). Consulte docs/LLM-OBSERVABILITY-AND-WAF.md.

AWS WAF para protecção antecipada

O AWS WAF é usado em frente da API (ex. em API Gateway ou CloudFront) como camada de perímetro: rate limiting e regras geridas ajudam a bloquear abuso e DDoS antes do tráfego chegar ao assistente. O WAF complementa mas não substitui a validação ao nível da aplicação — o translate-then-check e as blocklists no nosso API continuam responsáveis pela detecção de prompt injection. Consulte a nossa página de segurança para o quadro completo de defesa em profundidade.

O que aprendemos

Tech stack & skills

Skills especializadas