Como controlar agentes de IA pela CLI: um guia prático

Por que controlar um agente pela linha de comando, afinal

Construo integrações para viver, então admito meu viés: prefiro rodar algo de um terminal a clicar por uma página de configurações que preciso reaprender a cada trimestre. Mas o argumento aqui é maior que gosto pessoal.

Um painel é um bom lugar para entender um agente. É um lugar ruim para operar um em qualquer escala. No momento em que você quer aplicar a mesma mudança a três agentes, ou uma configuração que vive em um repositório Git ao lado do resto da sua infraestrutura, ou um rollout que um job de CI possa executar sem um humano, o navegador vira o gargalo. Tudo o que você faz manualmente é um passo que não pode repetir, revisar ou reverter de forma limpa.

A linha de comando resolve isso transformando as operações do agente em texto. Um comando que você pode colar em um runbook. Uma configuração que você pode comparar com diff. Uma execução que você pode disparar de um cron job ou de um webhook. E, cada vez mais, uma superfície que outro agente de IA pode operar, que é exatamente por isso que a documentação do eesel diz para agentes de programação usarem a CLI em vez de tentar clicar pelo painel em um navegador.

O restante deste guia percorre esse ciclo passo a passo. Vou usar a CLI do eesel para os comandos concretos porque é a que sei ser real e sobre a qual posso te apontar a documentação, mas o formato se aplica a qualquer plataforma de agentes que leve o terminal a sério.

O que você precisa antes de começar

Três coisas, e nenhuma delas demora muito.

• Um Node.js recente. A CLI do eesel precisa do Node 18.17 ou mais recente. A maioria das máquinas fabricadas nos últimos anos já tem isso.
• Uma plataforma de agentes com uma CLI de verdade. Este é o ponto a checar com cuidado. Muitas ferramentas se anunciam como "amigáveis a desenvolvedores" e depois entregam uma página de configurações. Procure documentação de CLI publicada com uma lista real de comandos antes de se comprometer.
• Uma fonte de dados para conectar. Para um agente de suporte isso significa um helpdesk, uma base de conhecimento ou tickets passados. O agente é tão bom quanto o que ele consegue ler.

Você não precisa necessariamente de uma conta para começar. A CLI do eesel pode subir um workspace anônimo para você testar uma bolha em um site sem nenhum cadastro, o que é uma boa forma de ver o fluxo inteiro antes de decidir qualquer coisa.

Passo 1: instalar a CLI e fazer login

Há três formas de conseguir a CLI do eesel, e elas correspondem a três situações diferentes.

Se você só quer experimentá-la em um site com zero comprometimento:

npx @eesel/cli init chat-bubble --site https://your-site.com

Isso roda sem uma conta e sobe um workspace anônimo. Se você quer instalá-la de verdade, pegue-a globalmente do npm:

npm i -g @eesel/cli

ou use o script de instalação:

curl -fsSL https://dashboard.eesel.ai/eesel-cli/install | sh

Depois de instalada, autentique-se:

eesel login
eesel whoami

eesel login abre o navegador uma vez para vincular o terminal ao seu workspace, e whoami confirma com qual conta e agente você está conectado. A partir daqui você pode ficar no terminal.

Um detalhe que vale a pena destacar para quem for scriptar isso: todo comando imprime JSON, e listas imprimem um objeto por linha. Isso significa que você pode canalizar a saída direto para o jq ou para um script sem precisar raspar texto legível por humanos. Você também pode restringir a saída com --fields (por exemplo --fields id,status) para que um script veja apenas as chaves de que precisa.

Passo 2: conectar um helpdesk ou fonte de dados

Um agente sem nada para ler é um truque de festa. A primeira coisa real que você faz é dar a ele uma fonte.

eesel integrations connect zendesk

Troque zendesk pela plataforma que você usa. O eesel se conecta com Zendesk, Freshdesk, Gorgias, Front, Help Scout, HubSpot, Salesforce e Jira Service Management, entre outros. O comando cuida do handshake OAuth e avisa quando a fonte está ativa.

Verifique o estado a qualquer momento:

eesel status

status diz o que está conectado, o que o agente conhece e se algo ainda está sincronizando. É o comando que mais executo, porque responde à única pergunta que importa no meio da configuração: isso já está realmente pronto.

Passo 3: definir as instruções do agente

Aqui é onde o "controle" se torna real. As instruções são as regras permanentes que o agente segue: tom, o que ele pode responder, quando deve escalar, quais ações pode tomar por conta própria.

eesel instructions

Isso lê as instruções atuais para que você veja exatamente sob quais regras o agente está operando, e permite editá-las. Como é texto, você pode manter suas instruções em um arquivo sob controle de versão e tratar uma mudança no comportamento do agente como qualquer outra mudança revisada, com diff e histórico, em vez de uma edição misteriosa que alguém fez em um painel de configurações três semanas atrás.

Se você levar apenas um hábito deste guia, que seja esse. O comportamento de um agente derivar porque ninguém consegue ver quem mudou o quê é a forma mais comum de esses rollouts darem errado silenciosamente.

Passo 4: simular antes de soltá-lo

Aqui está a parte que a maioria das pessoas pula, e a parte pela qual eu lutaria.

Passamos anos colocando agentes de IA em filas de suporte ao vivo, e a lição que ficou foi que um bot que soa confiante não é o mesmo que um correto. Um modelo dará de bom grado uma resposta errada com uma voz tranquilizadora. A única forma de pegar isso antes que um cliente pegue é testá-lo contra a realidade primeiro.

O eesel faz isso como uma simulação que reproduz seus tickets passados e pontua as respostas do agente contra o que sua equipe realmente enviou. Você a invoca pedindo, por exemplo, para rodar uma simulação sobre seus tickets recentes. Ela devolve onde o agente teria batido com sua equipe, onde teria errado e o que mudar nas instruções. Uma coisa que ela deliberadamente não faz é inventar uma taxa de resolução ou uma previsão de custo, e eu ficaria desconfiado de qualquer ferramenta que afirme fazer isso, porque esse número é um palpite disfarçado de medição.

Rode a simulação, leia as lacunas, corrija as instruções do Passo 3 e rode de novo. Esse ciclo é todo o sentido de fazer isso pelo terminal: cada passagem é um comando que você pode repetir, não um clique a clique que você precisa lembrar.

Passo 5: disparar execuções e ler o log de atividade

Agora você o opera. Converse com o agente diretamente:

eesel chat "Where is my order #DL-4821?"

E leia o que ele tem feito, mais recente primeiro:

eesel activity

eesel activity é a superfície de observabilidade. Ela lista execuções para que você possa identificar padrões, e você pode abrir uma execução individual para ver exatamente o que o agente leu, decidiu e fez. Quando algo parece estranho, é aqui que você olha antes de qualquer outra coisa. Erros também são estruturados: um comando que falha imprime uma única linha JSON no stderr com um error, uma hint e se é retryable, e sai com um código diferente de zero. É isso que torna a CLI segura para conectar a um job de CI. Um script consegue diferenciar entre "você digitou o comando errado" e "o serviço teve um soluço, tente de novo".

Passo 6: proteger ações com aprovações

Você não precisa escolher entre um agente totalmente autônomo e um inútil. O meio-termo é uma fila de aprovações com humano no loop, e ela é um recurso de primeira classe na linha de comando.

eesel approvals list
eesel approvals approve <id>
eesel approvals deny <id>

Quando o agente quer realizar uma ação em que você ainda não confia totalmente, ela cai na fila de aprovações em vez de simplesmente acontecer. Você a revisa pelo terminal e aprova ou nega. Assim que um determinado tipo de ação ganhar sua confiança, promova-a a automática:

eesel approvals approve <id> --always

É assim que você aumenta a autonomia gradualmente em vez de virar uma chave assustadora. Comece com tudo protegido, observe o que o agente propõe, e use --always para entregar as ações que você já viu que ele acerta, uma categoria de cada vez.

Além da CLI: as outras três superfícies de controle

A CLI é a superfície em que você vai viver, mas não é a única forma de operar o agente. Ajuda ver o conjunto completo, porque cada uma responde a uma pergunta diferente.

• Servidor MCP, para quando outra IA é a operadora. Todo workspace do eesel também é um servidor MCP. Executar npx @eesel/cli mcp token imprime uma URL, um token de 30 dias e um comando claude mcp add pronto para colar, para que um cliente como o Claude possa chamar as mesmas operações como ferramentas. É assim que você deixa um agente de programação gerenciar seu agente de suporte.
• Webhooks, para quando um evento externo deve acionar o agente. Uma URL de webhook exclusiva acorda o agente quando algo acontece em outro lugar da sua stack, para que um novo pedido ou o envio de um formulário possa iniciar uma execução sem que ninguém digite um comando.
• Network Access, para quando o agente precisa se comunicar para fora. Você libera um domínio e anexa um cabeçalho de autenticação, e o agente pode então chamar essa API REST com GET, POST, PATCH ou DELETE durante uma execução. As credenciais são armazenadas como cabeçalhos e nunca são mostradas ao modelo, que é o detalhe que sua equipe de segurança vai perguntar.

Para ambientes headless, você pula o login interativo por completo: defina EESEL_API_URL e EESEL_API_TOKEN (e EESEL_AGENT_ID para fixar um agente específico) como variáveis de ambiente, e a CLI se autentica a partir delas. É isso que faz ela se encaixar de forma limpa em um pipeline de CI.

Erros comuns a evitar

Algumas coisas que já vi atrapalharem pessoas, para você pular a lição:

• Ir para produção sem simular. O erro mais caro desta lista. Execute o Passo 4. Sempre.
• Editar instruções manualmente com pressa. Se o comportamento do seu agente não está sob controle de versão, você eventualmente terá uma pane que ninguém consegue explicar. Trate a saída de eesel instructions como código.
• Ativar autonomia total no primeiro dia. Comece com tudo na fila de aprovações e ganhe cada promoção --always. Confiança se constrói uma categoria de ação de cada vez.
• Ignorar os códigos de saída. A CLI retorna erros estruturados e saídas diferentes de zero por um motivo. Um script que não os verifica vai passar alegremente por cima de uma falha.
• Presumir que existe uma API REST. Se você está avaliando um fornecedor e seu plano depende de um endpoint REST documentado, confirme que ele existe antes de construir em cima dele. Com o eesel, a resposta honesta é que a CLI, o MCP, os webhooks e o Network Access são a superfície, e isso é suficiente para controlar um agente, só que não é o mesmo que um produto REST.

Experimente o eesel

Se você quer um agente de suporte que possa realmente operar pelo terminal, o eesel foi feito para isso. A CLI se instala em um comando, conecta ao helpdesk que você já usa, simula contra seus tickets passados reais antes de tocar em uma conversa ao vivo, e mantém cada ação atrás de uma fila de aprovações até você dizer o contrário. O preço é baseado em uso, a 40 centavos de dólar por ticket atendido, e o teste gratuito inclui 50 dólares de uso sem cartão de crédito, para que você possa scriptar todo o rollout e ver funcionando antes de gastar qualquer coisa.