Agente Release Radar

O Release Radar é um agente de briefing de dependências sempre ativo, construído com o Google ADK. Lê o requirements.txt ou o package.json, verifica as dependências mapeadas contra as releases do GitHub e reporta apenas as alterações que requerem atenção: breaking changes, deprecações, correções de segurança, releases yanked (removidas) e atualizações de versão major.

A aplicação é executada de forma interativa no ADK Web ou como um serviço FastAPI agendado. O modo de exemplo é determinístico e não faz pedidos ao GitHub. A entrega agendada assume, por predefinição, o modo dry-run e permanece desativada até que existam as definições do Gmail ou do webhook.

Funcionalidades

• Análise de manifestos: Lê os requirements de Python, bem como as dependências de runtime e de desenvolvimento do npm.
• Análise de releases do GitHub: Utiliza a GitHub REST API com um token opcional.
• Ordenação por impacto: Pontua sinais de segurança, breaking changes, releases yanked, versões major e deprecações.
• Filtragem de ruído de patches: Descarta releases de patch e minor rotineiras sem sinal de impacto.
• Briefings em texto e HTML: Agrupa as alterações por dependência, com o delta de versão, o motivo, o impacto e a ligação para a release.
• Agente Google ADK: Expõe o root_agent para perguntas interativas sobre dependências.
• Hooks de agendamento: Aceita acionadores HTTP diretos e Pub/Sub.
• Entrega opcional (opt-in): Suporta o Gmail e webhooks genéricos apenas quando configurados explicitamente.

Como Funciona

1. O radar.py analisa um manifesto e mapeia pacotes conhecidos ou URLs de dependências do GitHub para repositórios.
2. O modo de exemplo carrega dados determinísticos com o formato do GitHub. O modo em direto obtém as releases recentes do GitHub.
3. O ranker.py classifica as notas de release e filtra o ruído rotineiro.
4. O delivery.py renderiza as releases selecionadas em texto e HTML.
5. O ADK Web devolve o briefing de forma interativa, enquanto o scheduler_api.py expõe as rotas HTTP e Pub/Sub agendadas.
6. O agendador envia apenas quando dry_run=false e existe configuração do Gmail ou de um webhook.

Os módulos de código-fonte utilizam a biblioteca padrão de Python para a análise de manifestos, o acesso ao GitHub, a renderização e a entrega. O FastAPI fornece a interface de agendamento, e o Google ADK fornece o agente interativo.

Requisitos

• Python 3.10+
• Uma chave da Gemini API para o ADK Web
• Um ficheiro requirements.txt ou package.json do projeto para análises em direto
• Opcionalmente, um token do GitHub para limites de taxa da API mais elevados
• Opcionalmente, credenciais OAuth do Gmail ou um URL de webhook para a entrega

Instalação

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

Executar no ADK Web

Comece com dados de exemplo determinísticos:

adk web .

Abra o ADK Web, selecione release_radar_agent e experimente:

Give me today's dependency release brief.

Para analisar um projeto real, defina um caminho absoluto para o manifest e ative os pedidos reais ao GitHub antes de iniciar o ADK Web:

export RELEASE_RADAR_MANIFEST="/absolute/path/to/requirements.txt"
export RELEASE_RADAR_LIVE_GITHUB=true
export RELEASE_RADAR_GITHUB_TOKEN="optional_github_token"
adk web .

O Release Radar reconhece URLs diretas de dependências do GitHub e pacotes comuns como Pydantic, FastAPI, Requests, OpenAI, Anthropic, Google ADK, LangChain, React, Vite e Zod. As dependências não mapeadas aparecem nas notas da análise em vez de interromper o briefing.

Executar a API do Scheduler

Defina o manifesto do projeto no ambiente do serviço e, em seguida, inicie o backend a partir deste diretório:

export RELEASE_RADAR_MANIFEST="/workspace/requirements.txt"
export RELEASE_RADAR_LIVE_GITHUB=true
uvicorn scheduler_api:app --host 0.0.0.0 --port 8000

Pré-visualize o briefing de exemplo determinístico sem entrega:

curl "http://127.0.0.1:8000/release-radar/dry-run?top_n=5&live=false"

Analise um manifesto através do caminho do scheduler, mantendo a entrega desativada:

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

O servidor lê o seu manifesto apenas a partir de RELEASE_RADAR_MANIFEST, pelo que os payloads dos pedidos não podem selecionar ficheiros locais arbitrários. O caminho tem de existir dentro do serviço de agendamento. Defina RELEASE_RADAR_GITHUB_TOKEN no ambiente do serviço quando analisar muitos repositórios.

Ativar a entrega

A entrega tem dois mecanismos de proteção independentes. O pedido tem de definir "dry_run": false, e um fornecedor tem de estar totalmente configurado. Sem ambas as condições, a API devolve um estado de ignorado e não envia nada.

Gmail

Crie um cliente Google OAuth com acesso à Gmail API e um refresh token utilizando o âmbito https://www.googleapis.com/auth/gmail.send e, em seguida, defina:

export RELEASE_RADAR_DELIVERY="gmail"
export RELEASE_RADAR_EMAIL_TO="you@example.com"
export RELEASE_RADAR_EMAIL_FROM="you@example.com"
export RELEASE_RADAR_GMAIL_CLIENT_ID="your_google_oauth_client_id"
export RELEASE_RADAR_GMAIL_CLIENT_SECRET="your_google_oauth_client_secret"
export RELEASE_RADAR_GMAIL_REFRESH_TOKEN="your_gmail_refresh_token"

Webhook

Use um webhook para encaminhar o briefing para o Slack, o Linear, o Jira ou um fluxo de trabalho interno:

export RELEASE_RADAR_DELIVERY="webhook"
export RELEASE_RADAR_WEBHOOK_URL="https://example.com/dependency-brief"
export RELEASE_RADAR_WEBHOOK_TOKEN="optional_bearer_token"

Depois de configurar um fornecedor, acione uma entrega em direto:

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

Cloud Scheduler

Implemente o serviço FastAPI atrás do Cloud Run ou de outro serviço HTTP. O Cloud Scheduler pode chamar o endpoint direto:

https://YOUR_SERVICE_URL/release-radar/trigger

Também pode publicar JSON codificado em base64 no endpoint de push do Pub/Sub:

https://YOUR_SERVICE_URL/release-radar/pubsub

O horário de uma manhã de dia útil é:

0 9 * * 1-5

Mantenha dry_run definido como true enquanto valida a implementação.

Teste

python3 -m pytest always_on_agents/release_radar_agent/tests/unit -q

Os testes utilizam releases de exemplo deterministas e aplicam patch ao acesso à rede quando verificam a segurança da entrega.

Esta aplicação é licenciada ao abrigo da licença Apache-2.0, através da licença presente na raiz do repositório.