O blog da AWS

Criando um pipeline de pontuação AEO com funções duráveis do AWS Lambda

Por Nick Beall, na Amazon Web Services.

Quando um agente de IA rastreia sua documentação em busca de respostas, ele não navega como um humano. Ele pontua a estrutura, extrai entidades, verifica a consistência factual e segue em frente, muitas vezes em menos de um segundo. Se o seu conteúdo não aparecer claramente nessas avaliações, ele não será exibido em respostas geradas por IA, independentemente de sua classificação atual nos mecanismos de busca. Esse problema é chamado de Agent Engine Optimization (AEO), e resolvê-lo exige a execução de várias etapas de avaliação que são caras, com estado e propensas a falhas.

Nesta publicação, você cria um pipeline de pontuação AEO de cinco etapas usando funções duráveis do AWS Lambda. Cada etapa (buscar, pontuar, analisar, publicar, registrar) é executada como uma operação com checkpoint que é suspensa sem gerar custos adicionais entre os estágios, é repetida sem gastar novamente com o trabalho anterior e é escrita como um código Python comum. Você pontua o conteúdo com base em cinco sinais de AEO, vê um exemplo real de auditoria e sai com um template do AWS Serverless Application Model (AWS SAM) pronto para implantação.

Uma observação sobre a busca: o pipeline usa uma requisição HTTP GET simples, imitando como os rastreadores de IA que não renderizam páginas (GPTBot, ClaudeBot, PerplexityBot) enxergam as páginas atualmente. Sites que dependem de JavaScript no lado do cliente podem receber pontuações mais baixas, pois a maioria dos agentes de IA não executa JavaScript.

Visão geral da solução

O pipeline é executado como uma única função durável do Lambda que encadeia cinco etapas com checkpoint. A pontuação é totalmente determinística (Python puro, sem modelo de linguagem de grande porte (LLM)), de modo que a mesma página produz consistentemente a mesma pontuação. O Amazon Bedrock gera uma análise em prosa que explica os resultados. Para implantações em produção que exibem conteúdo gerado aos usuários finais, considere adicionar o Amazon Bedrock Guardrails para controles de IA responsável. Como a função é suspensa entre as etapas sem gerar custos adicionais, uma falha na etapa 3 é retomada a partir da etapa 3. As pontuações determinísticas da etapa 2 já estão registradas em checkpoint.

O diagrama de arquitetura a seguir mostra os cinco estágios do pipeline:

  1. Fetch (Buscar) – Recupera a página de destino por meio de uma requisição HTTP GET e extrai sinais estruturados (títulos, contagem de tokens, regras de robots.txt, llms.txt, AGENTS.md).
  2. Score (Pontuar) – Aplica a rubrica determinística: verificações baseadas em limites produzem uma pontuação reproduzível de 0 a 100, sem envolvimento de LLM.
  3. Analyze (Analisar) – Envia as pontuações e os sinais brutos ao Amazon Bedrock, que gera descobertas em prosa e recomendações de correção (temperatura 0 para consistência).
  4. Publish (Publicar) – Renderiza o relatório de auditoria em HTML e JSON e o grava no Amazon Simple Storage Service (Amazon S3).
  5. Record (Registrar) – Persiste a pontuação e os metadados no Amazon DynamoDB para acompanhamento de tendências.
Diagrama de arquitetura do pipeline de pontuação AEO mostrando cinco etapas com checkpoint de uma função durável do Lambda em sequência: buscar, pontuar, analisar com o Amazon Bedrock, publicar no Amazon S3 e registrar no Amazon DynamoDB.

Figura 1: Os cinco estágios com checkpoint do pipeline de pontuação AEO, da busca ao registro.

Isso oferece segurança em novas tentativas, previsibilidade de custos e depuração mais simples. O pipeline é executado de forma totalmente automatizada por padrão, com uma barreira de callback opcional para fluxos de trabalho que exigem aprovação humana.

Por que usar funções duráveis do Lambda

Uma auditoria AEO consiste em cinco operações que dependem umas das outras, e qualquer uma delas pode falhar no meio da execução. Sem checkpoints, uma nova tentativa significa executar novamente todas as etapas desde o início, incluindo chamadas ao Bedrock que já retornaram resultados válidos.

As funções duráveis do Lambda resolvem isso com etapas com checkpoint. A saída de cada etapa é persistida antes do início da próxima. Quando uma chamada ao Bedrock sofre throttling na etapa 3, somente a etapa 3 é repetida. O pipeline não executa novamente as etapas 1 e 2 nem gasta novamente com seus tokens de inferência.

Entre as etapas, a função é suspensa sem manter nenhum ambiente aberto, portanto você não paga nada durante a espera. O pipeline é lido como um único arquivo Python, de cima para baixo. O checkpoint de cada etapa pode ser inspecionado de forma independente, de modo que depurar uma execução com falha significa examinar o resultado de uma única etapa, em vez de reproduzir todo o log de execução.

Pré-requisitos

Um template do SAM no repositório do GitHub provisiona a tabela do DynamoDB, o bucket do S3, a função durável do Lambda e as funções do IAM necessárias. Você implanta a stack completa com sam build && sam deploy --guided.

Tempo estimado: 20 a 30 minutos. Cada execução de auditoria usa uma única chamada de inferência do Bedrock, além de um breve uso da função durável do Lambda e do DynamoDB. Consulte a Calculadora de Preços da AWS para obter estimativas com base na sua Região e no volume de uso.

Os cinco sinais de AEO

A pontuação avalia o conteúdo com base em cinco sinais extraídos do framework de Agent Engine Optimization de Addy Osmani. Cada sinal corresponde a uma capacidade de que um agente de IA precisa ao decidir se deve usar o seu conteúdo. A pontuação é determinística: cada ponto corresponde a um limite mensurável (o arquivo existe, a contagem de tokens está abaixo do teto, a hierarquia de títulos é válida). Nenhum LLM está envolvido na produção do número.

1. Descobribilidade (0–25)

Este sinal verifica se a URL retorna HTML renderizado no servidor, se existe um arquivo llms.txt na raiz do domínio e se os rastreadores de IA recebem uma resposta bem-sucedida. Uma página que retorna HTTP 200 com conteúdo analisável é aprovada. Uma página que retorna 403 ou 429 para agentes de usuário de IA é reprovada.

2. Capacidade de análise (0–25)

Este sinal pontua a hierarquia de títulos (H1 a H6), a presença de blocos de código e tabelas e se a página possui marcos semânticos. Como os agentes analisam o conteúdo de forma estrutural, e não linear, é essencial que os sites sejam bem organizados e lógicos. Osmani sugere servir Markdown e HTML, iniciar cada seção com o resultado e usar tabelas para referências de parâmetros, entre outras dicas que tornam seu site mais fácil de analisar.

3. Eficiência de tokens (0–25)

Mede a contagem total de tokens em relação a um teto de 30.000 tokens e a uma meta de início rápido de 15.000 tokens. Páginas sobrecarregadas com elementos de navegação ou texto repetido recebem pontuações mais baixas.

4. Sinalização de capacidades (0–15)

Este sinal verifica a existência de arquivos AGENTS.md ou skill.md que descrevam as ações disponíveis, as entradas necessárias, a autenticação e os limites de taxa. Sem eles, os agentes descobrem as capacidades por tentativa e erro.

5. Controle de acesso (0–10)

Verifica o robots.txt em busca de regras específicas para IA (GPTBot, ClaudeBot, PerplexityBot). Páginas com regras explícitas de Allow ou Disallow para agentes de usuário de IA recebem pontuações mais altas do que páginas sem regras específicas para IA, nas quais o acesso é aberto por padrão. Qualquer uma das escolhas é válida. O sinal recompensa tomar a decisão de forma intencional.

As pontuações determinísticas alimentam a etapa de análise, na qual o Bedrock gera explicações em prosa e recomendações práticas de correção.

Exemplo: auditando uma página real

Para ver o pipeline em ação, veja os resultados de uma página de documentação técnica: uma visão geral conceitual de um serviço de computação em nuvem.

Alvo: uma página de documentação técnica (visão geral conceitual, 958 palavras)

Pontuação geral: 58/100

Sinal Pontuação Principal descoberta
Descobribilidade 17/25 Renderizada no servidor, llms.txt existe (mas inchado, com 295 KB / ~74 mil tokens, em comparação ao limite recomendado de 5 mil tokens). Sem AGENTS.md.
Capacidade de análise 14/25 Hierarquia de títulos inválida (H1 para H6 para H2). Sem blocos de código delimitados ou tabelas, apesar de ser documentação técnica. Taxa de ruído de HTML de 63,9%.
Eficiência de tokens 25/25 1.245 tokens. Bem abaixo da meta de início rápido de 15 mil e do teto de 30 mil.
Sinalização de capacidades 0/15 Sem skill.md. Os agentes não conseguem descobrir quais ações esta documentação possibilita.
Controle de acesso 2/10 Sem regras específicas para IA no robots.txt. O acesso é acidental, e não intencional.

Três principais correções:

  1. Criar um skill.md declarando o que os agentes podem fazer com este serviço (ações disponíveis, entradas necessárias, restrições).
  2. Corrigir a hierarquia de títulos para seguir um aninhamento válido (H1, H2, H3) e adicionar blocos de código delimitados com marcação de linguagem.
  3. Adicionar um AGENTS.md na raiz do domínio e regras explícitas para rastreadores de IA no robots.txt.

A pontuação é determinística, e cada ponto corresponde a uma condição mensurável. Em seguida, o Amazon Bedrock executa a inferência do LLM sobre os resultados para gerar as descobertas em prosa.

Nos bastidores: etapas e callbacks

Cada etapa da auditoria anterior, da busca ao registro, é executada como uma etapa com checkpoint. O callback é opcional e fica após a etapa de análise, caso você queira que uma pessoa revise o relatório antes de ele ser publicado.

As funções duráveis do Lambda expõem duas primitivas principais: etapas e callbacks. Este pipeline é executado de forma totalmente automatizada por padrão (cinco etapas, sem barreira humana), mas você pode optar por uma barreira de aprovação baseada em callback quando o caso de uso exigir.

Etapas

Uma etapa é uma unidade de trabalho. O runtime registra em checkpoint o valor de retorno antes do início da próxima etapa. Você declara uma com o decorador @step:

@durable_step
def score_content(step_context: StepContext, page_content: str) -> dict:
    response = bedrock.invoke_model(
        modelId=os.environ["BEDROCK_MODEL_ID"],
        body=json.dumps({"prompt": build_scoring_prompt(page_content)})
    )
    return json.loads(response["body"].read())

Se esta etapa for bem-sucedida, seu valor de retorno é persistido. Em uma nova tentativa, as etapas concluídas são ignoradas e seus resultados em cache são repassados adiante. Duas regras:

  • Mantenha os valores de retorno pequenos. Retorne resultados estruturados, não respostas brutas de API.
  • Um efeito colateral por etapa. Uma etapa que chama o Bedrock e também grava no DynamoDB é mais difícil de analisar em uma nova tentativa. Faça uma chamada externa por etapa.

Callbacks

Por padrão, o pipeline executa as cinco etapas sem parar. Para adicionar uma barreira de revisão humana, ative o callback. A função é suspensa sem gerar custos adicionais até que um sinal externo chegue. Na prática, você conecta isso a um bot do Slack ou a um painel de aprovação, em vez de um comando de CLI. A retomada ocorre por meio da chamada de API da AWS SendDurableExecutionCallbackSuccess com o ID do callback. Como essa é uma chamada de API autenticada, somente entidades principais com as permissões apropriadas do IAM podem sinalizar a conclusão.

# In the handler (called on DurableContext, not inside a step):
callback = context.create_callback(name="review_report")
send_to_reviewer(callback.callback_id, report)

# Execution suspends here until the external system calls
# SendDurableExecutionCallbackSuccess with the callback ID.
result = callback.result()

A função é suspensa em callback.result() sem gerar custos adicionais. O sistema externo chama SendDurableExecutionCallbackSuccess com o ID do callback e o payload de aprovação. Os timeouts geram TimeoutError para roteamento de fallback.

Quando adicionar um callback

Execute de forma totalmente automatizada quando… Adicione um callback quando…
Auditorias agendadas ou monitoramento de regressão de integração contínua e entrega contínua (CI/CD) Páginas de alto risco que precisam de aprovação humana
Os relatórios alimentam diretamente painéis ou alertas Integração com fluxos de trabalho externos (Slack, Jira, webhook)
As correções são sugestões, não ações aplicadas automaticamente As ações subsequentes são controladas (abertura automática de tickets)

Por padrão, o pipeline ignora completamente o callback. Para ativá-lo, defina APPROVAL_GATE=true nas variáveis de ambiente da função.

Limpeza

Para evitar cobranças contínuas, exclua a stack quando terminar de experimentar:

sam delete --stack-name aeo-scoring-pipeline

Isso remove a função durável do Lambda, a tabela do DynamoDB, o bucket do S3 (se estiver vazio) e as funções do IAM associadas. Se o seu bucket do S3 contiver relatórios de auditoria que você deseja manter, faça o download deles primeiro ou remova a configuração DeletionPolicy: Delete do template antes de implantar.

Conclusão

Agora você tem um pipeline de pontuação AEO de cinco etapas em uma única função do Lambda que registra checkpoints entre as etapas sem gerar custos adicionais. Algumas etapas envolvem inferência de LLM pela qual você não quer pagar duas vezes. Os checkpoints duráveis ajudam a garantir que isso não aconteça.

Para começar:

  1. Clone o repositório: github.com/aws-samples/sample-aeo-scoring-pipeline
  2. Implante com sam build && sam deploy --guided
  3. Execute sua primeira auditoria: aws lambda invoke --function-name AeoScoringPipeline --payload '{"url": "https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html"}'

Próximos passos: agende auditorias usando o Amazon EventBridge, adicione alertas no Slack quando as pontuações caírem ou estenda a rubrica com sinais específicos do seu domínio.

Para saber mais sobre as funções duráveis do Lambda, consulte o Guia do Desenvolvedor de funções duráveis do AWS Lambda. Para conhecer o framework AEO, consulte a publicação original de Addy Osmani sobre conteúdo otimizado para agentes.


Este conteúdo foi traduzido da publicação original do blog, que pode ser encontrado aqui.

Biografia do Autores

Nick Beall é Technical Account Manager na Amazon Web Services.

 

Biografia do tradutores

Daniel Abib é Arquiteto de Soluções Sênior e Especialista em Amazon Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem.
https://www.linkedin.com/in/danielabib/
Nicolas Tarzia é Senior Technical Account Manager na AWS, com mais de 13 anos de experiência, com ampla experiência em arquitetura cloud, engenharia e design de software. Atualmente está habilitando empresas do ramo de ISV (Independent Software Vendors) simplificando a operação na nuvem e otimizando os custos em cloud. Sua área de interesse são tecnologias serverless.
https://www.linkedin.com/in/nicolastarzia