Crie um agente de resumo de monitoramento com execução programada: 4 componentes e guia de seleção de interfaces

Nota do autor: vamos explorar os quatro componentes de um Agent de monitoramento e resumo executado em horários programados, mostrar como desacoplar a camada de invocação do modelo de um SDK específico usando uma interface compatível com OpenAI e apresentar um exemplo funcional em Python.

A OpenRouter publicou recentemente um tutorial que usa o @openrouter/agent 0.11.0 em TypeScript para criar um AI Agent que fica em execução e, em horários programados, monitora o Hacker News e gera resumos automaticamente. É um cenário bastante comum: muitas equipes querem algo parecido para reunir, todas as manhãs, notícias do setor, novidades da concorrência ou posts em destaque de comunidades de tecnologia. Vamos aproveitar esse exemplo para apresentar uma arquitetura genérica para um Agent de monitoramento e resumo, sem dependência de um SDK específico.

Este artigo não é uma reprodução daquele tutorial. Como apenas informações resumidas sobre o tutorial original foram divulgadas, não vamos especular sobre os detalhes da implementação. Nosso foco é mais amplo: quais são os componentes de um Agent de monitoramento e resumo e como projetar a camada de invocação do modelo para trocar de modelo e de provedor a qualquer momento.

O que você vai aprender: ao final, você vai conhecer a estrutura em quatro etapas — acionamento agendado, obtenção de dados, resumo pelo modelo e saída dos resultados — e terá uma implementação em Python baseada em uma interface compatível com OpenAI, pronta para adaptar.

Pontos principais de um Agent de monitoramento e resumo

A tabela abaixo reúne as conclusões do artigo. Nas próximas seções, vamos detalhar cada ponto.

Os quatro componentes de um Agent de monitoramento e resumo

Um «Agent permanente» é, na prática, um fluxo de processamento acionado repetidamente por um agendador. Ele não precisa de um raciocínio complexo em várias etapas, mas precisa ser muito estável, já que ninguém estará acompanhando sua execução o tempo todo. Dividi-lo em quatro componentes com responsabilidades bem definidas é fundamental para mantê-lo funcionando de forma confiável no longo prazo.

Esses quatro componentes se comunicam apenas por meio de estruturas de dados simples: o coletor entrega uma «lista de itens», o gerador produz um «texto de resumo» e o componente de saída recebe esse texto. A vantagem é que qualquer problema pode ser identificado separadamente: se a qualidade do resumo estiver ruim, basta ajustar o gerador; se o envio falhar, é só verificar o componente de saída.

Na primeira versão, muita gente coloca toda a lógica em um único script. Ele funciona, mas é difícil de manter. Quando chega a hora de trocar o Hacker News pelo GitHub Trending, ou de mudar para um modelo de outro fornecedor, é preciso alterar grande parte do código. Com os componentes separados, adicionar uma fonte de informação exige apenas um novo coletor, enquanto trocar o modelo requer apenas uma mudança de configuração.

Como escolher o acionamento agendado do Agent de monitoramento e resumos

É o acionamento agendado que mantém o Agent funcionando de forma contínua. O tutorial da OpenRouter usa um processo permanente, mas há várias opções de implantação. A escolha depende principalmente da infraestrutura que você já tem.

Para tarefas de resumo executadas a cada hora ou uma vez por dia, o cron do sistema com um script que encerra ao terminar costuma oferecer o melhor custo-benefício. Essa abordagem evita o aumento de memória de um processo permanente e, em caso de falha, uma nova execução será iniciada no próximo horário. Um processo permanente só costuma valer a pena quando você precisa de monitoramento a cada poucos minutos ou quer compartilhar recursos mais pesados entre execuções.

Como desacoplar a camada de invocação do modelo no Agent de resumo de monitoramento

Este é o ponto central do artigo. O tutorial da OpenRouter usa seu próprio SDK, o @openrouter/agent, o que facilita bastante os primeiros passos. Porém, as informações públicas disponíveis não esclarecem se o SDK aceita endpoints personalizados compatíveis com a OpenAI, e nós também não verificamos isso. Por isso, não vamos abordar como conectá-lo a outras plataformas.

Vamos seguir outro caminho: em vez de fazer o código de negócio depender diretamente do SDK de Agent de um provedor, adicionamos uma camada fina de interface de resumo. O código de negócio chama apenas summarize(items); a escolha do modelo e do endpoint fica por conta dessa camada, conforme a configuração.

Design da interface de invocação do Agent de resumo de monitoramento

O design dessa camada segue três princípios simples, mas que podem evitar muito retrabalho no futuro:

• Expor apenas a semântica de negócio: disponibilizar summarize(items) -> str, sem deixar parâmetros de baixo nível, como messages e temperature, vazarem para o código de negócio.
• Padronizar o protocolo interno: usar o formato Chat Completions compatível com a OpenAI, lendo base_url, api_key e model de variáveis de ambiente.
• Ter uma alternativa em caso de falha: tentar novamente um número limitado de vezes e, se a chamada continuar falhando, retornar a lista original de títulos. Assim, pelo menos haverá um resultado legível naquele dia.

Escolhemos o protocolo compatível com a OpenAI como base porque ele já se tornou um formato praticamente universal: o SDK oficial e muitas ferramentas de terceiros permitem alterar o base_url. Desde que o servidor seja compatível com esse formato, trocar de modelo se resume a alterar uma linha de configuração.

Com esse design, plataformas agregadoras como a APIYI podem ser uma opção para a camada de invocação do modelo. A APIYI é compatível com o formato da API da OpenAI e aceita conexões pelo SDK oficial; para trocar de modelo, basta alterar seu nome. Para um Agent de resumo de monitoramento, isso significa que você pode comparar os resumos de diferentes modelos com a mesma chave API, sem precisar escrever uma integração separada para cada provedor.

O que considerar ao escolher um modelo para resumos de monitoramento

Resumir informações parece simples, mas cada fonte pode exigir capacidades bem diferentes do modelo. Ainda não temos dados de testes sistemáticos para esse tipo de tarefa, então não vamos apontar “o melhor modelo”. Em vez disso, reunimos os fatores que vale a pena considerar na decisão.

💡 Dica para escolher: não existe uma resposta padrão para o melhor modelo de resumo. A forma mais confiável de decidir é comparar alguns modelos por alguns dias usando suas fontes reais. Uma opção é usar a APIYI apiyi.com para alternar entre candidatos com o mesmo código, comparar a consistência do formato e a qualidade da escrita em chinês e, então, decidir qual usar no longo prazo.

Primeiros passos com um agente de monitoramento e resumo

Vamos implementar uma versão mínima funcional em Python. Como fonte de informações, usaremos a API pública do Hacker News (hacker-news.firebaseio.com/v0), mantendo o mesmo cenário do tutorial do OpenRouter para facilitar a comparação.

Exemplo mínimo: buscar e resumir

O código abaixo busca os títulos dos 10 posts mais populares do Hacker News e pede ao modelo que gere um resumo em chinês. Assim, podemos verificar se todo o fluxo está funcionando:

import requests
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # OpenAI 兼容端点
)

HN = "https://hacker-news.firebaseio.com/v0"
ids = requests.get(f"{HN}/topstories.json", timeout=10).json()[:10]
titles = [requests.get(f"{HN}/item/{i}.json", timeout=10).json().get("title", "") for i in ids]

resp = client.chat.completions.create(
    model="gpt-4o-mini",  # 示例模型名，以平台模型列表为准
    messages=[{"role": "user", "content": "用中文分 3 点总结这些热帖的主题：\n" + "\n".join(titles)}]
)
print(resp.choices[0].message.content)

Esse código funciona, mas ainda não está pronto para rodar continuamente: ele não elimina duplicatas, não trata falhas e tem o modelo e o endpoint definidos diretamente no código. A versão completa abaixo separa os quatro componentes e adiciona o gerenciamento de estado.

import json
import os
import time
from pathlib import Path

import openai
import requests

HN = "https://hacker-news.firebaseio.com/v0"
STATE_FILE = Path(os.getenv("STATE_FILE", "seen_ids.json"))
TOP_N = int(os.getenv("TOP_N", "30"))


# ---------- 数据获取器 ----------
def fetch_new_stories(seen: set) -> list:
    ids = requests.get(f"{HN}/topstories.json", timeout=10).json()[:TOP_N]
    items = []
    for i in ids:
        if i in seen:
            continue
        item = requests.get(f"{HN}/item/{i}.json", timeout=10).json() or {}
        if item.get("title"):
            items.append({"id": i, "title": item["title"],
                          "url": item.get("url", ""), "score": item.get("score", 0)})
    return items


# ---------- 状态管理 ----------
def load_seen() -> set:
    return set(json.loads(STATE_FILE.read_text())) if STATE_FILE.exists() else set()

def save_seen(seen: set) -> None:
    STATE_FILE.write_text(json.dumps(sorted(seen)[-2000:]))  # 只保留最近的 ID


# ---------- 摘要器（模型调用层） ----------
class Summarizer:
    def __init__(self):
        self.client = openai.OpenAI(
            api_key=os.environ["LLM_API_KEY"],
            base_url=os.getenv("LLM_BASE_URL", "https://api.apiyi.com/v1"),
        )
        self.model = os.getenv("SUMMARY_MODEL", "gpt-4o-mini")

    def summarize(self, items: list, retries: int = 2) -> str:
        lines = "\n".join(f"- [{x['score']}] {x['title']}" for x in items)
        prompt = ("你是技术资讯编辑。请用中文把下面的 Hacker News 新热帖归纳为 3-5 个主题，"
                  "每个主题一句话，并列出最值得关注的 3 条标题。\n" + lines)
        for attempt in range(retries + 1):
            try:
                resp = self.client.chat.completions.create(
                    model=self.model,
                    messages=[{"role": "user", "content": prompt}],
                    max_tokens=800,
                )
                return resp.choices[0].message.content
            except Exception as e:
                print(f"摘要失败（第 {attempt + 1} 次）：{e}")
                time.sleep(2 ** attempt)
        return "【模型暂不可用，以下为原始标题】\n" + lines  # 降级输出


# ---------- 输出器 ----------
def deliver(text: str) -> None:
    webhook = os.getenv("WEBHOOK_URL")
    if webhook:
        try:
            requests.post(webhook, json={"text": text}, timeout=10).raise_for_status()
            return
        except Exception as e:
            print(f"推送失败，改为落盘：{e}")
    Path(f"digest-{time.strftime('%Y%m%d-%H%M')}.md").write_text(text, encoding="utf-8")


# ---------- 一次运行（由定时器触发） ----------
def run_once() -> None:
    seen = load_seen()
    items = fetch_new_stories(seen)
    if not items:
        print("没有新条目，本轮跳过")
        return
    deliver(Summarizer().summarize(items))
    save_seen(seen | {x["id"] for x in items})


if __name__ == "__main__":
    run_once()

A versão completa tem algumas decisões de projeto que vale destacar. Primeiro, Summarizer expõe apenas summarize: o nome do modelo, o endpoint e a chave vêm de variáveis de ambiente. Esse é o desacoplamento da camada de invocação do modelo mencionado anteriormente. Além disso, o arquivo de estado mantém apenas um conjunto recente de IDs, evitando que cresça indefinidamente. Por fim, se o modelo falhar, os títulos originais são usados como saída; se o envio falhar, o resultado é salvo em disco. Assim, cada execução deixa um registro rastreável.

Agendamento do Agent de resumos de monitoramento

O script foi projetado para executar uma vez e encerrar, então pode ser agendado diretamente pelo cron do sistema. A configuração abaixo executa o script todos os dias, às 8h e às 20h:

# crontab -e
0 8,20 * * * cd /opt/hn-digest && LLM_API_KEY=xxx SUMMARY_MODEL=gpt-4o-mini /usr/bin/python3 agent.py >> run.log 2>&1

Se quiser comparar outro modelo, basta alterar SUMMARY_MODEL para o nome desejado, sem mudar uma linha do código. Em produção, é recomendável guardar a chave em um arquivo .env ou em um serviço de gerenciamento de segredos, em vez de escrevê-la diretamente no crontab.

🚀 Dica para começar: primeiro, use o exemplo mínimo para confirmar que tudo está funcionando. Depois, passe para a versão completa e configure o cron. A APIYI apiyi.com oferece créditos gratuitos de teste para novos usuários. Com uma única chave, você pode alternar entre modelos como OpenAI, Claude e Gemini, o que facilita a comparação dos resumos durante a prototipagem.

Perguntas frequentes (FAQ)

Principais pontos sobre o Agent de resumo e monitoramento

• Estrutura em quatro etapas: acionamento agendado, coleta de dados, resumo pelo modelo e envio dos resultados são independentes, facilitando substituições e a identificação de erros
• Executar e encerrar é mais confiável: para resumos pouco frequentes, cron com um script de execução única dá menos trabalho do que um processo permanente
• O estado determina a qualidade: registre os IDs já vistos e resuma apenas os novos itens a cada rodada, evitando repetições e desperdício
• Desacople a camada de invocação: a lógica da aplicação depende apenas da interface summarize; modelo, endpoint e chave vêm da configuração
• Use um protocolo compatível como base: o formato compatível com OpenAI permite trocar de modelo alterando uma única variável de ambiente
• Escolha o modelo com testes práticos: compare contexto, capacidade de seguir instruções, idioma, custo e estabilidade. Na APIYI apiyi.com, você pode alternar entre modelos e testá-los com o mesmo código
• Tenha alternativas para falhas: se o modelo falhar, apresente os títulos originais; se o envio falhar, salve o resultado em disco

Conclusão

Para criar um Agent de monitoramento e resumo com execução agendada, o essencial não é usar um framework complexo, mas organizar bem a estrutura:

1. Separação de componentes: acionamento, coleta, resumo e envio se conectam por estruturas de dados simples, e cada etapa pode ser testada separadamente
2. Desacoplamento de interfaces: uma camada simples de resumo isola o SDK específico, usando o protocolo compatível com OpenAI por baixo
3. Estabilidade em primeiro lugar: deduplicação, novas tentativas e alternativas para falhas são essenciais em tarefas executadas sem supervisão

O tutorial da OpenRouter sobre o Hacker News oferece um ótimo exemplo de aplicação. Já a arquitetura genérica deste artigo permite levar a mesma ideia para qualquer fonte de informação e qualquer modelo. Como próximo passo, coloque o fluxo para funcionar com um exemplo mínimo, configure o cron para executá-lo por alguns dias e avalie a qualidade dos resumos antes de escolher o modelo para uso contínuo.

Recomendamos usar a APIYI apiyi.com para testar rapidamente os resultados: com uma única chave API, você pode alternar entre vários modelos populares. Novos usuários também recebem créditos gratuitos para testes comparativos durante a fase de prototipagem.

📚 Referências

1. Resumo do tutorial da OpenRouter: como usar o Agent SDK para criar um agente de IA permanente que monitora o Hacker News
2. Link: aihot.news/items/upl3hjjdokqe13w3ieo9opr0v

3. Descrição: inspiração para este artigo, apresenta a criação de um agente agendado em TypeScript com @openrouter/agent 0.11.0

4. API oficial do Hacker News: interface pública de dados somente para leitura

5. Link: github.com/HackerNews/API

6. Descrição: documenta os campos de endpoints como topstories e item, usados como fonte de dados nos exemplos deste artigo

7. OpenAI Python SDK: biblioteca cliente oficial

8. Link: github.com/openai/openai-python
9. Descrição: mostra como conectar endpoints compatíveis usando o parâmetro base_url

Autor: Equipe técnica da APIYI
Discussões técnicas: entre em contato conosco pela página inicial do site da APIYI. Para mais informações sobre integração, acesse a central de documentação em docs.apiyi.com

Artigos relacionados

• Apagão de 7 horas e 52 minutos no Google Cloud em Londres: não deixe seu negócio depender de um único modelo: Uma zona de disponibilidade do Google Cloud em Londres ficou sem energia por 7 horas e 52 minutos, e o DeepSeek também sofreu uma interrupção de 4 horas e 52 minutos há alguns dias; como os modelos são apenas uma etapa do fluxo de trabalho, é mais útil deixar uma segunda e uma terceira opção prontas do que esperar o serviço upstream se recuperar.
• Comparativo entre tarefas agendadas do ChatGPT, agentes do Codex e automação completa do Dot: 6 diferenças fundamentais entre 3 tipos de automação: Compare as tarefas agendadas do ChatGPT, o agente Codex e o ChatGPT Dot quanto à automação total, aos custos e à confiabilidade, considerando acionamento, execução e coordenação contínua, e apresente recomendações de escolha.
• Resolver o problema das faixas coloridas na geração de imagens com o GPT Image 2.5: diagnóstico de 5 tipos de faixas coloridas e guia para escolher o parâmetro quality: Analise os 5 tipos e causas de faixas coloridas e pontos de ruído coloridos ao gerar imagens com gpt-image-2.5-sunburst, explique a relação entre os níveis de qualidade e o orçamento computacional, apresente a conversão “2.5 high ≈ 2 medium”, a comparação de custos e soluções econômicas.