CH 09 · Subsistemas Centrais e o Fluxo de Uma Mensagem
Objetivo do Capítulo
O CH 08 explicou que o dsh é "uma árvore de plugins"; este capítulo aproxima o zoom: o que cada plugin-chave (subsistema) na árvore trata, como eles se coordenam, depois acompanha uma mensagem por inteiro — desde quando você pressiona Enter até quando ele responde, o que acontece no meio. Quando você vir essas duas coisas, vai saber como o dsh funciona internamente.
Subsistemas Centrais: A Equipe da Cozinha dos Fundos de um Restaurante
Continuando o restaurante pequeno do CH 08: a cozinha não é uma pessoa só, mas uma equipe com divisões claras de trabalho, cada um tratando sua parte, passando as coisas entre si. Os subsistemas centrais do dsh são essa equipe:
| Subsistema | Equivalente na equipe | O que ele trata |
|---|---|---|
agent-loop | Chef principal | O driver padrão: decide "o que fazer a seguir" — requisitar o modelo, chamar ferramentas, coletar resultados; todo o loop é dirigido por ele |
llm | Operador da linha de delivery | Conecta a modelos externos via adaptadores, envia mensagens, recebe respostas |
tools | Armário de ferramentas + porteiro | Registro de ferramentas + pipeline de execução controlada; cada agent usa o seu (isolamento de escopo) |
system-prompt | Bandeja de preparo | Costura os fragmentos de prompt e schemas de ferramentas registrados por vários plugins em "o que este prato mostra para o modelo" |
session | Livro-razão | Log de sessão append-only: o que você enviou, o que o modelo respondeu, quais ferramentas rodaram — tudo registrado |
scope | Isolamento de estação | Faz o registro de cada agent ter efeito apenas em sua própria célula, sem cruzamentos |
Como eles se coordenam, veja este diagrama:
Uma mnemônica: o chef principal (agent-loop) dá ordens, a bandeja (system-prompt) prepara, o operador da linha (llm) pede o delivery, o armário de ferramentas (tools) entrega ferramentas, e todos os resultados são registrados no livro-razão (session). O livro-razão é o destaque do próximo capítulo.
Uma Unidade-Chave: step e turn
Antes de olhar o fluxo, primeiro distinga dois termos; eles são a fundação para entender toda a cadeia:
- step = uma requisição ao modelo + as ferramentas que ela chama. O modelo "pensa + age" uma vez é uma step.
- turn = zero ou mais steps. Desde pegar sua primeira entrada até não haver mais trabalho devido.
Por que uma resposta pode ter várias steps? Porque o modelo frequentemente faz "pensa um pouco → chama uma ferramenta → vê o resultado e pensa de novo → chama outra..." até sentir que é suficiente, então dá a resposta final. Essa cadeia inteira é um turn, e cada "pensa + age" dentro dela é uma step. As palavras oficiais: um turn abre antes de pegar a primeira entrada, e fecha quando não há trabalho devido.
Uma analogia da vida real: você pede uma refeição (turn), o garçom pode ir e voltar várias vezes (step) — primeiro confirma se o prato está disponível, então serve, depois pergunta se você quer mais — até o pedido estar totalmente pronto.
O Fluxo de Uma Mensagem: Do Seu Enter até a Resposta
Agora acompanhe uma mensagem por inteiro. Siga este diagrama de cima para baixo:
① turn/start: o turn abre. Antes de você pressionar Enter, este turn não começou; depois que você pressiona, o turn primeiro abre, entrando em "pegar entrada".
② Pegar entrada (inbox). Todas as entradas vão primeiro para uma caixa de correio chamada inbox. A mensagem que você enviou vai acordar imediatamente o chef principal para começar a trabalhar; enquanto "contexto injetado" (o tipo que você viu no CH 04) fica na caixa de correio primeiro, esperando outra mensagem real para acordá-lo — então "injetar dados" por si só não vai interromper o fluxo.
③ Montar: prompt + schema de ferramenta. O system-prompt costura os fragmentos registrados por vários plugins em um prato, dizendo ao modelo "quem você é, quais ferramentas estão disponíveis, como as ferramentas se parecem".
④ agent/pre-step: decidir o que o modelo vê. Este é o primeiro "ponto de extensão ao vivo" — plugins podem reescrever o conteúdo a ser enviado aqui, ou diretamente rejeitá-lo. Se rejeitado ou reescrito para vazio, o turn ainda fecha e registra como de costume; o log mostra "tentou uma vez mas não rodou".
⑤ step/start: razão + pegar histórico. A mensagem que você enviou é escrita no log de sessão como user/message; ao mesmo tempo, o histórico do modelo para este turn é projetado a partir do log (deriveMessages()). Tudo que o modelo vê vem do log — esta é uma linha que vamos voltar repetidamente.
⑥ Requisitar o modelo → receber a resposta. agent/request envia a requisição (interceptável), llm/stream faz streaming de volta, e a resposta do modelo é escrita no log como assistant/message.
⑦ Precisa chamar uma ferramenta? Se o modelo decide "preciso agir", é tool/call → executar → resultado tool/result escrito de volta no log. Há pontos de interceptação antes e depois da execução (pre/post-execute). Se nenhuma ferramenta for necessária, pule para a próxima step.
⑧ step/end: mais trabalho? Se o resultado da ferramenta precisa que o modelo processe de novo (ou nova entrada chega), abra outra step, volte para "pegar entrada"; até não haver trabalho devido, vá agent/turn-stopping → turn/end, este turn termina, e você vê a resposta final.
Uma distinção-chave para manter em mente: o lado direito do diagrama marca dois tipos de eventos —
- Eventos persistentes (
turn/*,step/*,user/message,assistant/*,tool/*): escritos no log de sessão, ainda lá após reinicialização; - Pontos de extensão ao vivo (
agent/pre-step,agent/request,llm/stream,tools/*): efetivos apenas enquanto rodando; plugins os usam para interceptar e mudar comportamento, mas eles não pousam no razão por si só.
Isso ecoa o "eventos são pontos de extensão" do CH 08: para observar ou interceptar trabalho em execução, observe eventos ao vivo; para manter fatos, use eventos persistentes.
De Onde Vem a Memória do Modelo
Uma frase: o log de sessão é o contexto que o modelo vê. O que o modelo "lembra" neste turn não é algo que ele mesmo lembra; é o histórico que o sistema projeta a partir do log — então "o que o modelo vê é o que é registrado" é uma regra rígida no dsh: qualquer coisa que chegue a uma requisição de modelo deve ser reconstruível a partir do log, e o runtime verifica isso com um invariante. Essa regra é o eixo de todo o design; vamos abordá-la no CH 10.
Uma referência cruzada rápida com anteriores: a "visão de Trajectory" que você viu no CH 04 — aquela linha de timeline ASSISTANT / TOOL — por baixo dos panos é apenas uma visualização deste log de sessão. O que o modelo disse, quais ferramentas ele chamou, quais foram os resultados — tudo renderizado a partir do log. Então quando você pergunta "por que ele lembra o que eu disse antes", a resposta é simples: não é o modelo que lembra, é o log que lembra — toda vez antes de uma consulta, o sistema projeta o histórico a partir do log e alimenta o modelo.
O que você aprendeu neste capítulo
- [ ] Afirmar as divisões de trabalho dos subsistemas centrais (agent-loop / llm / tools / system-prompt / session), e explicar como eles se coordenam
- [ ] Explicar a diferença entre step e turn (step = uma requisição de modelo + ferramentas; turn = zero ou mais steps)
- [ ] Percorrer o fluxo completo de uma mensagem ao longo do diagrama: turn/start → pegar entrada → montar → pre-step → step/start → requisitar modelo → chamada de ferramenta → step/end → turn/end
- [ ] Distinguir eventos persistentes de pontos de extensão ao vivo, e afirmar o propósito de cada um (deixar evidência vs interceptar)
- [ ] Afirmar o significado da regra "o que o modelo vê é o que é registrado"