Agente de IA especializado contra canivete suíço universal: como reduzimos a latência de resposta de 17 para 7,7 segundos

• Redução da latência de resposta: a mediana caiu de ~17 s (13,3–20,6 s) para 7,7 s (7,25–7,93 s)
• Compressão do prefixo de entrada: de 15.266 para 1.424 tokens por requisição (economia de 10,7 vezes sem alterar a lógica de negócio)
• Volume do núcleo determinístico: 766 linhas de um plugin Python de gamificação sobre SQLite e 342 linhas de um verificador de notação
• Teto prático do arquivo de personalidade: cerca de 20.000 bytes para o `SOUL.md` sem perda de atenção do modelo ao meio da instrução

A primeira tentação ao montar um agente de IA é dar a ele acesso a tudo de uma vez: terminal, navegador, busca na web, arquivos e servidores MCP. O choque de realidade veio em um tutor de xadrez infantil, erguido sobre um endpoint local `/v1/chat/completions`. A criança movia a peça no tabuleiro, e o comentário do treinador chegava 17 segundos depois — quando o jovem jogador já havia feito mais duas jogadas.

A análise mostrou que, dos 15.266 tokens do prefixo de entrada, quase 14.000 eram ocupados por esquemas JSON de ferramentas que nunca foram chamadas durante a partida de xadrez, além da coleta automática de informações do SO na inicialização. Além disso, o agente com acesso a `execute_code`, ante a menor dificuldade, começava a escrever e executar scripts no sandbox, transformando uma única jogada em vinte chamadas de API.

Como três linhas na configuração comprimem o prompt em 10,7 vezes e

eliminam a latência?

Para transformar o generalista pensativo em um serviço rápido, não foi preciso reescrever o código do plugin. Ajustamos três parâmetros na configuração do runtime:

1. Deixamos na plataforma `api_server` apenas um conjunto de ferramentas de domínio (`[chess]`), removendo os conjuntos de arquivos e shell. 2. Desativamos o `environment_probe`, que a cada inicialização consultava o host e inseria um retrato do ambiente no prompt de sistema. 3. Definimos `reasoning_effort: none` — já que os fatos táticos já são calculados pelo motor Stockfish, o modelo não precisa construir uma cadeia de raciocínio antes de responder; sua tarefa é narrar de forma viva o veredito já pronto.

Nas medições de controle com o cache aquecido, o tempo de resposta caiu de `13,3 / 17,3 / 20,6 s` para `7,25 / 7,74 / 7,93 s` (mediana de 7,7 s), e o consumo de tokens de entrada despencou 10,7 vezes — de 15.266 para 1.424. A redução do conjunto de ferramentas economiza tokens e protege o circuito contra iniciativas próprias no terminal, enquanto a desativação da etapa extra de raciocínio proporciona o principal ganho em segundos. Um detalhe importante: os perfis de ferramentas para o mensageiro e para o agendador (`cron`) são definidos separadamente — se esquecer de registrar o plugin na seção `cron`, o envio matinal vai silenciosamente tentar buscar dados por meio de leitura de arquivos.

Como dividir a personalidade em duas camadas e transferir o cálculo de

sequências para o SQLite?

A personalidade de um agente especializado é projetada em duas camadas: um bloco curto de gatilhos no `config.yaml` (10–15 linhas) define o despacho (`tutor_state` no início do diálogo, `tutor_record_lesson` após o exercício), enquanto o regulamento de tom e pedagogia vive no `SOUL.md`. O teto prático desse arquivo é de cerca de 20.000 bytes (nos meus bots, entre 6,7 e 19,9 KB): se inflado além disso, o modelo perde as regras do meio do texto.

O modelo de linguagem interpreta emoções muito bem, mas calcula mal datas, pontos de experiência e notas por rubricas. No tutor de idiomas, toda a matemática de gamificação (10 níveis de 0 a 8000 XP, marcos de sequência de 3 a 365 dias, 15 emblemas e cristais) foi transferida para um plugin Python de 766 linhas sobre SQLite:

```python if last_date == today: streak = max(1, prev_streak) elif last_date == yesterday or not last_date: streak = (prev_streak + 1) if last_date == yesterday else 1 else: gap_days = (parse_date(today) - parse_date(last_date)).days if freezes > 0 and gap_days == 2: freezes -= 1 streak = prev_streak + 1 events.append({"type": "freeze_used", "msg": "A congelação salvou a sequência de dias!"}) else: if prev_streak > 1: events.append({"type": "streak_reset", "old": prev_streak}) streak = 1 ```

A ferramenta retorna um array `events`, e no campo `description` do próprio esquema JSON da função fica embutida a diretriz: parabenizar o aluno emocionalmente por cada evento de `events`, sem inventar nada sobre o saldo por conta própria. Da mesma forma, no simulador de negociações de compras, uma rubrica de 4 módulos em escala de 40 pontos verifica marcadores-chave (riscos, checagem de fatos, negociação) por código, de modo que o participante não consiga «convencer» a rede neural a elevar a nota.

Por que o progresso zerava silenciosamente após o reinício e como

corrigir o framework?

Nas primeiras versões, o motor passava ao manipulador da ferramenta o parâmetro `task_id`, igual ao ID da sessão atual, e eu o usava como chave primária do aluno. Ao pressionar `/new` ou reiniciar o contêiner, era gerado um novo `task_id`, e a pessoa via uma folha em branco em vez de 30 dias de estudo. O problema foi resolvido com um resolvedor de chave em duas camadas, que extrai via regex o ID permanente da conta a partir de `telegram:dm:<user_id>` ou faz a verificação cruzada com `sessions.json`, garantindo uma chave estável `tg:<id>`.

Para não precisar reconstruir uma imagem de gigabytes a cada biblioteca nova, o deploy instala os pacotes via `pip install --target` no volume `data/pylibs`, aplica `chown -R` para um usuário não-root e limpa o `__pycache__`. E onde o transporte básico não tinha o teclado inferior ou engolia o `/start`, patches autocorretivos do `bootstrap.sh` verificam, na inicialização, âncoras no código do adaptador, inserem o bloco necessário e validam o arquivo via `py_compile`.

O padrão «plugin determinístico calcula — modelo especializado interpreta» está na base do [Nomad AI](https://nomadnet.ai) e do ambiente em nuvem [agent.nomadnet.ai](https://agent.nomadnet.ai). Laboratórios para montar esse tipo de agente estão disponíveis na [Hamidun Academy](https://academy.hamidun.com) (72 horas de teste grátis), e plugins prontos e mais de 370 habilidades são analisados no [Vibe Club](https://hamidun.com/club).