# Agente de Briefing Hacker News Sempre Ativo

> O AgentScout é um agente de briefing sempre ativo do Hacker News que analisa histórias relevantes sobre agentes de IA, MCP, automação de fluxo de trabalho e aplicações LLM.

- Fonte: https://doutorai.pt/apps/always-on-hn-briefing-agent
- Categoria: Agentes Sempre Ligados
- Dificuldade: Avançado
- Modelos: Gemini
- Frameworks: Google ADK
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: AGENTSCOUT_GMAIL_REFRESH_TOKEN, AGENTSCOUT_WEBHOOK_TOKEN, GOOGLE_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# 📰 Agente de Briefing Sempre Ativo do Hacker News

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.

![Arquitetura do Agente de Briefing Sempre Ativo do Hacker News](/assets/apps-img/eed17d1d323e2f28.png)

## 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

```bash
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.

```bash
adk web .
```

# Aceder ao ADK Web UI

Abre o ADK Web UI e seleciona `always_on_hn_briefing_agent`.

Experimenta comandos como:

```text
Give me today's AgentScout brief.
```

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

```text
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:

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

```markdown
# Pré-visualizar uma execução agendada

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

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

```markdown
# 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:

```bash
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:

```bash
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.
```

```bash
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}'
```

```markdown
# 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:

```bash
your-command --live-scan
```
```

```bash
export AGENTSCOUT_LIVE_HN=true
```

```markdown
# 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:
   ```bash
   git clone https://github.com/usuario/projeto.git
   ```
2. Navega até à pasta do projeto:
   ```bash
   cd projeto
   ```
3. Instala as dependências:
   ```bash
   npm install
   ```

## Uso

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

```bash
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:
   ```bash
   git checkout -b minha-nova-funcionalidade
   ```
3. Faz as tuas alterações e commit:
   ```bash
   git commit -m "Adiciona nova funcionalidade"
   ```
4. Envia a branch para o repositório remoto:
   ```bash
   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.
```

```bash
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:

```bash
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.

```bash
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:

```text
https://YOUR_CLOUD_RUN_URL/agent-scout/trigger
```

```markdown
# 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:

```bash
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:

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

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

```markdown
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:
```

```text
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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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.

```text
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

```json
{
  "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."
  ]
}
```

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/always-on-hn-briefing-agent