Modo Agente: Execução de Tarefas

​

Como Iniciar

/agent encontre todos os arquivos de log modificados nas últimas 24h e copie para 'logs_recentes'

​

O Ciclo do Agente

​

Como o Agente Funciona Internamente

​

O Loop ReAct

1. Construção do histórico — O histórico de conversa é montado com um anchor reminder (lembrete de formato) anexado ao final. Esse anchor reforça para a IA o formato de resposta esperado, evitando que ela “esqueça” as instruções ao longo de conversas longas.
2. Chamada ao LLM — O histórico completo é enviado ao provedor de IA configurado.
3. Parse da resposta — A resposta é analisada para extrair raciocínio, explicações, chamadas de ferramentas e comandos.
4. Execução das ações — Ferramentas e comandos são executados com os devidos controles de segurança.
5. Injeção de feedback — O resultado da execução é injetado de volta no histórico como mensagem de contexto.
6. Próximo turno — O loop retorna ao passo 1, até que a IA conclua a tarefa ou o limite de turnos seja atingido.

​

Composição do System Prompt

• Contexto do workspace — Arquivos bootstrap como SOUL.md, USER.md e memória persistente
• Descrição das ferramentas — Lista completa dos plugins disponíveis e seus parâmetros
• Persona ativa — Se uma persona customizada estiver configurada, ela é incluída
• Instruções de formato — As AgentFormatInstructions que definem o formato esperado da resposta

​

Formato de Resposta da IA

​

Cancelamento e Ctrl+C

• Durante chamada ao LLM — Ctrl+C cancela a requisição via context.WithCancel(). A resposta parcial recebida até aquele momento é descartada.
• Verificação por turno — No início de cada turno do loop ReAct, o agente verifica context.Done(). Se o contexto foi cancelado, o loop encerra imediatamente.
• Tratamento de sinais — SIGINT e SIGTERM são capturados pela função runWithCancellation(), que coordena o shutdown gracioso.
• Fila type-ahead — Mensagens digitadas pelo usuário durante o processamento da IA são enfileiradas e processadas assim que o turno atual terminar. Isso evita perda de input.

​

Histórico e Compactação

​

Estratégia de Compactação

1. Trimming — Mensagens de contexto injetadas (resultados de ferramentas, outputs de comandos) com mais de 3000 caracteres são truncadas, preservando início e fim.
2. Sumarização — Mensagens intermediárias são resumidas pela própria IA, mantendo os pontos-chave.
3. Truncamento de emergência — Se os níveis anteriores não forem suficientes, as mensagens mais antigas são removidas.

​

Checkpoint e /rewind

​

Interface do Plano de Ação

PLANO (visão compacta)
  #1: Criar o diretório de destino -- mkdir -p logs_recentes
  #2: Encontrar e copiar os arquivos -- find ~ -name "*.log" -mtime -1 -exec cp {} logs_recentes/ \;

COMANDO #2: Encontrar e copiar os arquivos
    Tipo:   shell
    Risco:  Seguro
    Status: Pendente
    Código:
      $ find ~ -name "*.log" -mtime -1 -exec cp {} logs_recentes/ \;

​

Menu Interativo

​

Segurança

​

Segurança do Modo Agente

​

Allowlist de Comandos (CHATCLI_AGENT_SECURITY_MODE)

export CHATCLI_AGENT_SECURITY_MODE=strict

export CHATCLI_AGENT_SECURITY_MODE=permissive

# Adicionar terraform e ansible a allowlist
export CHATCLI_AGENT_ALLOWLIST="terraform;ansible;packer"

# O agente tenta executar "terraform plan" mas é bloqueado no modo strict
# Erro: "command 'terraform' is not in the allowed commands list"

# Solução: adicionar terraform a allowlist
export CHATCLI_AGENT_ALLOWLIST="terraform"
# Agora "terraform plan", "terraform apply", etc. funcionam

​

Proteção de Caminhos Sensíveis (CHATCLI_AGENT_WORKSPACE_STRICT)

# Habilitar proteção de workspace
export CHATCLI_AGENT_WORKSPACE_STRICT=true

# Permitir acesso ao kubeconfig (para operações K8s)
export CHATCLI_AGENT_ALLOW_KUBECONFIG=true

# Permitir caminhos adicionais de leitura
export CHATCLI_AGENT_EXTRA_READ_PATHS="/opt/configs;/var/log/myapp"

​

Configuração de Shell (CHATCLI_AGENT_SOURCE_SHELL_CONFIG)

# Habilitar source da configuração do shell (opt-in)
export CHATCLI_AGENT_SOURCE_SHELL_CONFIG=true

• Propriedade do arquivo — O arquivo deve pertencer ao usuário atual
• Tamanho do arquivo — Limite de segurança para evitar source de arquivos muito grandes

​

Sanitização de Saída de Comandos

• Detecção de injeção de prompt — Padrões suspeitos na saída (ex: instruções para a IA ignorar regras) são detectados e sanitizados antes de serem injetados no contexto
• Limite de tamanho — Saídas de comandos são truncadas para evitar consumo excessivo de tokens

# Configurar limite de saída de comandos (padrão: 50000 caracteres)
export CHATCLI_MAX_COMMAND_OUTPUT=100000

​

Histórico Unificado e Contexto

• Iniciar uma conversa no chat, entrar no /agent, e a IA terá todo o contexto anterior
• Usar /compact para reduzir o histórico quando ficar grande
• Usar /rewind (ou Esc+Esc) para voltar a um ponto anterior da conversa

​

Configuração do Modo Agente

export CHATCLI_AGENT_PLUGIN_MAX_TURNS=100
export CHATCLI_AGENT_CMD_TIMEOUT=30m

​

One-Shot Mode (flag -p)

chatcli -p "liste todos os containers Docker parados"

​

Como funciona

1. A instrução é enviada ao LLM como um único turno (sem loop ReAct).
2. Uma animação de pensamento é exibida enquanto a IA processa.
3. Se a flag --auto-execute estiver ativa, o primeiro bloco de comando da resposta é executado automaticamente — mas apenas após passar pela verificação de comandos perigosos.
4. O resultado é exibido e o processo encerra.

​

Workspace e payloads grandes

​

Próximos Passos