Construindo um Agente Descartável para Notion com Modelos Acessíveis

TL;DR: Construímos um trabalhador HTTP de uma única vez que se comunica com o Notion através do MCP. A versão um funcionou. A versão dois ficou mais barata e mais legível, mas falhou de uma nova maneira. O suporte estava bom. A superfície da ferramenta, o modelo e o prompt não eram o mesmo problema, e continuamos tratando-os como um só.

Continuamos vendo a mesma proposta: coloque um agente na nuvem, dê-lhe ferramentas, deixe-o viver no Slack, deixe-o lembrar de você. Isso é um produto. Não é o produto que precisávamos.

Precisávamos de algo mais simples e útil. Outro serviço deveria ser capaz de dizer "leia esta página do Notion, escreva um resumo em algum lugar, pare." Sem histórico de chat. Sem personalidade que se acumula ao longo das semanas. Sem um processo sempre ativo. Se ninguém estiver chamando, não deve custar nada.

Começamos a chamar essa forma de agente de uma única vez. Uma solicitação HTTP. Ferramentas para essa solicitação. Um resultado JSON. Então a instância pode desaparecer.

Este é o caminho que realmente percorremos: primeira versão funcional, o que deu errado, o fork do Markdown e os truques mais baratos que importaram mais do que trocar frameworks.

O trabalho nunca foi "construir um chatbot"

A primeira tarefa real foi quase entediante. Uma vez por semana, puxar um resumo de habilidade do Notion, extrair o que importava e anexá-lo a uma página de digestão. Os chamadores nomeariam páginas em inglês. Eles não colariam ids do Notion. Se um nome fosse ambíguo, o agente deveria se recusar a escrever em vez de adivinhar.

Se esse ciclo estiver errado, as pessoas param de confiar na gravação. Se for caro, ninguém agenda. Se precisar de um humano para cuidar de um terminal, não é um sistema.

Portanto, as restrições eram sociais tanto quanto técnicas:

• Um chamador externo possui a programação. O agente não.
• O agente deve ser autorizado a usar ferramentas, não apenas falar sobre elas.
• Segredos permanecem no ambiente, nunca no corpo da solicitação.
• Tempo ocioso deve ser gratuito.

Pergunta que você provavelmente fará: por que não um script cron que acesse a API do Notion diretamente?

Porque a tarefa muda a cada chamada. Esta semana é um resumo semanal. Na próxima semana é "liste as linhas em andamento e não escreva." Não queríamos um novo arquivo Python por trabalho. Queríamos um único trabalhador que aceita um prompt mais uma lista de servidores de ferramentas.

Armadilha comum: começar a partir de um agente de codificação (shell, arquivos, memória, um loop de aprendizado) e tentar reduzi-lo a um trabalhador de solicitação/resposta. Você passa meses deletando recursos que nunca quis.

A forma que nos comprometemos

O ciclo é curto de propósito.

caller
  |  POST /run  { prompt do sistema, prompt do usuário, quais ferramentas }
v
agente de uma única vez  (começa se necessário, morre quando ocioso)
  |  loop de modelo + ferramenta
  v
servidor MCP para Notion
  |  token de integração
  v
API do Notion
  |
  +--> JSON de volta: resultado, ferramentas usadas, tokens, custo

Algumas escolhas surgiram dessa imagem.

HTTP, síncrono. O chamador espera. Um resumo semanal pode esperar dois minutos. Não queríamos uma fila de trabalho para a v1.

O agente não é o cliente do Notion. O Notion (e depois Slack, GitHub, o que for) vive atrás do MCP: um pequeno servidor que expõe ferramentas. A imagem do agente permanece leve. O token do Notion nunca entra no processo do agente como "o cabeçalho do chamador."

Pesquisar primeiro. Os chamadores dizem "Habilidade Semanal", não um id de 32 caracteres. O modelo pesquisa, escolhe uma correspondência de título e para se não conseguir.

Um modelo padrão barato por trás de um gateway estilo OpenRouter. Não queríamos uma conta do Claude em cada gatilho interno. O primeiro padrão foi um modelo flash DeepSeek muito barato, na ordem de alguns centavos por milhão de tokens.

Decisão: mantenha o suporte leve (valide a solicitação, anexe ferramentas, execute o loop, retorne JSON). Coloque inteligência no modelo, no servidor de ferramentas e no prompt. Se a qualidade for ruim, mudamos esses três antes de mudarmos o loop.

Essa última frase parece óbvia. Nós quase a violamos.

O que olhamos e ignoramos

Um MCP Notion hospedado

O conector hospedado do Notion é construído para o Claude Desktop e clientes semelhantes. Ele quer OAuth. Queríamos um token de integração interno em um armazenamento secreto e um servidor que pudéssemos executar ao lado do agente. A auto-hospedagem do MCP oficial do Notion foi o caminho entediante que combinou com isso.

Identidade para cada chamador

A versão "correta" na nuvem é: cada chamador tem uma conta de serviço, emite um token de curta duração, a plataforma o verifica. Isso é ótimo quando todos os chamadores vivem na sua nuvem. É miserável quando o próximo chamador é um script em um laptop ou um trabalho de terceiros.

Enviamos uma chave de API compartilhada no agente em vez disso. O ingresso na nuvem é aberto. O aplicativo verifica o cabeçalho e falha de forma segura. O onboarding é "aqui está uma chave." A revogação é "gire a chave."

Compensação: você perde a identidade por chamador até crescer um conjunto de chaves. Aceitamos isso para a v1.

Um suporte mais pesado

Quando a qualidade oscilou, o movimento tentador foi "usar um agente real": algo com memória, habilidades, um terminal, uma personalidade que melhora. Olhamos com atenção para essa família (os tempos de execução persistentes e auto-melhoradores que as pessoas querem dizer quando dizem que querem agentes da classe Hermes).

Eles são bons em serem companheiros. Eles são a forma errada para "POST, trabalhar, retornar, parar." Eles querem estado em disco. Eles querem ficar ativos. Eles aumentariam nossa conta do Cloud Run e nosso modelo de ameaça para um problema que não tínhamos.

Decisão: não troque o loop porque o modelo não consegue nomear uma ferramenta. Um loop leve mais OpenRouter já é o suporte. A qualidade vive um nível acima.

Incorporando o trabalho de habilidade semanal no prompt do sistema

Este é um ponto ideológico, e apareceu em um pedido real.

Tínhamos um trabalhador genérico. Alguém enviou uma página específica do Notion e uma pergunta específica ("resuma as tarefas em andamento"). A solução fácil é enfiar o nome daquela página, aquela propriedade de Status, aquela persona no prompt do sistema.

Esse prompt então se torna inutilizável para o próximo trabalho. O agente não é mais de uma única vez e genérico. É um bot de habilidade semanal vestindo um casaco genérico.

O padrão que agora seguimos: duas camadas.

1. Como operar as ferramentas (estável). Pesquisar por nome. Ler antes de escrever. Não inventar ids. Se o markdown mostrar um stub de banco de dados, consultar o banco de dados. Não escreva a menos que solicitado.
2. O que fazer nesta execução (o chamador). A tarefa real vive no prompt do usuário.

Usuários do Claude Desktop mal escrevem a camada 1, porque um modelo forte a infere da lista de ferramentas. Um modelo barato não fará isso. A camada 1 precisa ser explícita, e ainda assim não deve conter o título da página desta semana.

Versão um: ferramentas nomeadas e um monte de JSON

A primeira MVP foi honesta e um pouco feia.

• MCP oficial do Notion, com uma lista plana de ferramentas nomeadas (search, retrieve page, append blocks, e amigos).
• O modelo podia ver esses nomes e chamá-los.
• As leituras voltaram como as árvores de bloco JSON brutas do Notion.
• Modelo padrão: a ID de classe flash mais barata que pudéssemos apontar.
• Guardrails: 12 passos do modelo, 20 chamadas de ferramentas, dois minutos no relógio.
• Infra: dois pequenos contêineres que escalam para zero. A API do Notion é gratuita para integrações internas. A conta que importa são os tokens.

Funcionou. A pesquisa encontrou páginas pelo título. Um resumo foi anexado. Uma execução bem-sucedida que registramos foi da ordem de 40.000 tokens de entrada, algumas centenas de tokens de saída e cerca de um quarto de centavo.