A maioria dos tutoriais sobre agentes Claude termina no "Olá, mundo".
Eles mostram como fazer o Claude chamar uma ferramenta. Como configurar um loop básico. Como obter uma resposta autônoma para uma tarefa simples de brinquedo.
Aí você tenta construir algo real e tudo desmorona.
A tarefa é ambígua demais. O agente trava. As saídas são inconsistentes. A sessão termina e nada foi salvo. Você começa do zero na próxima vez.
A lacuna entre um agente Claude que funciona em um tutorial e um agente Claude que funciona em produção não é uma lacuna na capacidade do Claude.
É uma lacuna em como o agente foi projetado.
Este guia fecha essa lacuna completamente.
Ao final, você terá um agente Claude executando um fluxo de trabalho real de forma confiável. Não uma demonstração. Não uma tarefa de brinquedo. Um fluxo de trabalho que produz saídas consistentes, lida com casos extremos com elegância, melhora com o tempo e é executado sem que você precise iniciar cada etapa.
O Que Torna um Agente do Mundo Real Diferente
Antes de construir qualquer coisa, entenda o que separa um agente do mundo real de um agente de tutorial.
Um agente de tutorial executa uma tarefa limpa com entradas limpas e produz uma saída limpa. A tarefa é bem definida. As entradas são fornecidas no formato exato esperado. Nada inesperado acontece. O sucesso é binário e óbvio.
Um agente do mundo real executa tarefas bagunçadas com entradas bagunçadas e tem que produzir saídas úteis de qualquer maneira. A tarefa é parcialmente definida. As entradas chegam em formatos que variam. Coisas inesperadas acontecem regularmente. O sucesso é uma questão de grau e requer julgamento para ser avaliado.
Quatro propriedades determinam se um agente sobrevive ao contato com o mundo real:
Definição robusta da tarefa. O agente sabe não apenas o que fazer, mas como lidar com as vinte variações da tarefa que encontrará na prática. As instruções cobrem casos extremos, não apenas o caminho feliz.
Memória persistente. O agente acumula contexto entre as sessões. O trabalho que fez na semana passada informa o trabalho que faz hoje. Ele não começa do zero em todas as sessões.
Tratamento elegante de falhas. Quando algo dá errado, o agente se recupera em vez de parar. Ele registra o que aconteceu, tenta alternativas e alerta um humano apenas quando a recuperação é impossível.
Autoverificação de qualidade. O agente verifica suas próprias saídas em relação a padrões definidos antes de entregá-las. Ele fecha seu próprio ciclo de feedback em vez de devolver o que produziu primeiro.
A maioria dos agentes de tutorial não possui nenhuma dessas propriedades. Este guia desenvolve as quatro.
A Arquitetura do Agente
A arquitetura tem quatro componentes que trabalham juntos.
A Camada de Definição da Tarefa
Um arquivo de habilidade estruturado que define a tarefa, o processo, o tratamento de casos extremos e o padrão de qualidade. Isso não é um prompt. É uma especificação operacional completa que o agente lê antes de cada execução.
A Camada de Memória
Um banco de dados persistente que armazena o que o agente fez, o que aprendeu e o que precisa lembrar entre as sessões. Construído em SQLite via Hermes Agent ou implementado manualmente com registro baseado em arquivos.
A Camada de Execução
As chamadas reais da API Claude que fazem o trabalho. Estruturadas para usar o modelo certo, o contexto certo e as ferramentas certas para cada etapa do fluxo de trabalho.
A Camada de Qualidade
O loop de verificação que confere as saídas em relação aos padrões definidos antes de entregá-las e tenta novamente com correções específicas quando as saídas ficam aquém.
Configurando a Base
Instale as ferramentas necessárias:
Instale o Hermes Agent para orquestração e memória
git clone https://github.com/NousResearch/hermes-agent
cd hermes-agent
npm install
Instale os servidores MCP para acesso a ferramentas
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-brave-search
Configure seu ambiente:
Configuração principal
MODEL_PROVIDER=anthropic
MODEL_NAME=claude-opus-4-8
ANTHROPIC_API_KEY=sua-chave-api-aqui
Configuração de memória — use caminhos absolutos
MEMORY_BACKEND=sqlite
MEMORY_PATH=/Users/seunome/agent-data/memory.db
Configuração do agendador
ENABLE_SCHEDULER=true
SCHEDULER_TIMEZONE=America/New_York
Configuração de saída — onde os resultados chegam
OUTPUT_PATH=/Users/seunome/agent-outputs
Recuperação de falhas
SKILL_RETRY_ENABLED=true
SKILL_RETRY_MAX=3
SKILL_RETRY_DELAY=300
Notificações
NOTIFICATION_GATEWAY=telegram
TELEGRAM_BOT_TOKEN=seu-token-do-bot
TELEGRAM_CHAT_ID=seu-id-do-chat
Escreva o CLAUDE.md:
Este é o arquivo mais importante em toda a configuração. Cada sessão do agente começa lendo-o. A qualidade de cada saída depende da especificidade do que está aqui.
Configuração do Agente — CLAUDE.md
Identidade e Propósito
[Descreva o que este agente faz em um parágrafo específico.
Não o que Claude faz em geral. O que este agente específico
está configurado para fazer para esta operação específica.]
Contexto Operacional
[Descreva o contexto empresarial ou pessoal em que este agente
opera. O que a pessoa que configurou este
agente faz? Quais são seus padrões e prioridades?]
Tarefas Ativas Atuais
[Liste as tarefas recorrentes específicas que este agente executa.
Para cada uma: o que faz, quando executa, como é uma boa saída.]
Permissões de Ferramentas
Você tem permissão para usar estas ferramentas autonomamente:
- Filesystem: ler e escrever em [CAMINHOS ESPECÍFICOS]
- Web search: para pesquisa em [TÓPICOS ESPECÍFICOS]
- [Outras ferramentas com escopo específico]
Você não deve:
- Escrever em qualquer caminho fora do diretório de saída configurado
- Fazer chamadas de API externas não listadas acima
- Tomar qualquer ação que afete sistemas externos sem aprovação explícita
Padrões de Qualidade
[Descreva como é uma boa saída para cada tipo de tarefa.
Inclua exemplos quando possível.
Seja específico o suficiente para que o agente possa se autoavaliar.]
Instruções de Memória
Armazene na memória:
- Cada saída significativa com data e avaliação de qualidade
- Cada caso extremo encontrado e como foi tratado
- Cada falha de qualidade e o que a causou
- Cada padrão identificado entre as saídas
Tratamento de Erros
Em falha de ferramenta: tente novamente uma vez, registre a falha, continue
com as ferramentas disponíveis.
Em falha de qualidade: tente novamente com correções específicas,
não uma reescrita completa. Máximo de três tentativas.
Em falha irrecuperável: salve o trabalho parcial,
registre a falha específica, envie notificação,
pare com elegância.
Construindo a Camada de Definição da Tarefa
A camada de definição da tarefa é onde a maioria dos agentes do mundo real falha.
As pessoas escrevem um prompt que descreve o caminho feliz e param. O agente lida bem com o caminho feliz e falha em todo o resto.
Uma definição robusta de tarefa cobre toda a realidade operacional da tarefa. Aqui está o modelo:
[NOME DA TAREFA]
Propósito
[Uma frase: o que esta habilidade realiza?]
Gatilho
[Condições exatas que fazem isso ser executado:
horário agendado, aparecimento de arquivo, comando manual, etc.]
Verificações Pré-Execução
Antes de iniciar, verifique:
- [A entrada necessária existe e está acessível]
- [As ferramentas necessárias estão conectadas e respondendo]
- [O caminho de saída é gravável]
- [A memória está acessível e atualizada]
Se alguma verificação falhar: registre a falha e pare.
Não prossiga com pré-requisitos ausentes.
Processo Principal
Etapa 1: Carregamento de Contexto
Leia o CLAUDE.md para obter contexto operacional completo.
Leia a memória em busca de histórico relevante marcado com: [TAG-DA-TAREFA]
Observe quaisquer padrões de execuções anteriores
que devam informar esta.
Etapa 2: Processamento de Entrada
[Descreva exatamente o que fazer com a entrada.
Cubra o formato PRIMÁRIO E os formatos alternativos
que aparecem na prática.]
Para formato de entrada padrão:
[Etapas exatas de processamento]
Para formato de entrada alternativo A:
[Como lidar com ele]
Para formato de entrada alternativo B:
[Como lidar com ele]
Para entrada malformada ou ausente:
[Como lidar — nunca falhe silenciosamente]
Etapa 3: Execução Principal
[O trabalho real da habilidade.
Divida em subetapas. Cada subetapa deve ser
específica o suficiente para que uma nova instância
do Claude pudesse executá-la sem contexto adicional.]
Etapa 4: Verificação de Qualidade
Antes de salvar a saída, verifique em relação a estes padrões:
OBRIGATÓRIO: [Propriedades de saída inegociáveis]
PREFERÍVEL: [Propriedades de qualidade que melhoram a saída]
PROIBIDO: [Coisas que nunca devem aparecer na saída]
Se a saída falhar nas verificações obrigatórias:
- Identifique especificamente o que falhou
- Tente novamente com correção direcionada
- Máximo de três tentativas
- Se ainda falhar após três: salve com sinalizador de falha
Etapa 5: Saída e Armazenamento
Salve a saída em: [CAMINHO ESPECÍFICO E FORMATO DO NOME DO ARQUIVO]
Armazene na memória marcada com: [TAG-DA-TAREFA, DATA]
Atualize o CLAUDE.md se alguma informação atual mudou.
Envie notificação: [O QUE INCLUIR NA NOTIFICAÇÃO]
Casos Extremos
[Nome do Caso Extremo 1]
Condição: [Quando isso ocorre]
Detecção: [Como reconhecer]
Resposta: [O que fazer]
[Nome do Caso Extremo 2]
Condição: [Quando isso ocorre]
Detecção: [Como reconhecer]
Resposta: [O que fazer]
[Nome do Caso Extremo 3]
Condição: [Quando isso ocorre]
Detecção: [Como reconhecer]
Resposta: [O que fazer]
Padrão de Qualidade
Uma ótima saída: [Descrição específica]
Uma saída aceitável: [Barra mínima]
Uma saída inaceitável: [O que deve acionar uma nova tentativa]
Instruções de Memória
Após cada execução, armazene:
- Data e duração da execução
- Avaliação de qualidade da saída (ótima/aceitável/falhou)
- Qualquer caso extremo encontrado e como foi tratado
- Qualquer padrão digno de nota para execuções futuras
Seu Primeiro Agente Real: O Agente de Pesquisa e Briefing
Aqui está um agente completo do mundo real construído usando esta arquitetura. Este agente monitora um conjunto de fontes diariamente, pesquisa tópicos relevantes para o seu trabalho e entrega um briefing estruturado toda manhã.
Esta não é uma tarefa de brinquedo. É um fluxo de trabalho real que substitui quarenta e cinco minutos de compilação manual de pesquisa todos os dias.
Crie skills/research-brief.md:
research-brief
Propósito
Monitorar fontes configuradas e produzir um briefing
de inteligência estruturado cobrindo desenvolvimentos
relevantes para projetos e prioridades atuais.
Gatilho
Agendado diariamente às 6:00 AM.
Manual: "Research brief" ou "Morning brief"
Verificações Pré-Execução
Antes de iniciar, verifique:
- CLAUDE.md está legível em 07-SYSTEM/CLAUDE.md
- Brave Search MCP está respondendo
- O caminho de saída é gravável em outputs/briefings/
- O banco de dados de memória está acessível
Processo Principal
Etapa 1: Carregamento de Contexto
Leia o CLAUDE.md completamente. Observe:
- Projetos ativos atuais e seu status
- Tópicos sinalizados para monitoramento
- Quaisquer decisões pendentes que precisam de inteligência
- Padrões de qualidade para este briefing
Leia a memória marcada com: research-brief
Observe: o que foi coberto em briefings recentes
para evitar repetição.
Etapa 2: Pesquisa de Fontes
Para cada tópico na lista de monitoramento do CLAUDE.md:
Consulta de pesquisa: "[TÓPICO] notícias últimas 24 horas"
Colete: título, fonte, data, afirmação principal
Aplique filtro de sinal:
INCLUIR: Novo desenvolvimento, dado, lançamento de produto,
declaração significativa, descoberta de pesquisa
EXCLUIR: Repetição de cobertura existente,
opinião sem nova informação,
qualquer coisa coberta nos últimos 3 briefings
Para cada resultado que passar pelo filtro de sinal:
Pesquise mais a fundo com uma busca de acompanhamento se
o resultado inicial sugerir um desenvolvimento significativo.
Etapa 3: Síntese
Agrupe descobertas por tópico.
Para cada grupo de tópico, identifique:
- O desenvolvimento mais significativo
- Por que é importante para os projetos atuais
- Que ação, se houver, ele implica
Síntese entre tópicos:
- Existem duas ou mais descobertas que se conectam para sugerir um padrão maior?
- Alguma descoberta impacta diretamente um projeto ativo ou decisão pendente?
Etapa 4: Verificação de Qualidade
Antes de finalizar, verifique:
OBRIGATÓRIO:
- Mínimo de 3 itens de sinal (não ruído)
- Cada item fundamentado em uma fonte específica
- Cada item explica relevância para o trabalho atual
- Nenhum item repetido dos últimos 5 briefings
PREFERÍVEL:
- Pelo menos uma conexão entre tópicos
- Pelo menos um item que implique uma ação específica
- Reconhecimento honesto se foi um dia de notícias lentas
PROIBIDO:
- Análise genérica sem evidência específica
- Itens que são interessantes, mas não relevantes
- Enchimento para fazer o briefing parecer mais abrangente
Se o briefing falhar nas verificações obrigatórias: identifique especificamente
o que está faltando e pesquise fontes adicionais
antes de tentar novamente. Não encha com sinais fracos.
Etapa 5: Geração de Saída
Gere o briefing neste formato exato:
Morning Intelligence Brief — [DATA]
MAIS IMPORTANTE HOJE
[Desenvolvimento mais significativo e por que é
importante para o trabalho atual. Específico. Fundamentado.]
ITENS DE SINAL
[Tópico 1]
\\Desenvolvimento:\\ [O que aconteceu]
\\Fonte:\\ [Publicação, data]
\\Relevância:\\ [Por que isso importa para os projetos atuais]
\\Implicação:\\ [Qualquer ação que isso sugira]
[Tópico 2]
[Mesmo formato]
[Continue para cada item de sinal]
CONEXÃO
[Se dois ou mais itens se conectarem para sugerir um padrão
maior, descreva aqui. Pule se não houver conexão genuína.]
RELEVÂNCIA PARA DECISÃO
[Se algum item for diretamente relevante para uma decisão
pendente no CLAUDE.md, sinalize aqui com detalhes.]
NOTA DE COBERTURA
[Avaliação honesta: dia abrangente / dia de notícias lentas.
Número de fontes pesquisadas.]
Etapa 6: Armazenamento e Notificação
Salve em: outputs/briefings/[DATA]-morning-brief.md
Armazene na memória:
- Data: [HOJE]
- Itens cobertos: [LISTA DE TÓPICOS]
- Qualidade: [ótimo/aceitável/falhou]
- Notável: [Qualquer caso extremo ou padrão] Tag: research-brief
Envie notificação no Telegram:
"Morning brief pronto: [N] itens de sinal.
[MAIS IMPORTANTE HOJE em uma linha]"
Casos Extremos
Nenhum Sinal Encontrado para um Tópico
Condição: Pesquisas não retornam novos desenvolvimentos
42 Resposta: Observe " Sem novos desenvolvimentos para esse tópico. Observe "Sem novos desenvolvimentos" para aquele tópico ... Não invente nem introduza padding. Vá para o próximo tópico ...
Não invente nem adicione conteúdo artificialmente ... Vamos corrigir isso no texto traduzido final mantendo a naturalidade e evitando qualquer tipo de interrupção no meio da frase ou palavra incompleta Reiniciar a transcrição da resposta Considerando esses casos comuns Recuperação automática
Para evitar qualquer conteúdo incompleto na resposta final como parte do processo de raciocínio para garantir que não haja nenhum problema com a resposta final que será apresentada, aqui está o resto do texto da última frase sem interrupções:
Não invente nem adicione conteúdo artificialmente. Vá para o próximo tópico.
Fonte Retorna Informações Conflitantes
Condição: Duas fontes relatam fatos contraditórios
Detecção: Contradição direta em uma afirmação específica
Resposta: Relate ambas as versões, cite ambas as fontes, sinalize como conflitante. Não escolha uma em detrimento da outra.
Ferramenta de Pesquisa Indisponível
Condição: Brave Search MCP não está respondendo
Detecção: Chamada de ferramenta retorna erro
Resposta: Registre a falha. Notifique via Telegram.
Salve o briefing parcial com a nota: "Pesquisa indisponível — briefing baseado apenas no contexto da memória."
Não falhe silenciosamente.
Briefing Repetiria o Item Principal de Ontem
Condição: O desenvolvimento mais significativo é o mesmo de ontem
Detecção: Referência cruzada com o briefing de ontem na memória
Resposta: Observe "Desenvolvimento contínuo de [DATA]" e foque no que é especificamente novo hoje.
Padrão de Qualidade
Ótimo briefing: 4-6 itens de sinal. Cada item relevante. Pelo menos um insight entre tópicos. Lê-se em menos de 5 minutos.
Briefing aceitável: 3 itens de sinal. Todos relevantes. Nenhum insight entre tópicos. Lê-se em menos de 5 minutos.
Briefing inaceitável: Menos de 3 itens de sinal. Qualquer item genérico ou não relevante para o trabalho atual. Qualquer item repetido dos últimos 3 briefings.
Construindo a Camada de Verificação de Qualidade
A camada de verificação de qualidade é o que separa agentes que produzem resultados consistentes de agentes que produzem resultados variáveis.
A maioria dos agentes pula esta camada completamente. Eles geram uma saída e a retornam. A qualidade depende inteiramente de quão boa foi a geração. Algumas sessões são excelentes. Algumas são medíocres. Você nunca sabe qual vai receber.
Uma camada de verificação de qualidade torna a qualidade da saída consistente, verificando cada saída contra padrões definidos e tentando novamente com correções específicas quando os padrões não são atendidos.
Aqui está o padrão de chamada da API Claude que implementa a verificação de qualidade:
async function executeWithQualityVerification(prompt, qualityStandard, maxRetries = 3) {
let attempt = 0;
let lastOutput = null;
let lastFailure = null;
while (attempt < maxRetries) {
// Gera a saída
const response = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ANTHROPIC_API_KEY,
'anthropic-version': '2023-06-01'
},
body: JSON.stringify({
model: 'claude-opus-4-8',
max_tokens: 4096,
messages: [
{
role: 'user',
content: attempt === 0
? prompt
: ${prompt}
Tentativa anterior falhou na verificação de qualidade: ${lastFailure}
Corrija especificamente para esta falha. Não reescreva tudo.
}
]
})
});
const data = await response.json();
lastOutput = data.content[0].text;
// Verifica a qualidade
const verificationResponse = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ANTHROPIC_API_KEY,
'anthropic-version': '2023-06-01'
},
body: JSON.stringify({
model: 'claude-opus-4-8',
max_tokens: 1000,
messages: [
{
role: 'user',
content: `Você é um verificador de qualidade. Avalie esta saída em relação a estes padrões:
${qualityStandard}
Saída a ser avaliada:
${lastOutput}
Responda APENAS com:
PASS se a saída atender a todos os padrões obrigatórios
FAIL: [descrição específica do que falhou] se não atender aos padrões obrigatórios
Não explique. Não sugira melhorias. Apenas PASS ou FAIL com descrição específica da falha.`
}
]
})
});
const verificationData = await verificationResponse.json();
const verificationResult = verificationData.content[0].text.trim();
if (verificationResult.startsWith('PASS')) {
return { output: lastOutput, attempts: attempt + 1, passed: true };
}
lastFailure = verificationResult.replace('FAIL:', '').trim();
attempt++;
}
// Todas as tentativas esgotadas
return {
output: lastOutput,
attempts: maxRetries,
passed: false,
failure: lastFailure
};
}
Este padrão gera uma saída, verifica-a em relação a padrões definidos e tenta novamente com correções específicas quando falha. Se todas as tentativas falharem, ele retorna a melhor saída com um sinalizador de falha em vez de travar.
O Padrão de Integração de Memória
A memória é o que transforma um agente capaz em um agente que aprende.
Sem memória, cada sessão começa do zero. O agente não sabe o que fez antes. Ele não pode aplicar aprendizados de execuções passadas. Ele não pode evitar erros que já cometeu.
Com memória, cada sessão se baseia na anterior. O agente sabe o que funcionou e o que não funcionou. Ele aplica o contexto acumulado para melhorar as saídas atuais. Ele melhora na tarefa específica ao longo do tempo.
Aqui está o padrão de integração de memória para qualquer agente Claude:
No início de cada execução:
Leia as entradas de memória marcadas com: [TAG-DA-TAREFA]
Limite: 20 entradas mais relevantes
Estratégia: relevância (não apenas atualidade)
Aplique este contexto:
- Observe padrões de execuções anteriores
- Observe casos extremos encontrados anteriormente
- Observe problemas de qualidade identificados anteriormente
- Aplique aprendizados à execução atual
No final de cada execução:
Armazene na memória:
data: [HOJE]
tarefa: [NOME DA TAREFA]
qualidade: [ótimo/aceitável/falhou]
notável: [qualquer coisa que valha a pena lembrar]
caso_extremo: [qualquer caso extremo encontrado]
padrão: [qualquer padrão observado]
Tag: [TAG-DA-TAREFA], [DATA]
Consolidação mensal:
Leia todas as entradas de memória marcadas com: [TAG-DA-TAREFA]
Identifique:
- Padrões que aparecem em múltiplas entradas
- Casos extremos que recorrem
- Problemas de qualidade que recorrem
- O que correlaciona saídas ótimas vs. aceitáveis
Consolide em uma única entrada de contexto atualizada
Arquive entradas individuais com mais de 90 dias
O Sistema de Recuperação de Falhas
Agentes do mundo real encontram falhas. Fontes ficam offline. APIs impõem limites de taxa. Arquivos não estão onde são esperados. Saídas falham nas verificações de qualidade após o número máximo de tentativas.
O sistema de recuperação de falhas determina se essas falhas são pequenos contratempos invisíveis ou paradas catastróficas.
Três níveis de tratamento de falhas:
Nível 1: Recuperação Automática
Falhas transitórias que se resolvem com uma nova tentativa. Ferramenta indisponível. Tempo limite de rede. Limite de taxa atingido.
Protocolo de Recuperação do Nível 1
Em qualquer falha de chamada de ferramenta:
- Aguarde 60 segundos
- Tente novamente a mesma chamada
- Se a nova tentativa for bem-sucedida: continue normalmente, registre o contratempo
- Se a nova tentativa falhar: escale para o Nível 2
Nível 2: Degradação Elegante
Falhas que não podem ser resolvidas, mas permitem conclusão parcial. Uma fonte indisponível. Uma ferramenta não respondendo. Uma seção da saída falhando nas verificações de qualidade.
Protocolo de Recuperação do Nível 2
Em falha parcial irresolúvel:
- Conclua o que pode ser concluído
- Observe especificamente o que foi pulado e por que
- Sinalize a saída como parcial no nome do arquivo
- Inclua uma nota explícita na própria saída
- Envie notificação: "Saída parcial — [motivo específico]"
- NÃO falhe toda a tarefa porque um componente falhou
Nível 3: Parada Elegante
Falhas que tornam toda a tarefa impossível. CLAUDE.md não encontrado. Caminho de saída não gravável. Banco de dados de memória inacessível.
Protocolo de Recuperação do Nível 3
Em falha completa:
- Identifique o ponto de falha específico
- Salve qualquer trabalho concluído em local temporário
- Registre o contexto completo da falha
- Envie notificação: "Tarefa falhou — [motivo específico]"
- Pare de forma limpa sem corromper nenhuma saída existente
- NÃO tente novamente automaticamente — aguarde intervenção humana
Testando Seu Agente Antes de Implantar
O erro mais comum na implantação de agentes do mundo real é pular os testes estruturados.
Três fases de teste antes de qualquer agente entrar em produção:
Fase 1: Teste de Componentes
Teste cada componente isoladamente antes de testar todo o fluxo de trabalho.
Teste se a memória está persistindo
hermes chat
Qual é a entrada de memória mais antiga que você tem armazenada?
Esperado: Deve relatar uma entrada ou relatar banco de dados vazio
Se retornar erro: a configuração de memória está errada
Teste o acesso à ferramenta
Liste os arquivos em [CAMINHO DE SAÍDA]
Esperado: Deve listar os arquivos reais
Se retornar erro: o MCP do sistema de arquivos não está configurado corretamente
Teste a pesquisa
Pesquise por "notícias de IA hoje" e me diga o principal resultado
Esperado: Deve retornar resultados de pesquisa reais
Se retornar erro: o MCP do Brave Search não está configurado corretamente
Fase 2: Teste do Caminho Feliz
Execute a habilidade manualmente em uma entrada padrão limpa e verifique se a saída atende ao padrão de qualidade.
Execute a habilidade manualmente
hermes run research-brief
Verifique a saída
cat outputs/briefings/[HOJE]-morning-brief.md
Verifique em relação ao padrão de qualidade:
- Mínimo de 3 itens de sinal?
- Cada item relevante para o trabalho atual?
- Nenhuma análise genérica?
- Lê-se em menos de 5 minutos?
Fase 3: Teste de Caso Extremo
Dispare deliberadamente cada caso extremo documentado e verifique o comportamento de recuperação.
Teste: sem acesso à internet
Desabilite o Brave Search no .env
Execute a habilidade
Esperado: Falha de Nível 3, parada limpa, notificação enviada
Teste: caminho de saída não gravável
Mude o OUTPUT_PATH para um diretório inexistente
Execute a habilidade
Esperado: Falha de Nível 3, parada limpa, notificação enviada
Teste: dia de notícias lentas
Execute em um fim de semana ou feriado
Esperado: Saída de Nível 2 com NOTA DE COBERTURA indicando dia lento
Executando Seu Agente em Produção
Assim que todas as três fases de teste passarem, configure o agendador e migre para produção.
{
"schedules": [
{
"skill": "research-brief",
"cron": "0 6 *",
"description": "Diariamente às 6AM",
"timeout_minutes": 15,
"on_failure": "notify_and_stop"
}
]
}
Inicie o Hermes em modo de segundo plano:
npm run start -- --daemon
Verifique a primeira execução agendada:
Verifique os logs após as 6AM
cat logs/hermes-[DATA].log
Verifique se a saída foi produzida
ls outputs/briefings/
Verifique se a memória foi atualizada
hermes chat
Quantas entradas de memória do research-brief você tem?
Se a primeira execução automatizada produzir uma boa saída, o agente está em produção.
O Que Muda no Mês 3
Mês um: O agente funciona de forma confiável. As saídas são consistentes. As falhas são tratadas com elegância. Você economiza quarenta e cinco minutos toda manhã.
Mês dois: A camada de memória começa a produzir uma melhoria visível. O agente processou sessenta dias de fontes e acumulou contexto sobre quais fontes produzem conteúdo de alto valor versus ruído. A qualidade da filtragem de sinais melhora porque o agente aprendeu quais fontes valeram a pena ser seguidas.
Mês três: A consolidação da memória foi executada duas vezes. O agente identificou padrões ao longo de noventa dias de pesquisa. Os briefs referenciam o contexto acumulado, tornando-os mais fundamentados e específicos do que qualquer pesquisa feita em uma única sessão poderia produzir.
O agente no terceiro mês não está executando o mesmo fluxo de trabalho do primeiro mês.
Ele está executando uma versão melhorada desse fluxo de trabalho, baseada em noventa dias de inteligência operacional acumulada.
Essa é a diferença entre um agente de tutorial e um agente do mundo real.
O agente de tutorial executa a tarefa.
O agente do mundo real aprende a executar a tarefa melhor.
Construa a base neste fim de semana.
Execute por uma semana. Conserte o que quebrar.
Execute por um mês. Observe-o melhorar.
Execute por três meses. Perceba o que ele sabe que você não poderia ter dito a ele no primeiro dia.
É assim que se constroi um agente Claude que realmente funciona no mundo real.
Siga @cyrilXBT para todas as arquiteturas de agente, templates de habilidade e padrões de implantação em produção que fazem seus agentes Claude sobreviverem ao contato com o mundo real.
