Agente de Briefing Hacker News Sempre Ativo

AgentScout é um agente de briefing sempre ativo do Hacker News construído com o Google ADK. Ele analisa o Hacker News em busca de histórias de alto sinal sobre agentes de IA, MCP, agentes de codificação, automação de fluxos de trabalho e aplicações LLM, e transforma os melhores links num resumo conciso de engenharia.

A aplicação pode funcionar como um agente interativo do ADK ou como um serviço de backend agendado. Usa o ADK Web para solicitar um briefing manualmente, ou executa o hook do agendador FastAPI para que o Cloud Scheduler possa ativar um briefing diário do Hacker News e enviá-lo através do Gmail, Slack, Linear, Jira ou um fluxo de digestão interna.

Funcionalidades

• Monitorização do Hacker News: Encontra histórias sobre agentes de IA, MCP, agentes de codificação, automação e aplicações LLM no Hacker News.
• Classificação de sinal: Classifica histórias por relevância, pontos, comentários e posição na página principal.
• Geração de briefing: Produz um briefing em texto e HTML limpo com resumos, links e próximas ações.
• Agente Google ADK: Expõe um root_agent para que os utilizadores possam solicitar briefings no ADK Web.
• Backend pronto para agendador: Inclui endpoints HTTP e Pub/Sub para o Cloud Scheduler ou outros sistemas de automação.
• Entrega via Gmail e webhook: Envia briefings através da API do Gmail ou de um webhook genérico quando dry_run=false.
• Fluxo de entrega seguro: Por defeito, funciona em modo de teste e salta a entrega a menos que as credenciais sejam configuradas explicitamente.

Como Funciona

1. AgentScout recolhe histórias a partir de dados de amostra determinísticos ou da página principal ao vivo do Hacker News.
2. Filtra tópicos sobre agentes de IA e aplicações LLM.
3. Classifica as histórias mais úteis para engenheiros e criadores de produtos.
4. Gera um briefing diário em texto e HTML.
5. O ADK Web, um trigger HTTP, ou um endpoint de push Pub/Sub devolve o resultado.
6. Se a entrega estiver ativada, a API do agendador envia o briefing através do Gmail ou publica-o em AGENTSCOUT_WEBHOOK_URL.

Requisitos

• Python 3.10+
• Chave da API Gemini para o ADK Web
• Credenciais OAuth do Gmail opcionais para entrega direta de e-mail
• URL de webhook opcional para Slack, Linear, Jira, GitHub Issues, SendGrid ou fluxos de trabalho internos

Instalação

git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
cd awesome-llm-apps/always_on_agents/always_on_hn_briefing_agent
pip install -r requirements.txt
export GOOGLE_API_KEY="your_gemini_api_key"

Opção 1: Executar no ADK Web

Utiliza o ADK Web quando quiseres conversar com o agente e pedir um resumo manualmente.

adk web .

Aceder ao ADK Web UI

Abre o ADK Web UI e seleciona always_on_hn_briefing_agent.

Experimenta comandos como:

Give me today's AgentScout brief.

Scout the top 3 Hacker News stories about AI agents and LLM apps.

Show me the highest-signal Hacker News items about MCP, coding agents, and workflow automation.

Opção 2: Executar a API do Scheduler Localmente

Utiliza a API do scheduler quando quiseres que o AgentScout funcione como um serviço de backend sempre ativo. Esta é a mesma interface que podes implementar por detrás do Cloud Run e ativar a partir do Cloud Scheduler.

Inicia o backend do scheduler:

uvicorn scheduler_api:app --host 0.0.0.0 --port 8000

Pré-visualizar uma execução agendada

Num outro terminal, pré-visualiza uma execução agendada sem entrega:

curl "http://127.0.0.1:8000/agent-scout/dry-run?top_n=3&live=false"

Ativar o caminho do agendador em modo de simulação:

Para ativar o caminho do agendador em modo de simulação, utiliza o seguinte comando:

your-command --dry-run

Isto irá permitir-te verificar o que aconteceria sem efetuar alterações reais.

Exemplo de utilização

Aqui está um exemplo de como utilizar o comando:

your-command --dry-run --path /caminho/do/agendador

Isto irá simular a ativação do agendador no caminho especificado.

Notas

• Certifica-te de que tens as permissões necessárias para executar o comando.
• O modo de simulação não irá fazer alterações no sistema, mas é sempre bom verificar os logs para garantir que tudo está a funcionar como esperado.

curl -X POST "http://127.0.0.1:8000/agent-scout/trigger" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true, "top_n": 5, "live": false}'

Modo de simulação

O modo de simulação devolve o resumo renderizado e o estado de entrega, mas não envia nada.

Ativar a verificação ao vivo do Hacker News para o processo atual:

your-command --live-scan

export AGENTSCOUT_LIVE_HN=true

Documentação do Projeto

Introdução

Este projeto é uma ferramenta que permite a gestão de tarefas de forma eficiente. Através de uma interface simples, podes adicionar, editar e remover tarefas.

Instalação

Para instalar o projeto, segue os passos abaixo:

1. Clona o repositório:

git clone https://github.com/usuario/projeto.git

2. Navega até à pasta do projeto:

cd projeto

3. Instala as dependências:

npm install

Uso

Para iniciar a aplicação, utiliza o seguinte comando:

npm start

A aplicação estará disponível em http://localhost:3000.

Funcionalidades

• Adicionar tarefas
• Editar tarefas
• Remover tarefas
• Marcar tarefas como concluídas

Contribuição

Se desejas contribuir para o projeto, segue os passos abaixo:

1. Cria um fork do repositório.
2. Cria uma nova branch:

git checkout -b minha-nova-funcionalidade

3. Faz as tuas alterações e commit:

git commit -m "Adiciona nova funcionalidade"

4. Envia a branch para o repositório remoto:

git push origin minha-nova-funcionalidade

5. Abre um Pull Request.

Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro LICENSE para mais informações.

curl -X POST "http://127.0.0.1:8000/agent-scout/trigger" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true, "top_n": 5, "live": true}'

Opção 3: Ativar Entrega Agendada

A entrega é opcional. O AgentScout não enviará e-mails nem chamará um webhook a menos que o corpo da requisição inclua "dry_run": false e um método de entrega esteja configurado.

Comportamento do modo de entrega:

• AGENTSCOUT_DELIVERY=gmail envia através da API do Gmail.
• AGENTSCOUT_DELIVERY=webhook publica em AGENTSCOUT_WEBHOOK_URL.
• Se AGENTSCOUT_DELIVERY não estiver definido, o AgentScout utiliza o Gmail quando este está totalmente configurado, caso contrário, utiliza o webhook quando uma URL de webhook está configurada.

Entrega pelo Gmail

Utiliza o Gmail quando desejas que o AgentScout envie o resumo diário diretamente para uma caixa de entrada. Cria um cliente OAuth do Google com acesso à API do Gmail, gera um token de atualização com o escopo https://www.googleapis.com/auth/gmail.send, e depois define:

export AGENTSCOUT_DELIVERY="gmail"
export AGENTSCOUT_EMAIL_TO="you@example.com"
export AGENTSCOUT_EMAIL_FROM="you@example.com"
export AGENTSCOUT_GMAIL_CLIENT_ID="your_google_oauth_client_id"
export AGENTSCOUT_GMAIL_CLIENT_SECRET="your_google_oauth_client_secret"
export AGENTSCOUT_GMAIL_REFRESH_TOKEN="your_gmail_refresh_token"

curl -X POST "http://127.0.0.1:8000/agent-scout/trigger" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false, "top_n": 5, "live": true}'

AgentScout envia um email multipart com versões em texto simples e HTML do resumo.

Entrega via Webhook

Utiliza a entrega via webhook quando quiseres encaminhar o resumo para Slack, Linear, Jira, GitHub Issues, SendGrid, ou o teu próprio fluxo de trabalho interno.

export AGENTSCOUT_DELIVERY="webhook"
export AGENTSCOUT_WEBHOOK_URL="https://example.com/agent-brief-webhook"
export AGENTSCOUT_WEBHOOK_TOKEN="optional_bearer_token"

curl -X POST "http://127.0.0.1:8000/agent-scout/trigger" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false, "top_n": 5, "live": true}'

O webhook recebe subject, text, html, stories e next_actions.

Cloud Scheduler Hook

Implanta a API do scheduler por detrás do Cloud Run ou de outro serviço HTTP, configura a entrega do Gmail ou do webhook nesse ambiente e, em seguida, chama um destes endpoints a partir do Cloud Scheduler.

Gatilho HTTP direto:

https://YOUR_CLOUD_RUN_URL/agent-scout/trigger

Exemplo de Requisição

Este é um exemplo de como fazer uma requisição para a API.

Método

Utiliza o método POST.

URL

A URL para a requisição é:

https://api.exemplo.com/endpoint

## Cabeçalhos

Os cabeçalhos que deves incluir são:

- `Content-Type: application/json`
- `Authorization: Bearer <token>`

## Corpo da Requisição

O corpo da requisição deve ser um JSON com a seguinte estrutura:

```json
{
  "campo1": "valor1",
  "campo2": "valor2"
}

Exemplo de Requisição

Aqui está um exemplo completo de como a requisição deve parecer:

curl -X POST https://api.exemplo.com/endpoint \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
  "campo1": "valor1",
  "campo2": "valor2"
}'

Resposta

A resposta da API será um JSON com os dados solicitados. Um exemplo de resposta pode ser:

{
  "status": "sucesso",
  "dados": {
    "campo1": "valor1",
    "campo2": "valor2"
  }
}

{
  "dry_run": false,
  "top_n": 5,
  "live": true
}

Define dry_run como true enquanto testas o agendamento. Define-o como false apenas depois de configurares a entrega do Gmail ou do webhook.

Agenda de briefing recomendada para dias de semana:

0 9 * * 1-5

Pub/Sub push endpoint:

Introdução

Neste tutorial, vais aprender a configurar um endpoint de push para o Google Cloud Pub/Sub. Um endpoint de push permite que o Pub/Sub envie mensagens diretamente para a tua aplicação.

Pré-requisitos

Antes de começares, certifica-te de que tens:

• Uma conta no Google Cloud.
• O Google Cloud SDK instalado e configurado.
• Um projeto no Google Cloud.

Criar um tópico

Primeiro, deves criar um tópico no Pub/Sub. Para isso, utiliza o seguinte comando:

gcloud pubsub topics create NOME_DO_TÓPICO

Substitui NOME_DO_TÓPICO pelo nome que desejas dar ao teu tópico.

Criar um subscription

Agora, deves criar uma subscription para o teu tópico. Utiliza o seguinte comando:

gcloud pubsub subscriptions create NOME_DA_SUBSCRIPTION --topic=NOME_DO_TÓPICO --push-endpoint=URL_DO_ENDPOINT --ack-deadline=10

Substitui NOME_DA_SUBSCRIPTION pelo nome que desejas dar à tua subscription, NOME_DO_TÓPICO pelo nome do tópico que criaste anteriormente e URL_DO_ENDPOINT pela URL do teu endpoint de push.

Configurar o endpoint

O teu endpoint deve ser capaz de receber requisições HTTP POST. A mensagem será enviada no corpo da requisição. Aqui está um exemplo de como pode ser a estrutura da mensagem:

{
  "message": {
    "data": "BASE64_ENCODED_DATA",
    "attributes": {
      "attribute1": "value1",
      "attribute2": "value2"
    }
  },
  "subscription": "projects/PROJECT_ID/subscriptions/NOME_DA_SUBSCRIPTION"
}

Certifica-te de que o teu endpoint responde com um código de estado HTTP 200 para confirmar que a mensagem foi recebida com sucesso.

Testar o endpoint

Para testar o teu endpoint, podes publicar uma mensagem no tópico utilizando o seguinte comando:

gcloud pubsub topics publish NOME_DO_TÓPICO --message="Mensagem de teste"

Verifica se o teu endpoint recebeu a mensagem corretamente.

Conclusão

Neste tutorial, aprendeste a configurar um endpoint de push para o Google Cloud Pub/Sub. Agora, a tua aplicação pode receber mensagens diretamente do Pub/Sub.

https://YOUR_CLOUD_RUN_URL/agent-scout/pubsub

Para Pub/Sub push, envia a mesma carga útil JSON como dados de mensagem codificados em base64.

Exemplo de Saída

{
  "subject": "AgentScout Hacker News brief - 2026-06-08",
  "watch_mode": "sample",
  "stories": [
    {
      "title": "Show HN: An open-source framework for reliable AI agent workflows",
      "points": 428,
      "comments": 116,
      "summary": "Framework discussion with practical tradeoffs around orchestration, retries, state, and tool execution."
    }
  ],
  "next_actions": [
    "Open the highest-comment thread and extract objections or implementation patterns."
  ]
}