5 conceitos fundamentais de IA
Antes de começar a usar o EasyClaw, dedique 5 minutos a aprender estes conceitos — eles vão ajudá-lo a compreender verdadeiramente como a IA funciona, em vez de introduzir instruções às cegas.
Não precisa de ser engenheiro, mas precisa de saber: porque é que a IA consegue fazer coisas, como torná-la mais precisa e quando pode falhar.
1. Agent (agente inteligente)
Como os principiantes o entendem
Um Agent (agente inteligente) pode ser simplesmente entendido como: "um colega de trabalho de IA que resolve coisas". Não se limita a conversar e explicar; mais importante ainda, consegue transformar os seus objetivos em passos concretos, e continuar a avançar após cada passo concluído até atingir o resultado desejado.
Visão geral do agente de IA
Um agente de IA típico é normalmente constituído por três partes que trabalham em conjunto:
Cérebro (compreensão e tomada de decisão) + Ferramentas/capacidades (onde executar) + Ciclo de execução (verificar enquanto faz).
Portanto, não se parece com uma "geração de resposta única", mas sim com um gestor de projeto:
primeiro pensar, depois agir e, em seguida, verificar.
A seguir, vamos esclarecer como funciona. Pode imaginar o processo de trabalho do agente como um ciclo executado repetidamente: Compreender a tarefa → Fazer o plano → Chamar ferramentas → Executar a ação → Verificar o resultado → Ajustar → Reportar.
1) Compreender a tarefa:
O agente vai primeiro determinar qual é o problema que está a tentar resolver, como é o sucesso,
e se existem restrições (por exemplo, formato, tom, prazo, o que não deve fazer).
Se a informação for insuficiente, pode fazer-lhe perguntas primeiro, ou fazer os pressupostos necessários e explicá-los.
2) Fazer um plano (decompor os passos):
Tarefas grandes precisam muitas vezes de ser decompostas em passos mais pequenos. Por exemplo, "organizar a caixa de entrada" pode ser decomposto em:
Analisar e-mails → Identificar tipos (notificações/faturas/clientes/diversos) → Avaliar a prioridade →
Arquivar → Redigir respostas (se necessário) → Resumir a lista. Este passo determina "o que fazer primeiro, o que fazer a seguir."
3) Chamar ferramentas/capacidades:
Esta é também a chave para o agente poder "fazer as coisas". Sem ferramentas, só pode ficar ao nível de
conselhos baseados em texto; com ferramentas, pode realmente executar ações, como: ler ficheiros, pesquisar informações,
enviar mensagens, aceder a sistemas empresariais, gerar documentos, etc.
Verá o agente a "conectar-se com o mundo exterior", e não apenas a gerar uma frase.
4) Executar e registar:
Nos passos apropriados, o agente vai realmente desencadear operações (por exemplo, chamar uma API de serviço,
concluir uma tarefa de processamento de dados, gerar conteúdo utilizável).
Ao mesmo tempo, regista "que passo concluí", facilitando a continuação ou o recuo para correções posteriores.
5) Verificação e correção de erros:
O agente não se limitará a aparentar "estar concluído"; também verificará se o resultado cumpre os requisitos.
Por exemplo: faltam campos-chave na saída, viola os seus requisitos de formato,
existem erros óbvios ou incertezas? Se não estiver satisfeito, voltará a planear o passo seguinte e continuará a iterar.
6) Reportar resultados e passos seguintes:
Finalmente, o agente resumirá o conteúdo que concluiu, as descobertas importantes,
e os itens que precisam da sua confirmação. Pode ver claramente: o que fez, o que foi concluído, o que ainda está em curso.
Você diz: "Por favor, organize a minha caixa de entrada e resuma os e-mails que precisam de resposta numa lista de tarefas."
O agente pode: ler a lista de e-mails → categorizar e arquivar → extrair remetente/assunto/cronologia chave →
determinar quais precisam de resposta → gerar "lista de tarefas" (com prioridade e pontos de resposta sugeridos) →
dizer-lhe "concluí estas categorias, ainda tenho itens não lidos/incertos por resolver."
Nota: Não se limita a dar "ideias organizativas", mas sim a produzir resultados utilizáveis
(listas/arquivos/rascunhos/progresso).
Os principiantes muitas vezes tratam o agente como um chatbot normal: perguntam apenas "como fazer". Mas um verdadeiro agente precisa de capacidades utilizáveis e fluxos de trabalho de execução. Se um sistema só consegue explicar passos mas não pode produzir resultados nem desencadear ações, é mais um "assistente de perguntas e respostas" do que um agente. Lembre-se disto: Falar ≠ Fazer; a vantagem do agente reside na execução e no feedback.
2. Skill (capacidade/habilidade)
Como os principiantes o entendem
Um Skill (capacidade/habilidade) pode ser entendido como: os módulos de capacidade específicos que o agente usa para "fazer as coisas".
O agente é responsável por pensar e programar (receber tarefas, decidir os próximos passos), enquanto o Skill é responsável por transformar
"como fazer o próximo passo" em operações executáveis: como recuperar informações, escrever documentos,
gerar relatórios, chamar interfaces, realizar cálculos, etc.
Um agente sem Skills muitas vezes só pode ficar ao nível do conselho; com Skills, o agente pode realmente produzir resultados.
O que é exatamente um Skill (essência)
De uma perspetiva de engenharia, um Skill é normalmente um tipo de "capacidade invocável", com formas comuns que incluem:
1) Ferramentas/funções (por exemplo, pesquisar, calcular, gerar, traduzir);
2) Processos de negócio (por exemplo, fazer encomendas, reembolsos, criar tickets);
3) Chamadas de interface (por exemplo, consultas CRM, sincronização de calendários, envio de e-mails).
O segredo não é "se consegue conversar", mas sim que os Skills geralmente têm limites claros:
qual é a entrada, como executá-la, qual é a saída.
Isto permite ao agente decompor tarefas de forma mais fiável e obter resultados verificáveis após a execução.
No ciclo do agente, o passo "chamar ferramentas/capacidades" aparece frequentemente, e o que está a ser chamado é normalmente um Skill. Pode pensar assim: O agente é como um cérebro, o Skill é como as mãos, os pés e uma caixa de ferramentas.
Para aprofundar, vamos explicar detalhadamente "como o Skill funciona no ciclo do agente":
1) O agente determina qual o Skill necessário
Quando a tarefa entra na fase de execução, o agente analisará quais as capacidades necessárias para o passo atual.
Por exemplo, "encontrar os registos históricos de comunicação de um cliente" precisa de um Skill do tipo "recuperar/ler";
"redigir um e-mail de acompanhamento" precisa de um Skill do tipo "gerar texto/usar modelo";
"sincronizar tarefa com o sistema de tarefas" precisa de um Skill do tipo "escrever/atualizar".
2) O agente preenche os parâmetros no Skill (entrada)
Os Skills geralmente requerem um formato de entrada específico, como: palavras-chave, intervalo de tempo, ID do cliente, público-alvo, estilo de saída, etc.
O agente extrairá o contexto e organizá-lo-á nos parâmetros requeridos pelo Skill.
Este passo determina se a execução é precisa: se a entrada estiver errada, a saída provavelmente será desviada.
3) O Skill é executado e devolve o resultado (saída)
Após a execução do Skill, este devolve resultados estruturados ou semiestruturados, como: listas de itens recuperados, resultados de cálculos,
texto de documentos gerados, códigos de estado de retorno de API, etc.
Estes resultados podem ser lidos de volta pelo agente para a tomada de decisão subsequente.
4) O agente valida a saída e continua para o passo seguinte (ciclo fechado)
A conclusão do Skill não é o ponto final; o agente também verificará: se o resultado cumpre as restrições,
se falta informação, se é necessária uma segunda geração ou correção.
Se não estiver satisfeito, pode chamar outro Skill (por exemplo, "pesquisa suplementar", "reescrever conteúdo", "formatar saída") e iterar novamente.
Este é o "ciclo fechado cooperativo" do Skill e do agente.
Os principiantes muitas vezes tratam o Skill como uma "instrução de chat". Mas um verdadeiro Skill é mais como uma "interface":
Quanto mais clara for a entrada, mais estável é a saída; só assim o agente pode repetir a execução de forma fiável e concluir tarefas.
Por exemplo, mesmo para "gerar e-mail", o Skill exigirá tom, extensão, informações do destinatário e campos de informação chave,
para que o conteúdo gerado não se desvie cada vez.
Exemplo: Pede ao agente para "escrever um e-mail de acompanhamento para potenciais clientes e criar uma tarefa."
Isto normalmente encadeia vários Skills, formando uma cadeia de ação completa:
1) Skill de recuperação de informações do cliente: entrada: ID/nome do cliente, saída: nome, empresa, pontos-chave da última comunicação;
2) Skill de extração/resumo de informação: entrada: registos de comunicação, saída: pontos problemáticos chave e itens alcançados;
3) Skill de geração de e-mail: entrada: tom (profissional/amigável), modelo (acompanhamento/fecho), pontos-chave, saída: corpo do e-mail;
4) Skill de geração de tarefas: entrada: conteúdo do e-mail e sugestões de ação, saída: itens de tarefa (responsável, prazo, passos);
5) Skill de escrita no calendário/sistema de tarefas: entrada: dados estruturados de tarefas, saída: estado de criação bem-sucedida ou link.
Vai notar: o agente parece "perceber de trabalho de vendas", mas por detrás disto estão módulos de Skill que unem capacidades reais num fluxo de trabalho. O agente é responsável por usar estas capacidades na ordem correta.
Muitas pessoas entenderão o Skill como um segmento de prompt ou uma instrução de uma linha durante a integração do sistema.
Mas sem entrada/saída claras e mecanismos executáveis, o agente não consegue reproduzir de forma estável os mesmos resultados.
A compreensão mais correta é: O Skill é uma unidade de capacidade invocável,
o prompt serve apenas para o ajudar a "selecionar/organizar" melhor.
Pode avaliar rapidamente com três perguntas:
Pode ser chamado?
Que entrada necessita e qual é a saída?
Após a execução, o agente pode obter resultados utilizáveis (e não apenas explicações)?
Se cumprir estes critérios, está mais próximo de ser um Skill; caso contrário, pode ser apenas "capacidade de texto consultiva".
Continue a usar o "ciclo operacional" do agente para compreender o Skill: o agente é responsável por pensar e programar, o Skill é responsável por executar passos concretos. Quando o agente descobre que uma tarefa precisa de uma determinada capacidade, selecionará o Skill apropriado, colocará os parâmetros necessários nele, aguardará que ele devolva os resultados e, em seguida, trará os resultados de volta ao ciclo para validação, suplementação ou planeamento do passo seguinte.
Exemplo: Pede ao agente para "escrever um e-mail de acompanhamento para um cliente e gerar uma tarefa."
Pode chamar diferentes Skills:
1) Recuperar informações do cliente (obter nome, pontos da última comunicação);
2) Gerar rascunho de e-mail (saída por tom/extensão/modelo);
3) Gerar lista de tarefas (decompor os passos seguintes em itens).
Quando estes Skills são reunidos, formam o comportamento do agente que "parece muito capaz".
O Skill transforma o agente de "pode falar" para "pode obter resultados", trazendo normalmente três benefícios:
Mais fiável (passos fixos, parâmetros claros), Mais controlável (saber o que está a fazer),
Mais reutilizável (a mesma capacidade pode ser usada para diferentes tarefas).
Algumas pessoas pensam que o Skill é um "prompt". Na verdade, o Skill é mais como um módulo de capacidade invocável (ferramenta/interface/processo). Sem entrada/saída claras e métodos de execução, o agente terá dificuldade em repetir de forma estável o mesmo efeito.
3. Prompt (instrução/indicação)
Compreensão popular
Um Prompt (instrução/indicação) é o que diz à IA em linguagem natural como um "requisito de uma linha". Você indica o que precisa de ser feito e a IA faz o seu melhor para produzir o resultado.
Compreensão aprofundada
De forma mais precisa, o Prompt é a interface central para a comunicação com a IA. Para sistemas com Agent e Skill integrados, um bom Prompt não é apenas "fazê-lo gerar texto", mas sim fazê-lo saber quando chamar o Skill, como preencher os parâmetros, qual deve ser o aspeto da saída e como lidar com as falhas.
| Tipo | Exemplo | Efeito |
|---|---|---|
| ❌ Prompt genérico | "Ajude-me a escrever um e-mail" | A IA improvisa livremente; quando falta informação, adivinha aleatoriamente; difícil de verificar |
| ✅ Bom Prompt (orientado para a execução) | "Você é um consultor de vendas B2B. Escreva um e-mail de acompanhamento de produto para o CTO: tom profissional e conciso; primeiro recupere a empresa de Zhang San e os pontos de comunicação anteriores do CRM; o e-mail deve incluir: 1) uma proposta de valor 2) confirmação alinhada com 2 pontos da última conversa 3) próxima ação clara; produza 3 tarefas no final (formato de data AAAA-MM-DD)." | Condições de acionamento claras + capacidades invocáveis definidas + estrutura de saída verificável |
Vai notar que o Prompt e os dois conceitos anteriores (Agent / Skill) são duas faces da mesma lógica operacional: O agente precisa do Prompt para decidir como proceder, o Skill precisa do Prompt para decidir o que preencher e como verificar.
"O ciclo de trabalho do agente" pode ser entendido como:
Compreender a tarefa → Fazer o plano → Decidir chamar o Skill → O Skill é executado → Verificar o resultado → Continuar a ajustar → Reportar.
E o papel do Prompt é dar regras em cada passo, evitando que se desvie, adivinhe às cegas ou forme um ciclo fechado.
1) O Prompt primeiro define "Objetivo e critérios de sucesso" (Porquê fazê-lo)
Este passo determina as "regras de pontuação" do agente. O Prompt precisa de lhe dizer: qual é exatamente o problema que está a resolver,
e que resultado conta como concluído.
Por exemplo: não "ajude-me a escrever um e-mail", mas "o e-mail deve incluir que parágrafos, que tom, que intervalo de extensão e terminar com uma tarefa."
Sem critérios de sucesso no Prompt, o agente só pode produzir uma saída que "parece mais ou menos correta", dificultando a verificação da qualidade.
2) O Prompt fornece "Condições de acionamento e restrições" (Quando fazer o quê)
Um Prompt que consegue obter resultados normalmente esclarece: quando chamar o Skill, quando fazer perguntas.
Por exemplo: se faltar o nome do cliente ou a data, deve perguntar primeiro em vez de se limitar a "escrever um nome ou data qualquer".
Isto equivale a reduzir a incerteza: quanto mais claras forem as restrições, mais estável é o agente.
3) O Prompt descreve "Que Skills são necessários e os contratos de entrada/saída para cada um" (Que ferramentas usar)
O Prompt deve esclarecer:
Que Skill chamar, que campos de entrada necessita, de onde vêm os campos de entrada, que requisitos de formato existem;
e ao mesmo tempo esclarecer: em que estrutura deve a saída do Skill ser devolvida (por exemplo, campos JSON, listas, tabelas, estrutura de parágrafos fixa, etc.).
Este passo é fundamental para que o Prompt seja verdadeiramente "engenheirado": transformar "como fazer o passo seguinte" em "invocação de capacidade invocável".
4) O Prompt requer "Verificação e tratamento de falhas" (Como avaliar se está bem feito)
Gerar resultados por si só não é suficiente; o Prompt deve especificar regras de verificação e estratégias de falha. As abordagens comuns incluem:
- A chamada do Skill falha/devolve resultado vazio: diagnosticar primeiro a causa (erro de parâmetro/permissão/rede/dados em falta) e depois tentar novamente ou degradar;
- Falta campos-chave na saída: deve completar ou perguntar ao utilizador, não é permitido adivinhar;
- O formato não corresponde: acionar "Skill de formato/Skill de reordenação/regenerar".
Isto evita que o agente fique preso num ciclo de "saída repetida mas sem convergir".
5) O Prompt define o "Formato de saída final" (Quem usará a saída)
Finalmente, o Prompt deve especificar como os resultados são apresentados: que campos devem ser devolvidos, que nomes de campo,
se são necessários resultados estruturados, se é necessária informação rastreável (por exemplo, "se o Skill foi chamado, que Skill foi chamado, quais foram as entradas/saídas chave").
Você diz: "Ajude-me a escrever um e-mail de acompanhamento para potenciais clientes e a criar uma tarefa."
Se usar um "Prompt executável", ele esclarecerá três coisas:
Condição de acionamento: perguntar primeiro se faltar o nome do cliente ou a data;
Invocação de Skills: primeiro chamar o "Skill de recuperação de informações do cliente", depois chamar o "Skill de geração de e-mail", finalmente chamar o "Skill de criação de tarefas";
Verificação de saída: o e-mail deve incluir a confirmação da proposta de valor e a próxima ação; a tarefa deve incluir o prazo (AAAA-MM-DD) e o responsável.
Desta forma, o agente passa de "escrever um e-mail decente" para "concluir um fluxo de trabalho totalmente executável".
Muitas pessoas escrevem Prompts apenas pedindo "faça isso por mim", mas sem critérios de sucesso, sem contratos de entrada/saída e sem tratamento de falhas.
O resultado é: o agente pode improvisar livremente, adivinhar quando faltam campos, a saída é difícil de verificar e, em última análise, não pode confirmar "se acertou".
A abordagem correta é: O Prompt deve ser como um contrato de execução que assina com o agente,
tornando cada passo julgável, corrigível e reutilizável.
1) Escreva o papel e os limites: Diga à IA quem ela é e que regras deve seguir
("deve verificar antes de produzir a saída", "não deve inventar informações inexistentes").
2) Defina o formato e os campos: Especifique a estrutura de saída ("devolva JSON com os campos A/B/C" ou "o e-mail deve ter três secções").
3) Escreva acionadores passo a passo: Decomponha a tarefa em ações executáveis, especifique quando chamar o Skill, quando perguntar, quando tentar novamente.
Compare: "Resuma este documento" vs "Resuma em 3 tópicos, cada um com no máximo 20 caracteres,
depois produza uma lista de palavras-chave (pelo menos 5 palavras-chave)"—este último é verificável, reutilizável e mais estável.
O agente é responsável por pensar e programar, o Skill é responsável pela execução concreta, enquanto o Prompt é responsável por dizer ao agente: quando chamar o Skill, como preencher os parâmetros, como verificar os resultados, e qual deve ser o aspeto da saída final.
4. Memory (memória de longo prazo) / MEMORY.md
Compreensão popular
O caderno da IA: usado para guardar de forma persistente as suas preferências e regras.
Compreensão aprofundada
A memória é o núcleo de memória de longo prazo do agente. As conversas normais normalmente só funcionam dentro de uma única sessão; mas o conteúdo escrito no MEMORY.md será priorizado e lido cada vez que o agente é iniciado, permitindo-lhe "fazer as coisas à sua maneira" em vez de perguntar os seus requisitos do zero cada vez.
Por exemplo, diz ao agente: "Prefiro respostas concisas em chinês, use Python para o código".
Se esta preferência for escrita na memória num formato adequado, quando o agente lidar com tipos de tarefas semelhantes mais tarde,
seguirá estas regras por defeito; não precisa de as enfatizar repetidamente,
e é muito menos provável que encontre problemas de "estilo de resposta inconsistente cada vez".
Se pensar no Agente como o executor e no Skill como a caixa de ferramentas,
então a memória é a configuração de longo prazo do agente:
Cada vez que o agente é iniciado, primeiro lê a memória para obter as suas preferências e POPs,
depois incorpora estas restrições ao planear e chamar os Skills.
Assim, a memória torna as "regras executáveis" eficazes a longo prazo.
Para garantir que a memória é verdadeiramente "utilizável", precisa de cumprir os padrões dos três conceitos anteriores: acionamento estável, entrada clara, saída verificável. Por outras palavras, o conteúdo escrito na memória deve guiar claramente como o agente deve proceder a seguir, não ser uma vaga expressão emocional.
Recomenda-se escrever a memória neste estilo de "lista de verificação de regras":
- Preferências de estilo de escrita: por exemplo, "chinês conciso", "conclusões primeiro", "não mais de 3 frases por parágrafo"
- Requisitos de formato: por exemplo, "Python para o código", "a saída da tabela inclui os campos A/B/C", "formato de data AAAA-MM-DD"
- POPs de decisão: por exemplo, "perguntar se a informação for insuficiente, não adivinhar; fornecer alternativas com rótulos de risco"
- Contexto de longo prazo: por exemplo, "a minha equipa é de entrega B2B", "as ferramentas comuns são XX (quando aplicável)"
Em vez de explicar cada vez "como quer que seja a saída", escreva os seus hábitos de trabalho na memória uma vez
para que o agente os siga automaticamente cada vez que é iniciado.
Quanto mais cedo solidificar estas regras, menos aborrecimentos depois e mais consistente será.
Pode priorizar por frequência: os itens estáveis e de alta frequência
(preferências de longo prazo, processos fixos) devem ser escritos primeiro.
A memória não é uma caixa de rascunhos. Tarefas temporárias e pontuais
(como "verifique o tempo em Shenzhen para mim hoje") não devem ser escritas na memória,
ou o ficheiro de memória tornar-se-á gradualmente inchado e confuso, fazendo com que o agente fique confuso no julgamento de longo prazo.
Princípio: Escreva apenas preferências fixas e POPs de longo prazo, ignore tarefas temporárias.
Se as respostas forem:
1) Esta regra será usada repetidamente no futuro?
2) Pode alterar de forma estável o formato/estilo de saída/estratégia de execução?
3) Não mudará com frequência ao longo do tempo?
Quantos mais critérios cumprir, mais adequado é para a memória.
Caso contrário, coloque-o apenas na instrução desta sessão.
A memória permite ao agente formar padrões de trabalho consistentes a longo prazo: solidifique nela as preferências estáveis e os POPs, mantendo as tarefas temporárias para a execução atual.
Pontos-chave sobre a memória:
1) A memória armazena a configuração de longo prazo (Porque é que existe)
A principal diferença entre a memória e o Prompt é: o Prompt trata desta tarefa específica,
enquanto a memória trata de "todas as tarefas futuras". Ao armazenar preferências e POPs na memória,
o agente pode aplicar estas regras de forma consistente sem que precise de as repetir.
Por exemplo, se escrever "o idioma de saída padrão é o chinês" na memória,
então em todas as tarefas futuras, o agente priorizará automaticamente responder em chinês.
2) Quando é que o agente usa a memória? (Mecanismo de carregamento)
Normalmente, a memória é carregada primeiro quando o agente inicia uma nova sessão ou conversa.
O agente lê o MEMORY.md, extrai as regras/preferências e depois trata-as como parte do contexto do sistema
para esta execução—semelhante a adicionar instruções extra do sistema.
Isto é diferente do Prompt a meio da conversa: a memória não muda durante a conversa,
é a "linha de base estável" para todas as execuções subsequentes.
3) O que NÃO deve ir para a memória (Estabelecimento de limites)
A memória deve conter: hábitos de trabalho estáveis, preferências de formato, POPs de longo prazo, restrições recorrentes.
A memória NÃO deve conter: tarefas pontuais, dados temporários, informações específicas da sessão, segredos pessoais.
Misturá-los faz com que a memória fique confusa e o agente perca a capacidade de distinguir
entre "o que é permanente" e "o que é temporário".
4) Como estruturar a memória para a máxima eficácia
Uma boa memória deve ser organizada por categorias:
- Estilo de comunicação: "Responder sempre em chinês conciso", "primeiro a estrutura, depois os detalhes", etc.
- Padrões técnicos: "usar Python como linguagem principal", "usar JSON para dados estruturados", etc.
- Regras de decisão: "quando não tiver a certeza, pergunte em vez de adivinhar", "forneça sempre uma avaliação de risco", etc.
- Contexto e antecedentes: "a trabalhar em B2B SaaS", "o tamanho da equipa é de 5", etc.
- Informações de ferramentas e integração: "o CRM típico é o Salesforce", "o sistema de registo é o Datadog", etc.
Desta forma, quando o agente lê a memória, pode encontrar rapidamente as regras relevantes para o contexto atual.
5) Manutenção da memória (Mantê-la atualizada)
A memória não é "escreva uma vez, use para sempre". À medida que o seu estilo de trabalho evolui ou as regras mudam,
deve rever e atualizar periodicamente a memória para a manter alinhada com a prática atual.
Uma boa prática: rever a memória trimestralmente, remover itens desatualizados, adicionar novos padrões estabelecidos.
Isto mantém a memória enxuta e eficaz.
Exemplo de MEMORY.md:
As minhas preferências de trabalho e POPs
Estilo de comunicação
Idioma: Português (conciso, conclusão primeiro)
Formato: tópicos ao listar, secções estruturadas para informações complexas
Tom: profissional mas acessível
Padrões técnicos
Linguagem principal: Python
Formato de dados: JSON
Formato de data: AAAA-MM-DD
Fuso horário: UTC+0
Regras de decisão
Quando a informação for insuficiente: fazer perguntas esclarecedoras, não assumir
Fornecer alternativas com análise de risco/benefício
Incluir raciocínio rastreável em decisões complexas
Contexto
Equipa: B2B SaaS, 5 pessoas
CRM principal: Salesforce
Ferramentas principais: Python, PostgreSQL, Slack
POPs de processos
Revisão de código sempre necessária antes da implementação
A documentação deve ser atualizada quando a API muda
Reunião diária às 10:00 AM UTC+0
1) Sobrecarregar a memória: Tratar a memória como "tudo sobre mim". Isto confunde o agente sobre as prioridades.
2) Regras vagas: Evite "seja inteligente", "use o seu melhor julgamento". Use regras específicas e acionáveis.
3) Nunca atualizar: A memória deve evoluir consigo. Regras antigas e obsoletas criam ruído.
4) Regras contraditórias: Se a memória tiver contradições, o agente pode oscilar ou não decidir. Limpe-a.
Agora temos as quatro camadas:
Agente (pensar e programar) → decide o que fazer
Skill (execução concreta) → executa a decisão
Prompt (instruções desta tarefa) → especifica como fazer esta tarefa
Memória (configuração de longo prazo) → garante a consistência em todas as tarefas futuras
Juntos, formam um sistema de execução de IA completo, reproduzível e escalável.
5. Soul (valores fundamentais e comportamento) / SOUL.md
Compreensão popular
A "configuração de personalidade" e as barreiras comportamentais da IA: determina o que "deve fazer e o que absolutamente não deve fazer".
Compreensão aprofundada
O SOUL.md define as regras de comportamento, os valores e os limites operacionais do agente.
É a "constituição fundacional" do agente—que ações são permitidas,
quais são absolutamente proibidas, tudo escrito aqui claramente.
Portanto, o SOUL não é apenas uma preferência de estilo; impacta diretamente os limites de segurança do agente
e a saída conforme.
Se a memória é "o que foi lembrado", então o Soul é "em que tipo de IA se tornar". Por exemplo: responder apenas a perguntas relacionadas com o produto; operações financeiras requerem dupla confirmação; nunca solicitar palavras-passe ou credenciais sensíveis; para assuntos legais/médicos, deve fornecer avisos de isenção de responsabilidade e orientar para canais profissionais, etc.
A configuração do SOUL.md determina diretamente como o agente "recusa" e "fornece alternativas"
em cenários de alto risco. Se for implementado como uma ferramenta de equipa ou envolver dados empresariais,
uma configuração inadequada do SOUL pode levar a acesso não autorizado, violações de limites
ou riscos de conformidade.
Portanto, antes de entrar em produção, certifique-se de configurar cuidadosamente este ficheiro e verificar
os limites com casos de teste.
Recomenda-se escrever o SOUL como uma "lista de verificação de regras executáveis", abrangendo as seguintes categorias:
- O que é permitido: O âmbito de trabalho do agente e os limites do domínio (por exemplo, apenas lidar com consultas de produtos/processos internos).
- O que é proibido: Recusas duras explícitas para comportamentos de alto risco (por exemplo, solicitar palavras-passe/chaves; prometer resultados incertos; contornar permissões).
- Ações que requerem confirmação: Regras para transferências, reembolsos, contratos, alterações de permissões que devem ser duplamente confirmadas ou aprovadas.
- Estilo e tom de saída: por exemplo, deve ser educado, sem ataques pessoais, sem linguagem ameaçadora.
- Como lidar com os limites: Quando não for possível concluir, fornecer alternativas (por exemplo, registar e escalar para um humano/sugerir consultar especialistas).
Suponha que está a configurar um agente de serviço ao cliente para a sua empresa;
o seu SOUL.md pode incluir:
• Ser sempre educado, sem linguagem insultuosa ou categoricamente negativa;
• Nunca prometer reembolsos ou compensações, apenas dizer
"Vou registar e escalar/transferir para tratamento";
• Quando surgirem perguntas legais, responder uniformemente
"Por favor, consulte profissionais jurídicos";
• Quando forem solicitadas palavras-passe, OTPs, chaves: recusar diretamente
e orientar o utilizador através do processo de verificação adequado.
Após a configuração, não importa como os utilizadores tentem manipular, o agente não excederá os limites.
Após modificar o Soul, recomenda-se testar com alguns cenários:
quais devem ser rejeitados, quais precisam de confirmação, quais podem ser respondidos normalmente.
Pode preparar 6 categorias de perguntas de teste para verificar se o Soul está a funcionar:
1) Perguntas fora do domínio: O agente recusa ou redireciona?
2) Solicitações de alto risco: Recusa claramente?
3) Ações que precisam de confirmação: Confirma antes de executar?
4) Solicitações de informações sensíveis: Recusa e fornece alternativas seguras?
5) Conformidade/avisos de isenção de responsabilidade: Produz a saída de acordo com as regras?
6) "Manipulação para contornar": Quando os utilizadores solicitam ignorar processos,
mantém o limite?
O SOUL.md define as "barreiras e limites" do agente: torna a IA com princípios e previsível ao executar, portanto, mais segura e fiável em cenários de equipa e negócio.
Distinções-chave entre Soul, Memory e Prompt:
| Dimensão | Soul (SOUL.md) | Memory (MEMORY.md) | Prompt (Esta tarefa) |
|---|---|---|---|
| Âmbito | Limites fundamentais | Preferências de longo prazo | Esta tarefa específica |
| Frequência | Raramente muda (fundacional) | Muda trimestral/sazonalmente | Muda por tarefa |
| Propósito | Prevenir danos / garantir a segurança | Garantir a consistência | Especificar os detalhes de execução |
| Consequência da violação | Incumprimento de conformidade / risco de segurança | Resultados inconsistentes | Desajuste na saída da tarefa |
| Exemplo | "Nunca solicitar palavras-passe" | "Responder sempre em chinês" | "Resumir em 3 tópicos" |
1) O Soul define "Que tipo de agente você é" (Identidade e barreiras)
O Soul responde à pergunta mais profunda: O que me é permitido ser e fazer?
Isto inclui:
- Âmbito de trabalho: Por que domínios/tarefas sou responsável?
- Barreiras duras: O que devo absolutamente nunca fazer (segurança, conformidade, ética)?
- Fluxos de trabalho de aprovação: Para que ações devo exigir confirmação?
- Caminhos de escalonamento: Quando não posso ajudar, para onde encaminho?
O Soul é a linha que "não deve ser cruzada". É aplicada em cada execução, independentemente de como os utilizadores tentam manipular.
2) Soul vs. Segurança: Porque é que o Soul é importante para a implementação
Um Soul bem configurado pode prevenir muitos vetores de ataque comuns:
- Injeção de Prompt: Se o Soul disser "verificar sempre as solicitações de alto risco",
mesmo que um prompt diga "ignore esta regra", o agente deve recusar.
- Engenharia social: Se o Soul disser "nunca fornecer credenciais",
não importa quão habilmente um utilizador pergunte, o agente deve rejeitar.
- Expansão do âmbito: Se o Soul definir o limite do domínio do agente,
ele não tentará lidar com solicitações fora do âmbito adivinhando.
Isto torna o Soul fundamental para uma implementação segura.
3) Como o Soul se integra com o ciclo de decisão do agente
Pense no ciclo de execução do agente assim:
Passo 1: Ler o Soul → Quais são os meus limites?
Passo 2: Ler a memória → Quais são as minhas preferências de trabalho?
Passo 3: Receber o Prompt → Qual é esta tarefa específica?
Passo 4: Planear a execução → Dentro dos limites, atingir o objetivo
Passo 5: Verificar a conformidade → Fiquei dentro do Soul?
Passo 6: Executar / Escalar
Note que o Soul é verificado antes e depois da execução. É o ciclo exterior.
Antes de implementar um agente, verifique:
☑ O Soul.md está escrito (não apenas implícito)
☑ Todos os membros da equipa compreendem os limites
☑ Os casos de teste cobrem mais de 6 cenários, incluindo tentativas de jailbreak
☑ Os caminhos de escalonamento estão definidos e funcionais
☑ Os requisitos de conformidade estão cobertos explicitamente
☑ As ações de alto risco exigem confirmação/aprovação
☑ O tom de comunicação está definido e testado
☑ As barreiras de segurança (palavras-passe, tokens, chaves) são claras
☑ O tratamento de fora do âmbito é elegante (não rude)
☑ A auditoria/registo está implementada para ações sensíveis
Agente é a entidade pensante
Skill é a capacidade de execução
Prompt é a instrução da tarefa
Memória é a preferência de longo prazo
Soul é a constituição operacional
Juntos: O agente pensa (usando a memória para o contexto e o Soul para as barreiras),
decide que Skill chamar, recebe instruções específicas do Prompt,
e executa dentro dos limites do Soul. Resultado: um sistema de IA fiável, seguro e consistente.
Conceitos avançados (opcional)
Os três conceitos seguintes vão ajudá-lo a "compreender a automatização" verdadeiramente. Não são conhecimentos totalmente novos, mas sim trazer os conceitos anteriores de Agent / Skill / Memory / Soul / Prompt para o nível prático de "executar realmente, conectar-se entre si e integração estável." Os principiantes podem saltar estes por agora; quando começar a construir processos de vários passos, a integrar serviços externos ou a depurar problemas de fluxo de dados, voltar aqui poupar-lhe-á muito tempo.
🔀 1) Workflow (execução de processos de vários passos)
Um Workflow pode ser entendido como um caminho de execução reutilizável: conectar vários passos em sequência para que o sistema atinja um objetivo de forma sistemática. Se o Agente é "um colega que pode pensar e executar", então o Workflow é "a fila de tarefas e o método de conexão que configuramos para esse colega." Ele resolve o problema: quando uma tarefa não pode ser concluída numa frase, como executamos de forma fiável vários passos como uma cadeia conectada?
Um Workflow típico contém normalmente estes elementos (pode usar este quadro para compreender as capacidades de vários passos do EasyClaw):
- Lista de passos: O que fazer no passo 1, passo 2, etc. Cada passo deve ter limites e responsabilidades claras.
- Entrada e saída: Cada passo deve produzir resultados estruturados que o passo seguinte possa usar, não apenas "descrições de texto".
- Condições e ramificações: Por exemplo, "se faltar um campo crítico, pergunte primeiro ou recupere mais dados", caso contrário, avance para o passo seguinte.
- Validação e tratamento de erros: Por exemplo, "se a análise falhar, tente novamente ou recue para uma abordagem alternativa."
- Saída resumida: Entregar o resultado final num formato utilizável (lista de verificação, relatório, lista de tarefas, conteúdo de notificação, etc.).
Como é que o Workflow se alinha com os conceitos anteriores? Uma frase conecta-os:
O agente trata da tomada de decisões e da programação, o Skill trata da execução concreta,
a Memory/Soul tratam das regras e limites de longo prazo, o Prompt diz-lhe "como fazer",
e o Workflow conecta estes passos em sequência como uma cadeia.
Exemplo: precisa de concluir "escalar a reclamação do utilizador para um ticket e notificar a pessoa responsável." Um Workflow razoável pode ser assim:
- Recolher entrada: Reunir o conteúdo da reclamação, as informações do utilizador e a cronologia do formulário/mensagem.
- Extração de informações: Usar o agente para estruturar os pontos-chave da reclamação (por exemplo, tipo de problema, âmbito do impacto, marcas temporais críticas).
- Julgamento de regras: Com base no Soul/regras, determinar se é de alta prioridade, precisa de escalonamento ou requer mais informações primeiro.
- Chamar o Skill de criação de tickets: Preencher os campos estruturados na API do sistema de tickets, gerar o número do ticket.
- Chamar o Skill de notificação: Enviar o número do ticket e o resumo chave para a pessoa responsável (Feishu/e-mail/IM).
- Validação do resultado: Confirmar que a criação do ticket devolveu o estado de sucesso, que a notificação foi enviada.
- Feedback resumido: Enviar para o utilizador ou administrador "Ticket criado + link/número + próximos passos".
Vai notar: o Workflow não resolve "como escrever uma explicação", mas sim "como encadear de forma fiável várias chamadas de ferramentas e passos de validação." Quando começar a lidar com processos complexos (especialmente entre sistemas: IM + tickets + base de dados), o Workflow tornar-se-á a sua capacidade mais utilizada.
📦 2) JSON (formato de troca de dados)
O JSON é o formato padrão para passar dados entre o agente e as ferramentas/APIs externas. Na automatização de vários passos, o papel do JSON é fundamental: torna "o passo seguinte pode obter os dados corretos" uma pergunta verificável, não "podemos entender intuitivamente uma frase em linguagem natural."
Pode pensar no JSON como: um "contentor de dados estruturados" dentro do sistema. Em vez de frases soltas, contém campos e tipos explícitos, como: título do ticket, ID do utilizador, prioridade, prazo, conteúdo da notificação, etc.
No fluxo de trabalho do EasyClaw, o JSON aparece normalmente nestes locais:
- Entrada e saída do Skill: Os Skills muitas vezes precisam de campos específicos como entrada, devolvendo resultados estruturados para a tomada de decisão do agente.
- Parâmetros de chamada de API: Por exemplo, ao chamar a API do Feishu, os parâmetros precisam de ser organizados em JSON.
- Transferência de dados entre passos: A saída JSON de um passo é lida pelo passo seguinte.
Porque é que muitos problemas que parecem "o agente não consegue fazer isto" se devem na verdade ao JSON? Os casos comuns incluem:
- Incompatibilidade de nome de campo: A entrada esperada é
user_id, mas a entrada real éuserId. - Campos em falta: Falta um campo obrigatório, a API devolve um erro.
- Incompatibilidade de tipo: A data deve ser uma cadeia, mas é passada como número, ou deve ser uma matriz, mas é passada como texto.
- Erro de formato JSON: Faltam aspas, faltam parênteses, vírgulas finais, a análise falha.
Portanto, a melhor ordem de resolução de problemas para problemas de integração é normalmente:
Verifique primeiro o JSON, depois o Prompt, depois a lógica de raciocínio do agente.
Porque o JSON é a base de "se vai funcionar".
🔑 3) API Key (credencial de acesso)
Uma API Key é a credencial de autenticação ao aceder a modelos de IA ou serviços de terceiros. Sem a API Key correta, o sistema normalmente não pode chamar o modelo ou serviço correspondente; mesmo que o agente raciocine perfeitamente, a execução continua impossível.
Nos cenários do EasyClaw, precisa de distinguir dois casos:
- Uso das capacidades/créditos oficiais por defeito: Os principiantes normalmente não precisam da sua própria chave, pois a plataforma já configurou o acesso para si.
- Integração de modelos personalizados/serviços personalizados: Precisa de preencher a API Key no local apropriado e direcionar o agente/Skill para esse modelo.
A API Key não se trata apenas de "pode ou não pode usá-la", mas também afeta "que capacidades, custo e estabilidade":
- Seleção de modelo: Diferentes chaves/modelos podem fornecer diferente qualidade de raciocínio, velocidade e desempenho do formato de saída.
- Controlo de custos: Algumas plataformas cobram por uso; a conta/cota da chave afeta o orçamento disponível.
- Limites de permissões: Algumas chaves de serviço podem permitir apenas chamadas de API limitadas, fazendo com que a execução de um Skill específico falhe.
Resolução de problemas comum para "falha na chamada do Skill":
Confirme se a chave está preenchida corretamente, se a chave expirou/tem cota insuficiente,
se essa chave tem permissões de chamada.
Se a API devolver um erro de autenticação (401/403), suspeite primeiro da configuração da API Key.
Quando deve estudar estes conceitos a sério? (Referência rápida)
- Está a construir uma automatização de vários passos: O Workflow determina se a cadeia pode ser executada de forma estável.
- Está a integrar o Feishu/sistemas empresariais/APIs externas: O JSON determina se os dados são transferidos corretamente e podem ser analisados.
- Está a integrar o seu próprio modelo ou serviço personalizado: A API Key determina se pode chamar a capacidade correspondente.
- Está a depurar "pode explicar mas não pode executar" ou "a execução falha sem pistas": Normalmente, a resolução de problemas mais rápida é verificar o encadeamento do Workflow, a estrutura JSON e as permissões da API Key por ordem.
O Workflow faz com que os passos sejam executados de forma fiável em sequência, o JSON faz com que os dados passados em cada passo estejam corretamente estruturados e sejam utilizáveis, a API Key faz com que as ferramentas e os modelos sejam realmente invocáveis. Juntos, transformam a sua automatização de "parece inteligente" para "realmente funciona na prática".
Agent = Colega de IA capaz
Skill = Módulo de capacidade invocável (ferramenta/interface/processo)
Prompt = Diz ao agente como fazer (regras, acionadores, saída, tratamento de erros)
Memory = Preferências e POPs de longo prazo (torna as regras eficazes a longo prazo)
Soul = Constituição do comportamento e limites (estratégia de permitir/proibir/confirmar)
Workflow = Caminho de execução de corrida de estafetas de vários passos
JSON = Formato estruturado de troca de dados (garante a usabilidade dos campos)
API Key = Credencial de integração de terceiros/modelo (garante a capacidade de invocação)