Deep Agents

Olá, daqui fala o Alex da DEV STORIES DOT EU. Deep Agents, episódio 1 de 16. Criar um coding agent de raiz é divertido durante cerca de uma hora. Depois, o teu modelo atinge o context limit, esquece completamente a task original e sobrescreve um ficheiro crítico com lixo. Para impedir que o teu assistente destrua o seu próprio workspace, precisas do que é conhecido como o agent harness pattern. As pessoas costumam encontrar este pattern através de uma library chamada Deep Agents. Primeiro, um rápido esclarecimento. O Deep Agents não é o LangChain, nem é o LangGraph. É uma library Python standalone que assenta em cima dessas tools, empacotando-as num coding assistant pronto a usar. Se tentares criar um coding assistant tu mesmo, normalmente começas com um script básico. Pegas num user prompt, envias para um large language model e fazes print do código que ele devolve. Isso é apenas um chat loop simples. Funciona bem para responder a uma única pergunta. Mas rapidamente vais querer que o modelo implemente realmente uma feature em vários ficheiros na tua máquina. É aqui que a ilusão se desfaz. Percebes que tens de escrever tools manualmente para ler ficheiros, pesquisar diretorias e aplicar code diffs com segurança. Precisas de um sistema para fazer track do context ao longo de dezenas de steps sem esgotar o token limit. Tens de construir uma task list persistente para que o modelo se lembre realmente do que acabou de fazer e do que precisa de fazer a seguir. Acabas por passar todo o teu tempo a escrever boilerplate de file system e state management, em vez de te focares no comportamento do agent. É exatamente isto que o agent harness pattern resolve. Um harness é a camada de infraestrutura que envolve o raw language model. Transforma um chat loop frágil e stateless num agent durável e long-running. No Deep Agents, este harness fornece o memory management, as operações de file system e a lógica de planeamento step-by-step, tudo out of the box. Dás-lhe um high-level goal e apontas para uma diretoria local. O harness assume o trabalho repetitivo de dar ao modelo um ambiente seguro para planear, editar e verificar código. Aqui está o ponto-chave. A principal vantagem de usar um harness independente como o Deep Agents é que ele é completamente model-agnostic. Soluções tightly integrated, como o Claude Agent SDK ou ecossistemas mais antigos como o OpenAI Codex, são altamente otimizadas, mas prendem-te a um único provider. Se amanhã for lançado um modelo mais barato ou mais inteligente, migrar o teu agent tightly coupled é uma enorme dor de cabeça. Como o Deep Agents abstrai o ambiente do reasoning engine, o language model torna-se um componente totalmente substituível. O harness gere as task lists, lê o file system e trata do error recovery. Esta lógica permanece idêntica, quer uses a Anthropic, a OpenAI ou um modelo open-weight local. O harness é o chassi do carro, e o language model é apenas o motor. O verdadeiro valor deste pattern é a fiabilidade. Um agent é apenas tão capaz quanto o ambiente em que opera, e sem um harness para o ancorar a um file system real e a um plano concreto, mesmo o modelo mais inteligente é apenas um text generator a patinar. Se quiseres ajudar a manter o programa no ar, podes procurar por DevStoriesEU no Patreon, qualquer apoio por lá faz uma grande diferença e é sempre apreciado. Por agora é tudo. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui fala o Alex do DEV STORIES DOT EU. Deep Agents, episódio 2 de 16. Não precisas de um diagrama de arquitetura enorme ou de centenas de linhas de boilerplate para que um language model planeie o seu trabalho de forma autónoma. Basta uma única function call para acionar o Core Loop. O ponto de entrada para este comportamento é uma função chamada create deep agent. É nesta função que defines o cérebro da tua aplicação. Em vez de importares client libraries separadas e escreveres wrappers personalizados, dizes à função qual modelo usar através de uma simples string separada por dois pontos. Passas o provider, dois pontos, e o nome exato do modelo. Podes usar anthropic dois pontos claude-sonnet-4-6, ou openai dois pontos gpt-5.4. A framework lê esta string e trata da inicialização específica nos bastidores. Um agente precisa de uma forma de interagir com o mundo, que tu forneces através de tools. Uma tool é simplesmente uma função Python standard que executa uma ação específica. Imagina que estás a construir um agente de pesquisa na internet. Escreverias uma função que recebe uma query, chama uma search API, e devolve texto. Passas esta função de pesquisa diretamente para a tua chamada do create deep agent como parte de uma lista. O teu agente está agora pronto. Para iniciar o processo, chamas o método run do teu novo agente e passas-lhe um prompt, como pedir-lhe para pesquisar e sintetizar notícias recentes sobre computação quântica. Agora o Core Loop assume o controlo. Aqui está o ponto chave. Os developers assumem frequentemente que têm de escrever system prompts complexos para forçar o modelo a dividir as tarefas, ou construir parsers personalizados para acompanhar o seu progresso. Não tens de fazer nada disso. Quando chamas o create deep agent, o harness injeta automaticamente uma tool integrada chamada write todos. Tu nunca escreves ou geres esta tool. Ela faz parte do core engine. Antes sequer de o agente tocar na tua search tool, o Core Loop força o modelo a usar a tool write todos. O agente avalia o teu prompt e gera uma lista estruturada de passos. Só depois de este plano estar finalizado é que a fase de execução começa. O loop itera sobre o plano passo a passo. O agente olha para a sua primeira tarefa, reconhece que precisa de informação, e chama a tua tool de pesquisa na internet. Ele lê o raw text devolvido pelo motor de busca e atualiza a sua memória interna. O loop depois verifica se o objetivo principal foi atingido. Se os resultados da pesquisa estiverem incompletos, o agente avança para o próximo item da sua todo list, talvez formulando uma nova search query para encontrar os detalhes em falta. Este ciclo de selecionar uma tool, observar o resultado e verificar o plano continua de forma autónoma. Quando o loop confirma que todas as tarefas necessárias estão concluídas, para de chamar tools. O agente analisa os dados recolhidos, gera uma resposta sintetizada final e devolve-ta. A característica que define o Core Loop é que transforma um gerador de texto estático num problem solver ativo, forçando-o estruturalmente a planear antes de agir. É tudo por este episódio. Obrigado por ouvires, e continua a construir!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 3 de 16. Dar a um agente autónomo acesso raw ao teu computador é uma excelente maneira de apagares acidentalmente a tua home directory. Se um agente decidir reorganizar os teus ficheiros ou testar um script, tens de garantir que ele fica confinado a uma área segura. É por isso que usamos o The Pluggable Filesystem. Quando dás a um Deep Agent tools para ler ou editar um ficheiro, essas tools não se ligam diretamente ao teu sistema operativo. Em vez disso, elas mapeiam para um backend. Um backend é um ambiente de storage que dita onde e como os ficheiros realmente vivem. O ambiente default é o StateBackend. Isto é uma drive fantasma efémera mantida inteiramente em memória. Supõe que pedes a um agente para escrever um rascunho rápido de um email ou manipular alguns dados de texto. O agente cria o ficheiro, volta a lê-lo e edita-o, tudo dentro do StateBackend. Quando o teu script termina de correr, essa memória é limpa e os ficheiros desaparecem. É completamente isolado e perfeitamente seguro. Mas o que acontece quando queres que o agente gere um projeto Python real no teu disco local? A memória já não é suficiente. Fazes upgrade às permissões do agente anexando um FilesystemBackend. Isto liga as tools de ficheiros do agente ao teu disco rígido real. Para manter a segurança, inicializas o backend com um parâmetro chamado virtual mode definido como true. Aqui está o ponto chave. O virtual mode cria um limite de path estrito. Defines uma diretoria base, e o agente opera lá dentro. Se o agente tentar ler um ficheiro de sistema sensível fora dessa pasta, o backend bloqueia o request. Isto prende o agente num workspace designado. No entanto, há aqui um equívoco perigoso. Muitos developers assumem que ativar o virtual mode cria uma sandbox completamente segura. Não cria. O FilesystemBackend controla apenas as operações de ficheiros. Se também quiseres que o teu agente corra comandos de terminal, tens de anexar um terceiro tipo de backend chamado LocalShellBackend. O LocalShellBackend dá ao agente uma nova tool chamada execute. Isto permite que o agente corra comandos de shell na tua máquina host. Se anexares um LocalShellBackend, o virtual mode do teu FilesystemBackend não te vai proteger de comandos de terminal destrutivos. O agente poderia executar um script de eliminação system-wide, e a shell iria corrê-lo, fazendo bypass completo às tuas restrições de file path. O acesso a ficheiros e a execução de shell são capacidades distintas mapeadas para backends distintos. Se o teu agente só precisa de escrever código, fica-te pelo FilesystemBackend. Anexa o LocalShellBackend apenas se o agente tiver absolutamente de compilar ou correr esse código localmente. O agente autónomo mais seguro não é aquele com os prompts mais inteligentes, mas sim aquele que é deployed com um StateBackend efémero que fisicamente não consegue tocar no teu sistema operativo host. É tudo por hoje. Obrigado por ouvires — vai construir algo fixe.

Olá, daqui fala o Alex da DEV STORIES DOT EU. Deep Agents, episódio 4 de 16. O erro mais comum no design de agentes é escrever um system prompt enorme, com quatro mil palavras, a detalhar exatamente como cada tool funciona e a fazer hardcoding de dados específicos da sessão. Acabas com um prompt frágil, context windows esgotadas e um pesadelo ao lidar com múltiplos utilizadores. Os Dynamic System Prompts resolvem isto ao montar as instruções exatas de que o language model precisa on the fly. Pensa no context engineering no Deep Agents como uma linha de montagem dinâmica. Em vez de escreveres um bloco de texto estático, o prompt final enviado ao language model é construído a partir de três camadas distintas. Estas camadas são o system prompt estático, os tool prompts e o runtime context. Elas unem-se no momento exato da execução para formar o input context completo. A primeira camada é o system prompt estático. Esta é a parte que escreves manualmente. É ela que define a persona do agente, as suas regras principais e o seu objetivo final. É propositadamente simples. Podes dizer ao agente que ele é um assistente de queries à base de dados, mas não lhe dizes como se ligar à base de dados, que formatação a tool espera, ou qual é o session ID do utilizador. Manténs esta camada estritamente focada na business logic de alto nível. A segunda camada consiste nos tool prompts, e é aqui que a framework entra em ação. O Deep Agents injeta automaticamente as instruções de uso necessárias para as tools específicas que associas ao agente. Se deres ao agente uma tool para ler um ficheiro, a framework anexa dinamicamente o schema exato para essa tool. Juntamente com os schemas, ela injeta um planning prompt integrado. Este planning prompt instrui o modelo sobre como sequenciar as tools disponíveis de forma eficaz para resolver um problema. Nunca escreves manualmente as instruções sobre como o modelo deve formatar uma tool call ou planear as suas etapas de execução. A framework lida com essas mecânicas automaticamente. Quando adicionas ou removes uma tool do agente, os tool prompts subjacentes são atualizados instantaneamente, sem que tenhas de tocar no system prompt principal. Agora, precisamos de esclarecer uma fonte comum de confusão entre o system prompt estático e o runtime context. O prompt estático é definido quando inicializas o agente. O runtime context, no entanto, é injetado exatamente quando invocas o agente para trabalhar. Considera um cenário em que estás a construir uma aplicação multi-tenant. Quando um utilizador específico faz uma pergunta, o agente precisa do connection ID único da base de dados desse utilizador para ir buscar os seus dados. Se colocasses esse identificador no system prompt estático, terias de recriar todo o agente do zero para cada pedido do utilizador. Em vez disso, usas o runtime context. Aqui está o ponto chave. Passas um context object através de uma feature chamada ToolRuntime logo no passo de invocação. Entregas à framework um dictionary que contém o connection ID da base de dados específico para essa sessão. A framework pega neste runtime context, faz o merge dele com o teu prompt estático e com as instruções das tools geradas automaticamente, e liga-o diretamente às tools que precisam dele. A tool é executada utilizando o connection ID correto, fornecido dinamicamente. O teu system prompt estático permanece completamente limpo de identificadores temporários, API keys ou session tokens. No milissegundo da execução, a linha de montagem dinâmica termina o seu trabalho. O Deep Agents concatena as tuas instruções principais, os tool schemas gerados dinamicamente, os planning prompts e os dados de invocação específicos num input context coeso. O modelo recebe um conjunto de instruções completo e perfeitamente formatado, adaptado a esse utilizador específico e a essa tarefa específica. Os agentes mais escaláveis não sabem nada sobre o seu ambiente até ao momento exato em que lhes é pedido para agir. É tudo por este episódio. Até à próxima!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 5 de 16. A maioria dos agentes de IA crasha ou falha silenciosamente no momento em que lê um system log ou um data dump que excede o tamanho máximo do seu prompt. O Deep Agents evita isto tratando os limites de contexto da mesma forma que um sistema operativo lida com a memória virtual. A isto chama-se Context Compression and Offloading. Os large language models têm um limite rígido na quantidade de texto que conseguem processar de uma só vez. Se um agente tentar manter demasiados dados no seu prompt ativo, o modelo dá um erro e para. O Deep Agents gere este token overflow monitorizando constantemente o tamanho dos dados da conversa. Funciona exatamente como um computador a fazer paging da RAM para um disco rígido quando a memória fica cheia. O espaço de trabalho ativo é mantido leve, enquanto o grosso dos dados é movido em segurança para fora do caminho. Este mecanismo opera em duas fases distintas. A primeira fase lida com picos de dados imediatos e massivos provenientes de tools externas. A framework monitoriza o token count de cada tool input e tool result. O limite rígido para esta verificação é de vinte mil tokens. Se uma operação exceder este limite, o sistema interceta o payload antes sequer de chegar ao language model. Imagina um agente a executar uma query que extrai um database dump massivo de trinta mil tokens. Um agente normal tenta inserir todo esse payload diretamente no histórico da conversa, o que dispara imediatamente um token overflow. O Deep Agents segue um caminho diferente. Ele interceta essa resposta massiva, faz offload do texto completo para um novo ficheiro no filesystem do backend, e substitui o payload na conversa por uma simples preview de dez linhas. O agente lê a preview e recebe um file path a apontar para os dados completos. O agente sabe exatamente o que encontrou, mas o prompt ativo permanece completamente limpo. Isto trata dos picos repentinos de dados. A segunda fase lida com a acumulação lenta de uma conversa normal. À medida que um agente corre um processo longo e de várias etapas, o histórico contínuo de idas e vindas consome lentamente os tokens disponíveis. O Deep Agents monitoriza o uso total da context window em relação aos limites do modelo. Quando o prompt ativo atinge oitenta e cinco por cento do total disponível da context window, um processo de sumarização em background é disparado automaticamente. O sistema pega no bloco de mensagens mais antigo do histórico atual e usa um language model para gerar um resumo denso e factual desses eventos. A seguir, substitui esse bloco de mensagens mais antigo no prompt ativo pelo resumo recém-gerado, reduzindo instantaneamente o token count de volta para um nível de operação seguro. Aqui está o ponto chave. Os developers costumam assumir que resumir a conversa destrói permanentemente o histórico original. Isso não é verdade. Antes de qualquer sumarização acontecer, as mensagens originais são gravadas no filesystem como um registo canónico permanente. Os raw data não se perdem. Se o agente determinar mais tarde que precisa de um detalhe altamente específico de uma etapa anterior que não entrou no resumo, pode usar as suas search tools para fazer uma query a esse filesystem e recuperar o texto original exato. Ao combinar offloads imediatos para o filesystem de tool results massivos com a sumarização dinâmica para históricos longos, um agente pode operar indefinidamente sem sufocar no seu próprio contexto. Obrigado por ouvirem, happy coding a todos!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 6 de 16. Se o teu agent principal de IA estiver a ler dez páginas web para responder a uma única pergunta, ele vai acabar por se esquecer de qual era o prompt original. Todo esse ruído intermédio acaba por abafar as instruções. A solução para isto é o Isolamento de Contexto com subagents síncronos. Pensa nisto como um padrão de clean architecture para os teus modelos de linguagem. Quando um único agent tem acesso a dezenas de tools e corre em longos loops iterativos, a sua context window enche-se rapidamente com dados brutos, mensagens de erro e outputs das tools. Este inchaço de contexto degrada a capacidade de raciocínio do modelo. Em vez de um agent enorme a tentar fazer tudo, precisas de um supervisor. O agent principal atua como um manager. Ele delega o trabalho confuso e pesado em tokens a especialistas e recebe apenas um relatório final limpo e formatado. As pessoas costumam confundir subagents com uma sala de chat multi-agent contínua, onde diferentes modelos ficam a debater ideias uns com os outros. Não é esse o caso aqui. Os subagents síncronos são estritamente efémeros. Eles são criados para executar um job específico, correm de forma completamente autónoma no seu próprio espaço de memória isolado até que o job esteja concluído, e retornam um único resultado final ao supervisor. Assim que entregam esse resultado, desaparecem. Considera um cenário específico. O teu agent principal tem a tarefa de escrever um market briefing, e precisa de dados sobre tendências económicas recentes. Em vez de o supervisor invocar diretamente uma tool de web search cinco vezes e poluir a sua própria context window com texto bruto de sites, ele delega o problema. Ele aciona um subagent researcher. Este researcher efémero entra no seu próprio loop isolado. Ele faz as cinco pesquisas no Google, lê os resultados confusos, sintetiza as descobertas e escreve um único parágrafo de resumo. Ele passa apenas esse parágrafo de volta ao supervisor. O supervisor obtém exatamente o que precisa, e o seu contexto permanece intacto. Para configurar isto, defines os teus especialistas usando dicionários simples. Passas isto para o parâmetro subagents ao construíres o teu agent principal. Cada dicionário é uma especificação de subagent que requer quatro informações. Primeiro, dás um nome, como researcher ou calculator. Segundo, dás uma descrição. Esta é a parte que importa. O supervisor lê esta descrição para decidir qual especialista contratar para um determinado problema. Terceiro, forneces as tools, dando a este subagent específico acesso isolado a coisas como um web scraper ou um database client. Finalmente, forneces um system prompt, que governa como o subagent se comporta. Assim que entregas esta lista de configurações ao agent principal, ele ganha automaticamente acesso a uma tool built-in chamada task. O supervisor não precisa de saber como instanciar os subagents. Quando encontra um problema que corresponde à descrição de um especialista, ele simplesmente chama a tool task. Ele passa dois argumentos: o nome do subagent a usar, e uma instrução em plain text do que precisa de ser feito. A execução do supervisor faz uma pausa. O subagent arranca, trabalha com as suas tools e acaba por terminar. Para o supervisor, a tool task simplesmente devolve a resposta final em texto como se fosse uma function call standard. Mesmo que não definas explicitamente nenhum dicionário, a framework dá-te um fallback. Há um subagent default de propósito geral built-in. O agent principal pode usar este especialista default para descarregar passos de raciocínio complexos. Ele atua como uma tela em branco, dando ao modelo uma context window limpa para resolver um puzzle lógico denso sem sujar a memória do supervisor. Aqui está o ponto-chave. Ao impor limites rígidos entre tasks isoladas, impedes que o trabalho intermédio de scratchpad degrade a qualidade de raciocínio do flow principal da tua aplicação. É tudo por este. Obrigado por ouvires, e continua a construir!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 7 de 16. Deixar um sistema autónomo correr SQL queries às cegas é uma excelente forma de fazeres drop acidentalmente a uma database de produção. Se queres que o teu agent opere no mundo real, precisas de um mecanismo para o intercetar antes que ele faça algo destrutivo. É aí que entram as intervenções Human-in-the-Loop. A ideia central é simples. Pausas o agent mesmo antes de ele executar uma operação sensível, pedes instruções a um humano e, de seguida, retomas a execução com base nesse feedback. Antes de olharmos para a mecânica, há uma armadilha comum a evitar. O LangGraph precisa de memory para pausar e retomar o state. Se tentares configurar uma intervenção Human-in-the-Loop sem configurares um checkpointer, a intervenção vai falhar. O sistema precisa de uma persistence layer, como um memory saver, para congelar o execution graph e guardar as variáveis atuais enquanto espera que um humano responda. Adiciona sempre um checkpointer primeiro. Nem todas as tools precisam de revisão humana. Verificar a meteorologia ou ler um log file é geralmente seguro. Apagar ficheiros ou alterar registos na database exige um controlo rigoroso. Geres esta categorização de risco usando o configuration parameter interrupt on. Quando inicializas o teu agent ou defines o teu tool node, passas uma lista de tool names para este parâmetro. Se o agent tentar fazer uma tool call que não está na lista, ela corre imediatamente. Se tentar chamar uma tool que está na lista, a execução pausa. Vamos ver um cenário concreto. Tens um agent com uma database tool chamada execute. Adicionas o execute à tua lista do interrupt on. O agent decide que precisa de limpar alguns dados antigos e tenta correr um comando drop na database. O sistema interceta a call e pausa o execution graph. Quando corres o teu agent, monitorizas o result object devolvido pela framework. Especificamente, verificas uma property chamada interrupts. Se a lista interrupts do result contiver dados, o agent bateu numa safety gate e está à espera do teu input. Neste ponto, o operador humano avalia a ação pendente. Tens três decisões permitidas que podes passar de volta ao agent. Estas são approve, reject ou edit. Se fizeres approve, o agent executa a tool com os arguments originais. Se fizeres reject, a tool call falha de forma controlada, e o agent recebe uma error message com um prompt para tentar uma abordagem diferente. É aqui que a coisa fica interessante. A decisão edit permite-te modificar a ação pretendida pelo agent antes que ela aconteça. No nosso cenário de database, o agent está a tentar um comando drop perigoso. Podes intercetar esse request, reescrever os tool arguments para correr uma select query segura em vez disso, e enviar esse payload modificado de volta para o sistema. Para tirar o agent de pause, invocas-o novamente, mas desta vez passas um command object usando o parâmetro resume. Dentro desse parâmetro resume, forneces a tua decision string juntamente com quaisquer arguments modificados. O checkpointer recupera o frozen state, injeta a tua decisão humana diretamente no graph como se o agent a tivesse planeado originalmente dessa forma, e a execução continua. A coisa mais importante a lembrar é que as intervenções Human-in-the-Loop dão-te mais do que apenas um botão de paragem de emergência. A capacidade de editar tool arguments a meio do processo permite-te guiar um agent em segurança por workflows complexos sem começares do zero. Se quiseres apoiar o programa, procura por DevStoriesEU no Patreon. Por este episódio é tudo. Obrigado por ouvires, e continua a programar!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 8 de 16. Podes olhar para um agente a ler um ficheiro local e presumir que essa capacidade está hardcoded bem fundo no core execution loop. Não está. A magia por trás do file system de um agente é totalmente alimentada por middleware composable que tu próprio podes estender. Hoje, vamos falar sobre como estender o harness com middleware. O Deep Agents não é uma black box. O harness que controla o execution pipeline é altamente extensível. Quando equipas um agente com um file system ou uma todo list, estás simplesmente a ligar middleware pre-packaged a esse harness. O middleware fica exatamente na fronteira entre a decisão do agente de invocar uma tool e a execução real dessa tool. É um interceptor. Dá-te controlo absoluto sobre o que entra, o que sai e o que é registado durante a troca. Para escreveres o teu próprio custom middleware, crias uma função interceptora e aplicas um decorator específico chamado wrap tool call. Este decorator regista a tua função no harness. Quando o agente aciona uma tool, o harness faz uma pausa no fluxo default e passa o controlo para a tua wrapped function. Dentro deste interceptor, recebes os raw input arguments gerados pelo agente, uma referência à tool que está a ser chamada e o graph state atual. Executas a tool original manualmente a partir da tua função, capturas o seu output e, de seguida, devolves esse output ao harness. Considera um custom middleware criado para monitorizar uma API externa. Queres intercetar cada tool call da API, fazer log dos argumentos exatos que o agente usou e monitorizar as métricas de uso para evitar rate limits. A tua função wrap tool call captura o request antes de chegar à rede. Extrai o payload, escreve-o nos logs da tua aplicação e, de seguida, executa o request real à API. Assim que o request termina, o middleware recebe os dados da response. Agora, precisa de registar que foi feita uma call. Presta atenção a esta parte. Ao fazer track das métricas de uso, os developers costumam tentar usar standard class instance variables. Escrevem simplesmente algo como self dot api call count plus equals one. Isto é um erro fatal. O Deep Agents executa tools e subagents rotineiramente em paralelo. Se várias tools resolverem no mesmo momento e tentarem mutar a mesma instance property diretamente, vais causar race conditions. Os teus contadores vão sobrescrever-se uns aos outros, os updates serão descartados e as tuas métricas ficarão completamente erradas. Para gerir os dados com segurança, deves antes atualizar o graph state. O graph state foi explicitamente concebido para lidar com parallel execution. Em vez de modificar uma variável local, o teu middleware lê a métrica atual do graph state, calcula o novo valor e faz yield de um state object atualizado juntamente com o tool result. A partir daí, o execution harness assume o controlo. Ele processa todos os state updates recebidos das parallel tool executions e faz o merge de forma limpa, sem colisões. Ao encaminhar todos os side effects e o metric tracking através do graph state, o teu middleware permanece totalmente thread-safe. Compreender este padrão desbloqueia todo o framework. Deixas de tratar o agente como um sistema fechado e passas a vê-lo como um pipeline transparente, onde cada ação pode ser intercetada e medida com segurança. É tudo por agora. Até à próxima!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 9 de 16. Ter um assistente de código com IA é ótimo, até teres de o lembrar pela quinquagésima vez que o teu projeto exige strict typing e variáveis em snake case. A solução é usar Project Conventions através de ficheiros de memória. A ergonomia do developer exige que as tuas ferramentas se adaptem à tua codebase, e não o contrário. Não devias ter de colar um style guide em cada prompt. O Deep Agents resolve isto dando ao agente uma memória persistente através de um ficheiro específico chamado AGENTS dot md. Às vezes, as pessoas confundem memória com skills. A memória fornece a tua baseline universal. É sempre carregada no startup, o que a torna perfeita para convenções globais e regras de arquitetura. As skills são ferramentas funcionais que o agente carrega dinamicamente apenas quando uma task específica as exige. Hoje, vamos focar-nos estritamente na memória. Quando inicializas um agente e passas o parâmetro memory, a framework injeta automaticamente o conteúdo do ficheiro AGENTS dot md diretamente no context do agente antes de ele fazer qualquer trabalho. Esta operação baseia-se no protocolo memory-first, que dita três fases distintas para o agente: Research, Response e Learning. Na fase de Research, o agente lê o ficheiro de memória para entender o environment. Na fase de Response, ele gera o código ou responde ao prompt. Depois vem a fase de Learning. Aqui está o ponto-chave. Não tens de escrever manualmente o ficheiro AGENTS dot md. O agente atualiza este ficheiro de forma autónoma com base no teu feedback. Imagina um cenário concreto. Pedes ao agente para gerar um novo endpoint de API. Ele escreve código funcional, mas formata as variáveis em CamelCase. Rejeitas o pull request e respondes que este projeto usa estritamente snake case. O agente corrige o código, mas não se fica por aqui. Entra na fase de Learning, abre o ficheiro AGENTS dot md local, e adiciona uma nova regra a exigir snake case para todas as futuras variáveis. Da próxima vez que pedires um endpoint, o agente lê esse ficheiro de memória durante a sua fase de Research e escreve nativamente em snake case desde o início. Este sistema de memória persistente opera em dois scopes diferentes. O primeiro é o scope global. Este ficheiro vive na tua home directory de utilizador, dentro de uma pasta dot deepagents. Usas isto para as tuas preferências pessoais de developer. Se preferes sempre Python assíncrono em vez de código síncrono em todos os teus projetos, o agente aprende isso aqui. O segundo é o scope do projeto. Este ficheiro vive diretamente dentro da pasta do teu repositório local. É aqui que entram as regras específicas do repositório. Quando um agente corre, carrega ambos os ficheiros. Aplica as tuas preferências globais primeiro, e depois sobrepõe as convenções específicas do projeto. Como o ficheiro de memória de scope de projeto vive no teu repositório, fazes commit dele para o version control. Quando um novo developer se junta à equipa e corre o agente, a sua instância local herda instantaneamente todas as decisões de estilo que o agente já aprendeu. Cada erro corrigido melhora permanentemente a compreensão do agente sobre o teu repositório, passando-o de um gerador de código genérico para um maintainer altamente contextualizado. É tudo por este episódio. Até à próxima!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 10 de 16. Se despejares cinquenta guias de documentação de API diferentes no teu system prompt, o teu agente não vai ficar mais inteligente. Ele apenas se vai distrair e falhar em tarefas básicas. Precisas de uma forma de dar ao agente conhecimento profundo sem rebentar com a context window. O Progressive Disclosure com skills resolve exatamente este problema. Uma skill no Deep Agents funciona como um upgrade modular ao cérebro. Permite-te empacotar lógica complexa, como regras de deploy na AWS ou workflows personalizados de data science, num diretório isolado. Para construíres uma, basta criares uma nova pasta, dar-lhe o nome da tua skill, e colocar lá dentro um ficheiro chamado exatamente skill ponto md. Um equívoco comum é achar que a framework simplesmente anexa todo o conteúdo deste ficheiro ao system prompt. Não é isso que acontece. Fazer isso colocar-nos-ia de volta no problema da context window sobrecarregada, degradando a performance e aumentando os custos. Em vez disso, a framework baseia-se num padrão chamado progressive disclosure, que acontece em três passos: Match, Read e Execute. Logo no topo do teu ficheiro skill ponto md, escreves um bloco de frontmatter. Este é formatado como YAML básico e contém apenas um nome e uma breve descrição. Aqui está o ponto chave. A framework carrega apenas essa breve descrição no system prompt inicial. O agente lê a descrição e decide se corresponde ao request atual do utilizador. Esta é a fase de Match. Se o agente decidir que a skill é relevante, não tenta adivinhar o que fazer a seguir. Usa ativamente uma tool interna para ir buscar o resto do ficheiro skill ponto md. Esta é a fase de Read. Agora, o agente tem as instruções completas e detalhadas carregadas temporariamente na sua memória de trabalho para este turno específico. Finalmente, passa para a fase de Execute, onde segue essas instruções detalhadas para concluir a tarefa. Quando a conversa avança para um tópico diferente, o payload pesado é descartado, e o agente volta ao seu estado de base. Considera um cenário em que queres construir uma skill chamada langgraph-docs. O frontmatter do teu skill ponto md tem uma descrição a indicar que esta skill fornece instruções e URLs internos para pesquisar a documentação do LangGraph. O corpo do ficheiro contém esses URLs internos e a metodologia de pesquisa específica. Quando um utilizador pergunta o que é o LangGraph, o agente verifica as suas skills ativas. Vê a breve descrição, percebe que precisa de mais informação para responder à pergunta, e pede o documento completo. Lê os URLs, faz a pesquisa e formula uma resposta precisa. Sem progressive disclosure, terias de colar todos esses URLs no prompt principal para cada conversa. Ao construíres uma biblioteca de skills, podes deparar-te com conflitos onde duas skills tentam definir instruções para tarefas semelhantes. O Deep Agents resolve isto usando source precedence. A regra é simples: a última ganha. A skill que for carregada em último lugar vai fazer override às instruções conflituosas das anteriores. Isto permite-te empilhar skills amplas e genéricas primeiro, e depois adicionar overrides altamente específicos mais tarde na tua configuração. A execução de todo o teu workflow de agentes depende do quão bem escreves esse frontmatter. Mantém as tuas descrições precisas e os corpos das tuas skills muito detalhados, porque o agente só vai ler o ficheiro completo se o convenceres primeiro com a descrição. É tudo por este episódio. Obrigado por ouvires, e continua a construir!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 11 de 16. Um assistente inteligente não te devia perguntar que base de dados usas sempre que começas uma nova conversa. No entanto, logo à partida, a maioria dos agentes sofre de amnésia total no momento em que uma thread termina. Para resolveres isto, precisas de Long-term Memory Stores. Quando corres um agente, ele gera ficheiros. Os ouvintes muitas vezes assumem que, se um agente escreve um ficheiro, ele vive para sempre. Mas não é assim. Por defeito, tudo é efémero. Os Deep Agents usam um StateBackend, que guarda os ficheiros dentro do state da thread de conversa atual. Quando essa thread conclui, esses ficheiros desaparecem. Se queres uma verdadeira personalização, onde o agente constrói uma base de dados vitalícia de preferências do utilizador e conhecimento do projeto, precisas de uma abordagem diferente. Precisas do StoreBackend. Este liga-se diretamente a uma LangGraph Store persistente, mantendo os dados seguros ao longo de múltiplas threads. Mas tu não queres persistir cada ficheiro temporário que o teu agente cria. Precisas de um mecanismo para separar o trabalho efémero de scratchpad das memórias duradouras. É aqui que entra o CompositeBackend. Pensa nele como um router de tráfego para o file system do teu agente. Configuras o CompositeBackend com um fallback por defeito, normalmente o StateBackend efémero. Depois, registas explicitamente uma rota para o teu storage de longo prazo. Dizes ao router que qualquer file path que comece com o prefixo de diretório barra memories barra deve ser tratado pelo StoreBackend. Presta atenção a esta parte. Esta persistência não é automática. Tens de fazer o routing específico do path barra memories barra para a Store. Se saltares este passo de routing, o agente vai simplesmente escrever os ficheiros de memória no state efémero, e eles serão apagados quando a thread terminar. Assim que introduzes uma base de dados persistente, enfrentas um novo problema. Não podes ter um utilizador a ler as preferências guardadas de outro utilizador. Para evitar isto, o StoreBackend usa namespace factories. Uma namespace factory é simplesmente uma função que injeta uma camada de isolamento com base no contexto atual. Em vez de guardar um ficheiro globalmente, a factory gera um array de prefixos, como a palavra users seguida pelo ID único do utilizador. Sempre que o agente interage com o StoreBackend, a base de dados faz automaticamente o scope da operação para esse namespace exato do utilizador. Vamos ver como isto flui na prática. Começas a conversa um. Mencionas que estás a construir uma aplicação React. O agente regista isto e escreve um resumo num ficheiro chamado project notes ponto txt, colocando-o especificamente dentro do diretório barra memories barra. O CompositeBackend vê esse prefixo de diretório, interceta o comando de escrita, e faz o routing para o StoreBackend duradouro sob o teu namespace de utilizador isolado. Amanhã, começas a conversa dois. Esta é uma thread completamente nova com zero contexto imediato. Fazes uma pergunta sobre frameworks de state management. Antes de responder, o agente verifica o seu diretório barra memories barra. O CompositeBackend faz o routing do pedido de leitura para a store persistente. O agente lê as tuas project notes, vê os detalhes de React, e fornece uma resposta altamente relevante adaptada à tua stack específica. O contexto transita perfeitamente, mesmo que as threads sejam separadas. A persistência cross-thread requer um design deliberado, fazendo o routing de diretórios específicos para uma store persistente e protegendo-os com namespaces específicos do utilizador. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.

Olá, daqui é o Alex do DEV STORIES DOT EU. Deep Agents, episódio 12 de 16. Deixar uma IA escrever código é impressionante. Deixar essa IA correr cegamente o código que acabou de escrever diretamente no teu portátil é uma péssima ideia. Para resolver isto, precisas de um ambiente seguro para o agente verificar a sua lógica sem colocar em risco a tua máquina host. É exatamente isso que vamos discutir hoje: Executar Código em Sandboxes. Se um agente não consegue executar código, não consegue verificar se o código realmente funciona. Depende puramente dos seus dados de treino para adivinhar se um script está correto. As sandboxes dão ao agente um ambiente seguro para iterar, falhar e corrigir erros com base no output real da execução. Antes de olharmos para a mecânica, precisamos de esclarecer uma ideia errada muito comum. Podes assumir que tem de ser feito o deploy do próprio agente para correr dentro da sandbox. Não é o caso. Os Deep Agents usam o pattern de Sandbox as tool. A lógica, a memória e os prompts do agente vivem em segurança no teu servidor. O agente simplesmente envia comandos de shell e código através de uma API para um ambiente remoto e isolado. Esta interação acontece através da execute tool. Quando o agente decide que precisa de correr um script, chama a execute tool e passa o bloco de código gerado. Esta tool reencaminha o payload para um backend de sandbox. Providers como a Modal, Daytona e Runloop fornecem estes ambientes. Eles provisionam um container seguro, correm o código e devolvem o standard output ou os error logs de volta ao agente. A sandbox cria uma fronteira de isolamento rigorosa entre o espaço de execução e o teu sistema. Imagina um agente encarregue de criar um pequeno package Python e correr uma test suite usando o pytest. O agente está no teu servidor. Usa a execute tool para chegar a um servidor remoto efémero. Primeiro, envia um comando para instalar as libraries necessárias. A seguir, escreve os ficheiros Python na diretoria da sandbox. Finalmente, envia um comando para correr o pytest. A sandbox executa estes passos e devolve o output do terminal. Se um teste falhar, o agente lê o erro da resposta da API, atualiza o código e chama a execute tool novamente. O agente pode fazer build, testar e limpar tudo, enquanto a tua máquina host permanece completamente intacta. Quando configuras um backend de sandbox, tens de definir o seu lifecycle. Existem duas abordagens principais. A primeira é thread-scoped. Aqui, a sandbox está ligada a uma thread de conversa específica. Quando a conversa começa, uma nova sandbox faz spin up. Quando a sessão do utilizador termina, a sandbox é destruída. Isto garante um ambiente limpo para cada interação e é ideal para operações single-task, onde os dados não precisam de persistir. A segunda abordagem é assistant-scoped. Neste modelo, a sandbox está ligada ao próprio agente, independentemente da conversa ativa. Cada thread que interage com esse agente partilha exatamente o mesmo state da sandbox. Se uma thread instala uma versão específica de uma library ou faz download de um grande dataset, esses ficheiros permanecem disponíveis para a próxima thread. Esta é a escolha certa quando o teu agente atua como um worker persistente que requer um workspace estável e contínuo. Aqui está o ponto-chave. O ambiente de execução dita a capacidade do agente. Ao controlar o lifecycle da sandbox e impor boundaries rígidas na API, dás ao agente a liberdade de cometer erros sem comprometer a tua infraestrutura. O verdadeiro poder de um agente não está apenas em gerar código, mas em iterar sobre a falha, e as sandboxes remotas oferecem a única maneira segura de permitir que essa iteração aconteça automaticamente. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 13 de 16. Disparas uma query complexa, o teu agent supervisor delega para três subagents em paralelo, e o teu utilizador fica a olhar para um loading spinner genérico durante dois minutos seguidos. Isso é uma user experience terrível e, para a corrigires, precisas de expor exatamente o que está a acontecer nos bastidores. A resposta é Subgraph Streaming UX. Workflows multi-agent são inerentemente assíncronos e lentos. Quando um agent principal delega tarefas, cria uma black box. Se simplesmente esperares pelo resultado final combinado, o utilizador assume que a aplicação bloqueou. Tens de fazer stream da atividade dos subagents diretamente para o frontend. Um erro comum que os developers cometem aqui é assumir que, quando os subagents fazem stream de tokens, esses tokens são simplesmente anexados às cegas à output stream do agent principal. Se isso fosse verdade, os outputs paralelos iriam intercalar-se numa confusão de texto. Em vez disso, a framework lida com isto isolando cada evento no seu próprio namespace. Para pores isto a funcionar, usas o formato de streaming versão dois e passas uma flag a definir subgraphs como true quando chamas a tua stream. Quando fazes isto, a stream já não devolve chunks de texto em bruto. Devolve dicionários. Cada dicionário contém três keys específicas: type, ns e data. Type diz-te para que tipo de evento estás a olhar. Data guarda o payload real ou o token de texto. E ns significa namespace. Esta é a parte que interessa. O namespace é um tuple que define o path exato do node que gerou o evento. Se um chunk vier do agent principal, o tuple do namespace está vazio. Se vier de um subagent, o namespace contém o path. Parece-se com um tuple que contém a palavra tools seguida por um ID único do subagent. Imagina que estás a construir um dashboard de frontend. Um utilizador pede ao sistema para planear umas férias. O agent supervisor cria três subagents separados: um para voos, um para hotéis e um para atividades. No teu código de frontend, fazes um loop sobre a stream que está a entrar. Ao verificares a key do namespace em cada chunk do dicionário, sabes exatamente qual subagent gerou esse token específico. Podes então fazer o routing desses dados para componentes de UI separados. Em vez de um único spinner bloqueado, o teu utilizador vê três loading bars ou janelas de texto individuais a encherem com outputs em tempo real, lado a lado. Às vezes precisas de fazer stream de informação que não é apenas um token de um language model. Talvez queiras fazer push de um status update customizado, como notificar a UI de que uma API externa está a ser chamada. Podes fazer isto a partir de dentro de um node usando a função get stream writer. Recuperas o writer, passas-lhe o teu dicionário customizado, e ele injeta esses dados diretamente na stream geral sob o namespace do subagent atual. O frontend recebe-o exatamente como qualquer outro evento e atualiza a loading bar específica correta. Se quiseres ajudar a manter o programa a andar, podes apoiar-nos procurando por DevStoriesEU no Patreon. A transparência multi-agent é fundamentalmente um problema de routing; mapear tuples de namespace para componentes de UI independentes é o que transforma uma black box frustrante numa user experience premium. É tudo por este episódio. Obrigado por ouvirem, e continuem a construir!

Olá, daqui fala o Alex da DEV STORIES DOT EU. Deep Agents, episódio 14 de 16. E se pudesses ligar o teu agente de terminal local à base de dados proprietária da tua empresa sem escreveres uma única linha de código Python? É exatamente por causa dessa capacidade que estamos a falar sobre a CLI do Deep Agents e as External MCP Tools. O SDK do Deep Agents fornece uma command line interface integrada, pronta a usar. Inicias o processo e ficas com uma prompt de terminal onde podes conversar com o teu agente. Podes gerir o core brain do agente diretamente a partir desta prompt. Se precisares de um reasoning engine mais capaz, basta escreveres barra model seguido do identificador do novo modelo. A CLI faz o hot-swap do provider instantaneamente, e tu continuas a tua sessão. Mas um agente de terminal que apenas conversa não é muito útil. Precisa de ter acesso ao teu trabalho real. Normalmente, dar acesso a um agente a um repositório do GitHub ou a uma base de dados local obriga a escrever código wrapper customizado em Python para lidar com as API calls. A CLI evita isto completamente ao usar o Model Context Protocol, amplamente conhecido como MCP. Muitas vezes há confusão sobre o que o MCP realmente é. Não é uma library de Python que importas para o código do teu agente. Um servidor MCP é um processo completamente separado ou um URL remoto. Atua como um wrapper standardizado à volta de um sistema externo. Quando a CLI arranca, comunica com este processo separado, pergunta que tools ele fornece, e carrega-as dinamicamente. Configuras esta ligação usando um simples ficheiro de texto chamado ponto mcp ponto json. Este ficheiro é o core das integrações zero-code. Quando inicias a CLI do Deep Agents, ela faz um auto-discovery. Procura no teu current directory por esta configuração json. Se encontrar uma, liga-se aos servidores lá listados, regista as suas tools, e entrega-as ao teu agente. Este ficheiro de configuração suporta dois mecanismos de transporte. O primeiro é standard input e output, ou stdio. Isto é para servidores locais. A CLI faz spawn do servidor como um processo em background na tua máquina e comunica com ele através de standard terminal streams. O segundo tipo de transporte baseia-se em HTTP e Server-Sent Events. Usas isto quando o teu servidor MCP está alojado remotamente, talvez dentro de uma rede corporativa privada. Como os servidores stdio correm comandos locais, a segurança é uma prioridade. A CLI mantém uma trust store local para servidores ao nível do projeto. A primeira vez que a CLI deteta um novo comando de servidor local no teu ficheiro ponto mcp ponto json, ela para e pede permissão explícita. Assim que aprovares, a hash desse comando é guardada na tua trust store, e futuras execuções ligam-se automaticamente. Vamos olhar para um cenário específico. Queres que o teu agente leia ficheiros do teu disco local. Crias um ficheiro ponto mcp ponto json. Lá dentro, defines um server block e dás-lhe o nome de local-filesystem. Defines o tipo de transporte como stdio. Para a command line, dizes-lhe para correr a tool do package manager do Node, o npx, apontando-o para um community server pré-construído chamado server-filesystem, juntamente com o caminho do diretório que queres expor. Guardas o ficheiro e lanças a CLI do Deep Agents. Aqui está o ponto chave. A CLI faz automaticamente o spawn desse comando npx em background. O filesystem server faz boot e faz broadcast de que tem tools para ler ficheiros e listar diretórios. A CLI apanha esse broadcast e equipa o teu agente. Podes escrever imediatamente no teu terminal, pedindo ao agente para ler o teu ficheiro de system log. O agente percebe que tem a tool, chama o processo em background, vai buscar os conteúdos do ficheiro, e responde à tua pergunta. Acabaste de dar a um sistema de IA acesso seguro ao teu disco local usando apenas algumas linhas de texto de configuração. Ao fazer o decoupling da lógica da tool da tua aplicação Python, o MCP transforma o teu terminal de uma interface de chat básica num centro de controlo extensível. É tudo por este episódio. Até à próxima!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 15 de 16. Porquê contentares-te com um assistente de código genérico quando podes injetar o teu próprio agente LangGraph altamente personalizado diretamente no teu editor de código? O protocolo que tira o teu agente personalizado do terminal e o integra no teu fluxo de trabalho diário é o Editor Integrations via ACP. Antes de avançarmos, precisamos de esclarecer uma colisão de siglas. Provavelmente já ouviste falar do MCP, ou Model Context Protocol. O MCP liga o teu agente a ferramentas externas, permitindo-lhe pesquisar numa base de dados ou ler um sistema de ficheiros. O ACP, Agent Client Protocol, é completamente diferente. O ACP liga o teu agente a IDEs externas, como o Zed ou o VSCode. Um liga o agente a dados externos, o outro liga o agente ao teu workspace. O ACP é uma camada de comunicação standardizada. Define exatamente como um Integrated Development Environment envia seleções de texto, estruturas de ficheiros e prompts do utilizador para um agente de IA. Também dita como esse agente devolve inserções de código, diffs de ficheiros e respostas de chat. Ao implementares este protocolo, o teu deep agent personalizado comporta-se exatamente como um assistente pronto a usar dentro do teu editor. A diferença é que ele possui todas as estruturas de memória específicas, templates de prompt personalizados e ferramentas internas especializadas que tu lhe construíste. Para colmatar esta falha, instalas o package deepagents-acp. A integração requer um script Python muito curto para atuar como entry point. Neste script, instancias o teu deep agent pré-configurado. Depois, em vez de iniciares um web server ou um loop de linha de comandos, fazes wrap do teu agente numa interface de servidor ACP. Consegues isto chamando uma função run dedicada e passando um objeto AgentServerACP, que por si só faz wrap da lógica subjacente do teu agente. Aqui está o ponto-chave. Quando configuras este servidor, defines que ele deve usar standard input e standard output, vulgarmente conhecido como modo stdio. Isto é crucial porque significa que não há portas de rede para gerir, regras de firewall para contornar, nem web sockets para fazer debug. O processo do agente simplesmente escuta as strings de texto recebidas no standard input e imprime as suas respostas estruturadas no standard output. A seguir, tens de ligar o teu editor a este script. Considera o editor Zed como um cenário concreto. Dentro do Zed, abres o teu ficheiro JSON de user settings. Adicionas um bloco de configuração a instruir o editor a usar um agente personalizado. Em vez de apontares o Zed para um endpoint de REST API remoto, apontas diretamente para o teu executável Python local, fornecendo o path para o teu novo script ACP como argumento principal. Quando inicias uma sessão, o editor faz spawn do teu script Python como um processo oculto em background. Sempre que pedes uma edição inline ou destacas uma função para refactoring, o editor envia uma mensagem ACP estruturada através do standard input diretamente para o teu script em execução. O teu agente personalizado processa o pedido, percorre o seu node graph interno, consulta a sua memória e imprime a resposta formatada em ACP de volta para o standard output. O editor captura esse output e aplica as alterações de código nativamente na janela da tua aplicação. A principal lição a tirar daqui é o controlo. Ao encaminhares o teu agente personalizado através do ACP via stdio, deixas de depender de um assistente genérico e passas a colaborar com uma entidade que entende inerentemente as convenções específicas da tua codebase. É tudo por este episódio. Obrigado por ouvires, e continua a programar!

Olá, daqui é o Alex da DEV STORIES DOT EU. Deep Agents, episódio 16 de 16. Pedes ao teu agent um refactor massivo da codebase, e a interface de chat congela imediatamente. Ficas a olhar para uma roda a girar durante vinte minutos, sem conseguires fazer perguntas ou mudar de ideias. Para resolveres isto, precisas de background workers com async subagents. Os subagents standard são síncronos. Eles bloqueiam a main thread. O supervisor delega uma task e simplesmente espera até que termine. Os async subagents mudam completamente esta dinâmica, ao correrem como background workers non-blocking. Quando o supervisor atribui trabalho, não espera pelo resultado. Recebe imediatamente um job ID e devolve o controlo ao utilizador. A user interface mantém-se responsiva enquanto o trabalho pesado acontece noutro lado. Configuras estes background workers usando a especificação Async SubAgent. Quando fazes o deploy da tua aplicação para o LangSmith Deployments, estes async subagents são alojados de forma independente. O supervisor principal comunica com eles através de transport protocols standard. Se fizeres o deploy do worker exatamente no mesmo servidor que o supervisor, eles comunicam usando ASGI, que é altamente eficiente para routing local. Se o worker estiver num servidor remoto separado, o supervisor liga-se a ele por HTTP. Para orquestrar estes remote workers, o supervisor está equipado com um conjunto específico de async tools. Lembra-te daquele pedido de refactor da codebase. O utilizador pede a reescrita. O supervisor decide que isto vai demorar muito tempo e chama a tool start async task. Esta tool arranca o coder subagent e entrega um job ID ao supervisor. O supervisor responde ao utilizador, confirmando que o background job está a correr. Como a main thread está livre, o utilizador pode continuar a conversa. Uns minutos depois, o utilizador pode perguntar como está a correr o refactor. O supervisor chama a tool check async task, passando o job ID, e recupera o status de execução atual do worker. Aqui está o ponto chave. O utilizador não fica bloqueado fora do processo enquanto o worker corre. Se o utilizador de repente perceber que precisa que o refactor force strict type hinting, pode simplesmente dizer ao supervisor. O supervisor chama então a tool update async task. Isto envia novas instruções de steering a meio do processo diretamente para o subagent que está a correr, sem reiniciar o job do zero. Se o utilizador decidir que o refactor foi uma péssima ideia, o supervisor usa a tool cancel async task para terminar o background process de forma limpa. Um ponto comum de confusão é como o supervisor se lembra destes jobs durante uma sessão longa. Com o tempo, os chat histories são compactados para poupar context tokens. Se o job ID existisse apenas como texto no histórico da conversa, o supervisor acabaria por se esquecer dele e perder o rasto do worker. Para evitar isto, a metadata da task nunca é guardada apenas no chat log. É guardada num state channel dedicado chamado async tasks. Este state channel opera de forma independente da lista de mensagens, garantindo que os job IDs ativos sobrevivem a qualquer compactação da conversa. Passar de blocking calls para background workers muda a tua arquitetura de uma simples chat interface para um motor de orquestração paralelo capaz de lidar com workloads massivos. Como isto conclui a nossa série atual, encorajo-te a ler a documentação oficial, a tentares fazer o deploy de um async worker tu mesmo, ou a visitares devstories dot eu para sugerires tópicos para a nossa próxima temporada. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.