Como criar agentes personalizados

Um agente personalizado é um ajudante que você mesmo escreve: as instruções são suas, assim como a decisão de quando ele roda e do que ele pode alterar. Crie um quando nenhum agente para download fizer o que você quer. Se um agente instalado chegar perto, passe o mouse sobre o cartão dele no painel Agents (agentes) e clique em Copy agent (copiar agente) para ganhar uma cópia editável.

Antes de começar: leia Agentes: ajudantes de IA para os seus chats. Criar um agente não faz ele rodar. Depois, você adiciona o agente a um chat. Os agentes personalizados funcionam em todos os modos de chat.

Como criar um agente personalizado

  1. Abra o painel Agents.
  2. Clique em New (o ícone de mais), perto do topo. O editor de agentes abre em tela cheia.
  3. Digite um nome no campo de título, por exemplo Weather Reporter.
  4. Preencha Description (descrição) e Author (autor).
  5. Escolha uma Pipeline Phase (veja Pipeline Phase).
  6. Ative os poderes de que ele precisa em Custom Agent Abilities.
  7. Escolha um Result Type que combine com o que o agente produz. Se estiver em dúvida, escolha Context Injection. Ele não exige nenhuma habilidade nem um formato de saída rígido.
  8. Escreva as instruções do agente em Prompt Template (modelo de prompt).
  9. Clique em Save na barra superior. Um selo verde Saved aparece.

O agente passa a aparecer na seção Custom Agents do painel Agents. Para usar o agente, abra um chat, vá em Chat Settings (configurações do chat), ative Enable Agents e adicione o agente pela seção Custom Agents.

Pipeline Phase

A Pipeline Phase (fase do fluxo) define quando o agente roda.

Certos tipos de resultado forçam uma fase. Text Rewrite muda a fase para Post-Processing. Prompt Patch e Character Activity mudam a fase para Pre-Generation.

Os agentes de Post-Processing ganham também uma seção Turn Data Access, com dois botões liga/desliga: Pre-generation injections e Parallel agent results. Ative-os para que o agente leia o que os outros agentes produziram no mesmo turno.

Custom Agent Abilities

As habilidades são poderes que você escolhe ativar. Cada uma fica bloqueada até você ligar o botão liga/desliga dela.

Ao ativar Edit lorebooks, surge uma seção Lorebook Writer. Ative Allow lorebook entry writes e escolha um lorebook em Target lorebook. O agente só consegue escrever nesse lorebook.

Result Type

O Result Type (tipo de resultado) diz a Marinara como interpretar a resposta do agente. A maioria dos tipos espera JSON, um formato de texto escrito com chaves e aspas. Um tipo fica acinzentado até você ativar a habilidade de que ele precisa.

Tipos que não exigem nenhuma habilidade:

Tipos que exigem Edit messages:

Tipos que exigem Edit trackers:

Outros tipos, cada um com a própria habilidade:

Controles por chat para agentes de imagem

Um agente com a habilidade Image generation ganha dois controles extras em Chat Settings → Agents → Custom Agents.

Activation Keywords

Por padrão, um agente roda na cadência normal dele (a frequência com que ele roda). As Activation Keywords (palavras-chave de ativação) pulam o agente quando a cena não é relevante, o que economiza tokens.

  1. Em Activation Keywords, digite uma palavra-chave ou frase por linha, como tavern ou secret door.
  2. Ajuste Scan Depth para o número de mensagens recentes a pesquisar. O padrão é 5 e o máximo é 200.

A partir daí, o agente só roda quando uma palavra-chave aparece nessas mensagens. Deixe a caixa vazia para desativar o filtro. A cadência e qualquer pergunta de ativação continuam valendo.

Como anexar ferramentas

Um agente pode chamar ferramentas: funções que a IA executa para buscar ou alterar alguma coisa e cujo resultado ela lê em seguida. Isso também se chama function calling.

  1. No editor de agentes, abra Tools / Function Calling e ative cada ferramenta que você quiser. A lista traz as ferramentas nativas e as suas próprias. Para criar uma, veja Ferramentas personalizadas.
  2. Em Chat Settings, abra Function Calling e ative Enable Tool Use. Sem isso, as ferramentas do agente continuam desligadas.

Agentes importados nunca recebem acesso a ferramentas. Revise um agente importado e depois selecione você mesmo as ferramentas dele.

Um agente recebe no máximo 16 rodadas de chamadas de ferramenta por execução (menos, se o MAX_TOOL_ROUNDS do servidor for menor) e depois responde com o que tiver. Um modelo que chama uma ferramenta por vez gasta uma rodada em cada chamada, então um agente que salva muitas entradas deve fazer várias chamadas em uma mesma resposta. Uma execução de preenchimento retroativo de lorebook recebe até 64 rodadas.

Named prompt options

Um agente pode guardar várias variações de prompt, para que cada chat escolha uma sem precisar editar o agente.

  1. Em Prompt Template, localize Named prompt options.
  2. Clique em Add option (adicionar opção).
  3. Dê à opção um nome e uma descrição curta e depois escreva o prompt completo dela.

Quando alguém adiciona o agente a um chat, um menu suspenso Prompt Mode lista as suas opções. Sem nenhuma opção, só o prompt padrão aparece.

Outras configurações

Macros como {{user}} e {{char}} funcionam no Prompt Template. Veja Macros.

Um exemplo completo

Este agente reescreve cada resposta em inglês britânico.

  1. Dê a ele o nome British English Editor.
  2. Em Custom Agent Abilities, ative Edit messages.
  3. Em Result Type, escolha Text Rewrite. A fase muda para Post-Processing.
  4. Cole isto em Prompt Template:
   You are a copy editor. Rewrite the latest reply into British English.
   Change spelling and vocabulary only. Do not change the meaning, tone, or events.
   Return JSON with an "editedText" field holding the full rewritten reply,
   and a "changes" array of short notes describing what you changed.
  1. Clique em Save.
  2. Abra um chat de Roleplay, ative Enable Agents em Chat Settings e adicione o agente pela seção Custom Agents.

Depois de cada resposta, o agente devolve um JSON como este:

{"editedText":"The colour of the harbour caught her eye.","changes":[{"description":"color to colour, harbor to harbour"}]}

Marinara coloca o editedText no lugar da resposta. As anotações de changes aparecem como um resumo curto.

Como importar e exportar agentes

Para exportar um agente, clique em Export agent (o ícone de upload) na barra superior do editor. O arquivo guarda o prompt e as configurações do agente, nunca definições de ferramentas personalizadas. Para exportar vários, use Select agents no painel Agents, escolha os agentes e exporte.

As importações externas vêm bloqueadas por padrão.

  1. Abra Settings → Advanced → Danger Zone (Configurações → Avançado → Zona de perigo) e ative Allow custom Agent imports. Nenhuma alteração no .env é necessária.
  2. No painel Agents, clique em Import agents e escolha arquivos de agente ou uma pasta.
  3. Revise a lista de permissões que Marinara mostra. Aprove só o que o agente precisa. As capacidades não marcadas continuam bloqueadas.

Esse bloqueio afeta apenas agentes vindos de arquivos, pastas ou repositórios personalizados. Os agentes que você cria e os agentes oficiais do Agent Organizer (organizador de agentes) funcionam normalmente. Cada arquivo importado recebe uma nova identidade personalizada, então não consegue substituir um agente oficial.

Por segurança, Marinara ignora funções embutidas no pacote, limpa as ferramentas selecionadas, higieniza o CSS temporário e confere as capacidades aprovadas antes que um agente importado possa alterar mensagens, trackers, lorebooks, planos de fundo, sprites, mídia, dispositivos hápticos, dados de About Me, prompts ou imagens. Importe funções confiáveis separadamente, revise essas funções e anexe-as você mesmo ao agente. Desligar o botão da Danger Zone faz os agentes importados pararem de rodar.

Perguntas de ativação

Uma pergunta de ativação pergunta se a cena recente precisa do seu agente. Ela reconhece paráfrases que as palavras-chave deixam passar. Ela exige um Decision model (modelo de decisão), um modelo pequeno que responde a perguntas de sim ou não. Escolha um no painel Connections. Veja Modelos de decisão. Com Decision model em None (nenhum), o padrão, os campos de pergunta ficam desativados, e um agente com pergunta roda como se não tivesse nenhuma.

  1. Abra o agente personalizado.
  2. Digite uma Question (pergunta) de até 500 caracteres. As macros {{user}} e {{char}} funcionam nela.
  3. Ajuste Run when probability is at least (rodar quando a probabilidade for pelo menos) para o limiar deste agente. O agente roda quando a probabilidade de "sim" atinge esse limiar, então valores maiores pulam mais execuções. O editor mostra um valor recomendado para o seu modelo: 0,5 para modelos de chat locais e contas Decision, ou 0,1 para os modelos Open-Jev integrados. Confira esse valor nos seus próprios chats depois de trocar de modelo. Veja Limiares.
  4. Opcional: ajuste Bypass the question after this many messages without a successful run (ignorar a pergunta após este número de mensagens sem uma execução bem-sucedida). Depois desse número de mensagens, a pergunta é ignorada, então um modelo que continua respondendo "não" não consegue silenciar o agente para sempre. Palavras-chave e cadência continuam valendo.

Escreva a pergunta como uma declaração sobre a mensagem mais recente, como The latest message moves the scene to a new place. Um modelo pequeno respondeu a isso com mais confiabilidade do que a Did the scene change? Veja Escrever declarações.

Como funciona:

As perguntas de ativação valem só para agentes personalizados.

Declarações de decisão no prompt do agente

Uma pergunta de ativação decide se o agente roda. Uma declaração de decisão no Prompt Template decide o que um agente em execução recebe como instrução. A sintaxe está em Prompts condicionais:

{{#if decision:"In the latest message, the characters move to a different location"}}
Update the location field.
{{else}}
Leave the location as it is.
{{/if}}

Use-as para enviar um prompt menor nos turnos tranquilos. Um tracker pode atualizar o local só quando ele mudou. Um agente de imagens pode descrever uma nova imagem só quando a cena mudou. Um agente de música pode trocar de faixa só quando o clima mudou. Para escolher um entre vários conjuntos de instruções, use {{#if decision_choice:"The kind of scene in the latest message" == "combat"}}, depois {{else if decision_choice:"The kind of scene in the latest message" == "dialogue"}}, e assim por diante. Veja Prompts condicionais.

Agentes instalados pelo Marinara-Agents processam os prompts da mesma forma.

Guias relacionados