Pepedocs

Introdução

O Pepe corre agentes de IA na tua própria máquina. Descreve quem eles são, liga qualquer modelo compatível com OpenAI e deixa-os fazer trabalho a sério com ferramentas. Sem servidor de base de dados, sem dependência de fornecedor.

O que é o Pepe

O Pepe corre agentes de IA na tua própria máquina ou servidor. Descreves um agente uma vez (um nome, as suas instruções, as ferramentas que pode usar e o modelo com que pensa) e o Pepe trata do resto: quando chega um pedido, o agente trabalha por etapas, usando as suas ferramentas, até ter uma resposta a sério.

Os agentes vivem muito tempo: conversas, canais, tarefas em segundo plano, não pedidos avulsos. O Pepe é construído em Elixir/OTP, uma tecnologia feita exatamente para esse tipo de trabalho, por isso um servidor modesto mantém uma equipa inteira de agentes a correr lado a lado sem gastar muita memória nem CPU.

Esse ciclo interno é a razão de ser de tudo. Uma simples chamada de chat devolve texto. Um agente consegue mesmo fazer coisas: ler um ficheiro, correr um comando, pesquisar na web, chamar a tua API, e depois raciocinar sobre o que encontrou e continuar. O Pepe entrega-te esse ciclo como um runtime acabado, em vez de algo que montas à mão em cada projeto.

pepe run "lê o package.json e diz que dependências estão desatualizadas"

Defines o comportamento uma vez, e o mesmo agente fica acessível de quatro formas: a partir do terminal, por uma API HTTP compatível com OpenAI, por um WebSocket com streaming, e a partir de canais de mensagens como o Telegram e o WhatsApp. Existe ainda um painel web para navegar e conversar a partir do browser. Responde a cada caso de uso ali onde ele já vive, sem criar um agente separado para cada canal.

O ciclo de chamada de ferramentas

Este é o ciclo que o Pepe corre em cada turno:

  1. Envia a conversa, junto com as definições de ferramentas do agente, para o modelo.
  2. Se o modelo devolver chamadas de ferramentas, executa cada uma e recolhe a saída.
  3. Anexa a mensagem do assistente e os resultados das ferramentas à conversa.
  4. Volta ao passo 1. Para quando o modelo devolve uma resposta simples, ou quando o agente atinge o seu limite de segurança max_iterations.

Pelo caminho, o Pepe anuncia cada passo, para que qualquer superfície possa mostrar o progresso em tempo real: a resposta à medida que chega em streaming (assistant_delta), cada chamada de ferramenta e o seu resultado (tool_call, tool_result), a resposta final (done) e os erros (error).

As ferramentas arriscadas (qualquer uma que corra um comando ou escreva um ficheiro) podem ser configuradas para te pedir autorização primeiro. Se recusares, a ferramenta nunca corre: o modelo recebe apenas uma breve nota de “negado” (e é emitido um evento tool_denied), de modo que um agente nunca atua em silêncio na tua máquina sem o teu consentimento.

Ferramentas incorporadas. Cada agente pode receber ferramentas como bash, read_file, write_file, edit_file, list_dir, fetch_url e web_search. Escolhes quais é que cada agente recebe ao criá-lo, por isso um bot de apoio e um agente de programação podem ter poderes muito diferentes.

As cinco superfícies

Constróis um agente uma vez. O Pepe expõe-o depois pela superfície que melhor serve a tarefa. A configuração e a gestão, por sua vez, acontecem de três maneiras: a CLI pepe, o painel web e pela conversa (falando em linguagem natural com um agente que possui a ferramenta de gestão adequada).

CLI

O comando pepe é a forma de configurares as coisas e de correres agentes a partir de um terminal. As execuções pontuais transmitem a resposta diretamente para a saída padrão, e pepe chat abre uma sessão interativa que se lembra da conversa.

pepe run assistant "resume o git log da última semana"
pepe chat assistant

Painel web

Corre o servidor e abre o painel num browser para conversar com um agente, navegar por sessões anteriores e gerir agentes, ligações a modelos, canais, tarefas agendadas, utilização e traces por uma interface de apontar e clicar. Em localhost está aberto por omissão; podes protegê-lo atrás de uma palavra-passe de operador quando o expuseres.

pepe serve --port 4000
# depois abre http://localhost:4000

API HTTP compatível com OpenAI

Arranca o servidor e o Pepe fala o protocolo Chat Completions da OpenAI, por isso qualquer SDK da OpenAI, LangChain ou um simples curl conseguem falar com ele sem adaptador. Serve POST /v1/chat/completions e GET /v1/models.

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "assistant",
    "messages": [{"role": "user", "content": "que ficheiros existem neste projeto?"}]
  }'

Aponta um cliente OpenAI existente para http://localhost:4000/v1 e o nome do modelo passa a ser o nome do teu agente. Vê a página da API HTTP para streaming, eventos de ferramentas e autenticação.

WebSocket

Para conversas ao vivo, token a token, numa app web ou móvel, liga-te por um WebSocket e subscreve o tópico do teu agente (agent:<name>). Recebes o texto do assistente à medida que é transmitido, além de eventos para cada chamada e resultado de ferramenta. Os detalhes e um exemplo de cliente estão na página da API.

Canais de mensagens

Coloca o mesmo agente à frente de utilizadores reais nas plataformas que eles já usam. O Pepe traz gateways para Telegram, WhatsApp, Slack, Discord, Microsoft Teams e Google Chat, além de um webhook de entrada genérico para qualquer outra coisa. Cada canal liga-se a um agente e mantém a sua própria memória de conversa por utilizador. Vê a página de canais.

Definir um agente

Um agente é apenas um nome, um prompt de sistema, uma lista de ferramentas e um modelo. Cria um pela CLI:

pepe agent add assistant \
  --prompt "És o Pepe, um agente de programação prestável." \
  --tools bash,read_file,write_file,edit_file,list_dir,fetch_url,web_search \
  --default

Também podes fazê-lo no painel web, na página Agents, que inclui um formulário para a persona, o modelo e a seleção de ferramentas.

Fá-lo pela conversa

Um agente que possui a ferramenta manage_agent consegue criar e moldar outros agentes diretamente a partir de uma conversa. Envia-lhe uma mensagem simples:

Tu: Cria um novo agente chamado “researcher” cuja função é vasculhar a documentação e resumir descobertas, e dá-lhe web_search e fetch_url.

O agente usa manage_agent para create o novo agente, definir a sua persona e adicionar cada ferramenta. manage_agent é uma capacidade protegida: o agente só pode mexer nos agentes da sua própria lista de permitidos, é instruído a confirmar as alterações contigo primeiro, e por ser uma ferramenta arriscada, cada chamada passa ainda pela barreira de permissão antes de algo ser escrito. Assim vês a alteração proposta e podes aprová-la antes de ela ter efeito.

Ligar um modelo

O Pepe nunca inclui um modelo ou uma chave. Aponta-o para qualquer fornecedor compatível com OpenAI através de uma ligação de modelo:

pepe model add openrouter \
  --api-key '${OPENROUTER_API_KEY}' \
  --model openai/gpt-5-chat \
  --default

A página Models do painel faz o mesmo com um formulário, e pode testar uma ligação antes de a guardares. Repara no ${OPENROUTER_API_KEY}: os segredos são guardados como referências a variáveis de ambiente e expandidos apenas na leitura, por isso as tuas chaves nunca são escritas de volta no disco em texto simples.

Adicionar um canal

Liga um agente a um canal de mensagens para que as pessoas possam falar com ele onde já estão. No painel, a página Channels guia-te pela ligação de um bot e pela escolha de com que agente ele conversa. O canal mantém então uma memória de conversa separada por utilizador.

Fá-lo pela conversa

Um agente que possui a ferramenta manage_channel consegue levantar um bot do Telegram a partir de uma conversa:

Tu: Adiciona um bot do Telegram chamado “support-bot” que fala com o agente de apoio. O token está na variável de ambiente SUPPORT_BOT_TOKEN.

O agente usa manage_channel para adicionar o bot e ligá-lo ao agente indicado. Esta capacidade é deliberadamente protegida: só mexe em bots com nome (nunca o predefinido protegido), é instruída a confirmar os detalhes contigo primeiro, e é uma ferramenta arriscada, por isso a chamada passa pela barreira de permissão. E o mais importante: dás o nome de uma variável de ambiente que contém o token, nunca o token em si, de modo que o segredo nunca passa pelo chat nem pelo modelo. Depois da alteração, o bot em execução entra no ar ao vivo, sem reiniciar.

Decisões de arquitetura que simplificam a utilização

Auto-alojado, as tuas chaves, os teus dados

O Pepe nunca inclui um modelo ou uma chave de API. Corre-o na tua própria máquina ou servidor, e apontas para o fornecedor que quiseres. Nada de uma conversa sai da tua infraestrutura, exceto as chamadas que configuras para o endpoint do modelo que escolheste.

Agnóstico de modelo

Como cada fornecedor é alcançado pelo mesmo protocolo Chat Completions da OpenAI, trocar de modelo é uma alteração de configuração, não de código. OpenAI, OpenRouter, Together, Groq, DeepSeek, Mistral e servidores locais como Ollama, LM Studio e vLLM funcionam todos da mesma forma. Uma ligação de modelo pode até listar modelos de fallback, por isso uma falha transitória (um limite de taxa, um erro de servidor, uma oscilação de rede) num fornecedor passa discretamente para o seguinte, enquanto uma chave inválida ou um pedido malformado falha de imediato, em vez de tentar de novo sem propósito.

Sem base de dados

Toda a configuração (ligações de modelo, agentes, canais, agendamentos) vive num único ficheiro JSON em ~/.pepe/config.json, fácil de ler, editar e guardar como cópia de segurança. Não há nada para instalar ao lado do Pepe nem nada para migrar. Os segredos são escritos como referências ${ENV_VAR} e expandidos apenas na leitura, por isso as tuas chaves nunca são escritas de volta no disco em texto simples.

{
  "models": {
    "openrouter": {
      "base_url": "https://openrouter.ai/api/v1",
      "api_key": "${OPENROUTER_API_KEY}",
      "model": "openai/gpt-5-chat"
    }
  }
}

Conversas isoladas

Cada conversa corre separada de todas as outras. Se uma correr mal, as restantes nem dão por isso: um único turno defeituoso não consegue deitar abaixo os teus outros agentes nem as tuas outras conversas.

Multi-tenant quando precisas

O trabalho pode ser limitado a um projeto, isolando agentes, canais, modelos e utilização por projeto. Se nunca criares outro, tudo vive no projeto default, para o qual cada comando recorre por omissão, e podes ignorar os projetos por completo.

Para onde ir a seguir

Instalação →