User's blog

Persistência de Estado de Sessão com Configuração de Filesystem e Execução de Comandos Shell

Written by

Make.com Service User

in

A Evolução dos Agentes de IA e o Desafio da Efêmera

Os agentes de inteligência artificial ultrapassaram a simples conversa e evoluíram significativamente. Hoje, eles conseguem escrever código, gerenciar estado persistente em filesystem, executar comandos de sistema operacional e administrar estados ao longo de toda a estrutura de diretórios. À medida que assistentes de codificação baseados em agentes e fluxos de desenvolvimento se tornaram mais maduros, o filesystem emergiu como a memória de trabalho principal desses agentes, estendendo suas capacidades muito além da janela de contexto disponível em modelos de linguagem grandes.

Porém, essa mudança de paradigma introduz dois desafios que toda equipe desenvolvendo agentes em ambiente de produção enfrenta inevitavelmente.

O Primeiro Desafio: Filesystems Efêmeros

O filesystem é temporário por natureza. Quando a sessão do agente termina, tudo que foi criado desaparece: dependências instaladas, código gerado, histórico local do git. Nada persiste.

O Segundo Desafio: Operações Determinísticas sem Intermediários

Quando seu fluxo de trabalho precisa executar operações determinísticas como npm test ou git push, você fica forçado a rotear essas operações através do modelo de linguagem grande (LLM) ou construir ferramentas customizadas fora do runtime. Nenhuma dessas opções é ideal.

Duas Soluções Integradas do Amazon Bedrock AgentCore Runtime

A AWS respondeu a esses desafios com duas capacidades inovadoras no Amazon Bedrock AgentCore Runtime: armazenamento de sessão gerenciado para persistir estado de filesystem do agente (em preview público) e execução de comando (InvokeAgentRuntimeCommand) para rodar comandos shell diretamente dentro da máquina virtual de rede (microVM) associada a cada sessão ativa do agente.

Cada uma delas é útil isoladamente. Juntas, elas desbloqueiam workflows que não eram possíveis anteriormente.

Compreendendo a Arquitetura do AgentCore Runtime

Isolamento e Segurança da Sessão

O AgentCore Runtime executa cada sessão em uma máquina virtual de rede dedicada com recursos isolados, incluindo seu próprio kernel, memória e filesystem. Essa arquitetura proporciona limites de segurança robustos, mas também implica que cada sessão começa com um filesystem limpo. Quando a microVM é finalizada — seja através de uma parada explícita ou timeout de inatividade — tudo que o agente criou desaparece.

Na prática, isso significa que seu agente de codificação pode gastar vinte minutos estruturando um projeto inteiro: configurando diretórios, instalando dependências, gerando código boilerplate, configurando ferramentas de build. Você tira um intervalo para almoçar e, quando retorna invocando a mesma sessão, o agente começa do zero. Cada pacote reinstalado, cada arquivo regeneado. Vinte minutos de computação desperdiçados antes que o agente possa fazer trabalho útil novamente.

As Soluções Anteriores e Suas Limitações

Essa limitação poderia ser contornada escrevendo lógica de checkpoint para fazer upload de arquivos para Amazon Simple Storage Service (S3) antes de parar a sessão e baixá-los ao retomar, ou mantendo sessões vivas para evitar perda de estado. Essas soluções funcionam, mas não resolvem as limitações no nível de filesystem e adicionam complexidade ao código do agente.

A mesma fricção existe para operações determinísticas. Quando o agente termina uma correção e você precisa rodar testes, rotear o comando através do LLM como uma chamada de ferramenta adiciona custo de tokens, latência e não-determinismo a uma operação previsível. A alternativa é construir lógica de orquestração separada fora do runtime, o que exige conectar-se ao filesystem do agente, adicionando ainda mais complexidade.

Armazenamento de Sessão Gerenciado: Estado que Persiste

O Conceito de Armazenamento Persistente

A AWS introduziu armazenamento de sessão gerenciado para resolver o desafio dos filesystems efêmeros. Ele oferece ao agente um diretório persistente que sobrevive aos ciclos de parada e retomada. A persistência é integrada no runtime e configurada na criação do agente — tudo que é escrito naquele diretório persiste mesmo quando o ambiente de computação é substituído.

Configurando Armazenamento Persistente

Para configurar armazenamento persistente, você adiciona sessionStorage à configuração de filesystem do runtime do agente. Usando a interface de linha de comando:

aws bedrock-agentcore create-agent-runtime \
  --agent-runtime-name "coding-agent" \
  --role-arn "arn:aws:iam::111122223333:role/AgentExecutionRole" \
  --agent-runtime-artifact '{"containerConfiguration": { "containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest" }}' \
  --filesystem-configurations '[{ "sessionStorage": { "mountPath": "/mnt/workspace" } }]'

Ou utilizando o AWS SDK para Python (Boto3):

import boto3

# Use the control plane client for creating and managing runtimes
control_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = control_client.create_agent_runtime(
    agentRuntimeName='coding-agent',
    agentRuntimeArtifact={
        'containerConfiguration': {
            'containerUri': '123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest'
        }
    },
    roleArn='arn:aws:iam::111122223333:role/AgentExecutionRole',
    protocolConfiguration={
        'serverProtocol': 'HTTP'
    },
    networkConfiguration={
        'networkMode': 'PUBLIC'
    },
    filesystemConfigurations=[{
        'sessionStorage': {
            'mountPath': '/mnt/workspace'
        }
    }]
)

Detalhes Importantes sobre Clientes Boto3

Uma observação técnica importante: o AgentCore utiliza dois clientes Boto3 distintos. O cliente do plano de controle (bedrock-agentcore-control) gerencia operações de ciclo de vida do runtime como CreateAgentRuntime, GetAgentRuntime e DeleteAgentRuntime. O cliente do plano de dados (bedrock-agentcore) lida com operações de sessão como InvokeAgentRuntime e InvokeAgentRuntimeCommand.

O caminho de montagem deve começar com /mnt seguido por um nome de pasta (por exemplo, /mnt/workspace ou /mnt/data). Após configurado, qualquer arquivo que o agente escreva nesse caminho é automaticamente persistido em armazenamento gerenciado.

A Experiência de Parada e Retomada

Você invoca seu agente e solicita que configure um projeto:

aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:...:agent-runtime/coding-agent" \
  --runtime-session-id "session-001" \
  --payload '{"prompt": "Set up the project and install dependencies in /mnt/workspace"}'

O agente baixa o código, instala os pacotes e gera as configurações na microVM dedicada a essa sessão. Depois, você para a sessão ou o timeout de inatividade dispara, e a microVM finaliza. Horas depois, você retorna e invoca com o mesmo ID de sessão:

aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:...:agent-runtime/coding-agent" \
  --runtime-session-id "session-001" \
  --payload '{"prompt": "Run the tests and fix any failures"}'

Um novo ambiente de computação (microVM) é provisionado e monta o mesmo armazenamento. O agente vê /mnt/workspace exatamente como deixou: arquivos de código, node_modules, artefatos de build e histórico .git intactos. O agente retoma seu trabalho sem necessidade de reinstalar ou regenerar. Do ponto de vista do agente, nada extraordinário está acontecendo — ele apenas lê e escreve em um diretório como faria normalmente. Seu código de agente não precisa mudar: sem APIs especiais, sem lógica de salvar/restaurar, sem serialização. Escreva um arquivo em /mnt/workspace, pare a sessão, retome, e o arquivo continua lá.

Controle da Retenção de Dados

Por padrão, os dados de armazenamento de sessão são retidos por 14 dias de inatividade. Se a sessão não for retomada dentro dessa janela, os dados são limpos automaticamente. Quando o endpoint do agente é atualizado para uma versão diferente e o mesmo ID de sessão é invocado, os dados da sessão são atualizados, oferecendo um contexto limpo para a nova versão.

Um Fluxo de Trabalho de Múltiplos Dias na Prática

Dia 1: Análise e Preparação

Você invoca seu agente de codificação e solicita que baixe uma base de código, inspecione os arquivos e configure o ambiente de desenvolvimento:

aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:...:agent-runtime/coding-agent" \
  --runtime-session-id "fefc1779-e5e7-49cf-a2c4-abaf478680c4" \
  --payload '{"prompt": "Download the code from s3://amzn-s3-demo-bucket/fastapi-demo-main.zip and list all files"}'

O agente baixa o repositório para /mnt/workspace, extrai o conteúdo e relata:

Arquivos no projeto fastapi-demo-main:

  • Dockerfile
  • README.md
  • main.py
  • requirements.txt

Você fecha seu laptop e vai para casa.

Dia 2: Implementação e Iteração

Você invoca com o mesmo ID de sessão:

aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:...:agent-runtime/coding-agent" \
  --runtime-session-id "fefc1779-e5e7-49cf-a2c4-abaf478680c4" \
  --payload '{"prompt": "Add a new function called hello_world to main.py"}'

O agente enxerga o projeto exatamente como deixou. Ele modifica o main.py diretamente. Sem re-download, sem re-extração. Quando você pede ao agente para listar os arquivos, tudo continua lá, incluindo o main.py modificado com a nova função hello_world. A microVM de ontem já foi finalizada, mas o trabalho persiste.

Execução de Comando Shell: Operações Determinísticas Diretas

O Problema das Operações Determinísticas

Agora que seu agente escreveu novo código, você precisa verificar que funciona. É onde a segunda capacidade entra em cena: InvokeAgentRuntimeCommand permite executar comandos shell diretamente dentro de uma sessão ativa do AgentCore Runtime e transmitir a saída de volta via HTTP/2.

Quando Usar Cada Abordagem

O conceito-chave é que agentes e comandos shell são bons em coisas diferentes. Use execução de comando para operações com comando conhecido (npm test, git push), operações que exigem execução determinística, fluxos que precisam de saída em tempo real de processos longos, validação de gate de fluxo de trabalho ou bootstrap de ambiente. Use o agente para operações que exigem raciocínio (“analise esse código e corrija o bug”), quando você quer que o LLM decida o que fazer, para trabalho criativo ou analítico.

Quando seu agente termina de escrever código e você precisa rodar testes, não deveria precisar do LLM para isso. npm test é npm test. O comando é conhecido, o comportamento deve ser determinístico, e você quer a saída bruta, não a interpretação do LLM.

Executando um Comando

Execute um comando utilizando o AWS SDK para Python (Boto3):

import boto3
import sys

client = boto3.client('bedrock-agentcore', region_name='us-west-2')
response = client.invoke_agent_runtime_command(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my-agent',
    runtimeSessionId='session-id-at-least-33-characters-long',
    body={
        'command': '/bin/bash -c "npm test"',
        'timeout': 60
    }
)

for event in response['stream']:
    if 'chunk' in event:
        chunk = event['chunk']
        if 'contentStart' in chunk:
            print("Command execution started")
        if 'contentDelta' in chunk:
            delta = chunk['contentDelta']
            if delta.get('stdout'):
                print(delta['stdout'], end='')
            if delta.get('stderr'):
                print(delta['stderr'], end='', file=sys.stderr)
        if 'contentStop' in chunk:
            stop = chunk['contentStop']
            print(f"\nExit code: {stop.get('exitCode')}, Status: {stop.get('status')}")

Tipos de Eventos da Resposta

A resposta transmite três tipos de evento em tempo real: contentStart (primeiro chunk, confirma que o comando começou), contentDelta (durante execução, contém saída stdout e/ou stderr) e contentStop (último chunk, contém exitCode e status — COMPLETED ou TIMED_OUT).

Como a saída é transmitida conforme é produzida, você pode detectar uma falha nos primeiros segundos e reagir imediatamente, em vez de esperar pela execução completa.

Detalhes Críticos: Mesmo Container, Mesmo Filesystem

Um detalhe crítico: comandos executam no mesmo container, filesystem e ambiente que seu agente, não em um sidecar ou processo separado comunicando via socket. Um arquivo que o agente escreveu em /mnt/workspace/fix.py é imediatamente visível para um comando executando cat /mnt/workspace/fix.py. Não há etapa de sincronização, transferência de arquivo ou volume compartilhado a configurar.

O AgentCore Runtime microVM não inclui ferramentas de desenvolvimento por padrão. Portanto, qualquer ferramenta que seus comandos dependem — git, npm ou runtimes de linguagem — deve ser adicionado na imagem de container ou instalado dinamicamente em tempo de execução.

Características de Design que Moldam o Uso

Os comandos seguem um design de execução única: cada comando dispara um novo processo bash, executa até conclusão (ou timeout) e retorna. Sem sessão shell persistente entre comandos. Isso alinha-se com como frameworks de agentes usam execução de comando: elaborar um comando, executá-lo, ler saída e decidir o próximo passo.

A execução é não-bloqueante: execução de comando não bloqueia invocações de agente. Você pode invocar o agente e rodar comandos concorrentemente na mesma sessão.

Cada comando é stateless: cada comando inicia limpo, sem histórico de shell e variáveis de ambiente de comandos anteriores não persistem. Se você precisa de estado, codifique na comando: cd /workspace && export NODE_ENV=test && npm test.

Casos de Uso Práticos

Equipes estão construindo com essas capacidades: automação de testes — após o agente escrever código, rodar npm test ou pytest como comando, transmitir saída e realimentar falhas específicas ao agente para iteração; fluxos git — branching, commit e push são determinísticos, rodar como comandos mantém lógica de controle de versão fora do LLM; bootstrap de ambiente — clonar repos, instalar pacotes, configurar ferramentas de build antes do agente começar, muito mais rápido e confiável como comandos diretos; pipelines de build — qualquer coisa com comando conhecido que deve rodar exatamente como especificado (cargo build --release, mvn package, go build); gates de validação — rodar linters, verificadores de tipo, scanners de segurança como gate após o agente escrever código mas antes de fazer commit; debug — inspecionar ambiente de runtime, verificar pacotes instalados, uso de disco, processos rodando. Tudo útil para entender falhas de agente.

Melhor Juntas: O Filesystem como Contexto Compartilhado

A Sinergia das Duas Capacidades

Armazenamento de sessão gerenciado resolve o desafio de filesystems efêmeros. Execução de comando resolve o desafio de operações determinísticas. Cada uma é valiosa isoladamente, mas são mais poderosas juntas porque compartilham o mesmo filesystem que une todo o fluxo de trabalho.

Quando seu runtime de agente tem armazenamento de sessão gerenciado configurado em /mnt/workspace, tudo opera no mesmo diretório persistente: InvokeAgentRuntime escreve código, gera artefatos e gerencia arquivos em /mnt/workspace. InvokeAgentRuntimeCommand executa testes, operações git e builds lendo e escrevendo no mesmo /mnt/workspace. Você para a sessão, computação (microVM) desliga, /mnt/workspace persiste. Retorna no dia seguinte, nova computação monta o mesmo armazenamento. Tanto agente quanto execute command veem os mesmos arquivos. O filesystem torna-se o contexto compartilhado que conecta raciocínio do agente, operações determinísticas e tempo.

Exemplo Integrado de Uso

Aqui está como parece em código:

import boto3
import json

client = boto3.client('bedrock-agentcore', region_name='us-west-2')
AGENT_ARN = 'arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my-coding-agent'
SESSION_ID = 'fefc1779-e5e7-49cf-a2c4-abaf478680c4'

def run_command(command, timeout=60):
    """Execute a shell command and return the exit code."""
    response = client.invoke_agent_runtime_command(
        agentRuntimeArn=AGENT_ARN,
        runtimeSessionId=SESSION_ID,
        contentType='application/json',
        accept='application/vnd.amazon.eventstream',
        body={'command': command, 'timeout': timeout}
    )
    for event in response.get('stream', []):
        if 'chunk' in event and 'contentStop' in event['chunk']:
            return event['chunk']['contentStop'].get('exitCode')
    return None

# Step 1: The agent analyzes the issue and writes a fix
# (Reasoning task → use InvokeAgentRuntime)
response = client.invoke_agent_runtime(
    agentRuntimeArn=AGENT_ARN,
    runtimeSessionId=SESSION_ID,
    payload=json.dumps({
        "prompt": "Read JIRA-1234 and implement the fix in /mnt/workspace"
    }).encode()
)

# Process agent response...

# Step 2: Run the test suite
# (Deterministic operation → use InvokeAgentRuntimeCommand)
exit_code = run_command('/bin/bash -c "cd /mnt/workspace && npm test"', timeout=300)

# Step 3: If tests pass, commit and push
# (Deterministic operation → use InvokeAgentRuntimeCommand)
if exit_code == 0:
    run_command('/bin/bash -c "cd /mnt/workspace && git checkout -b fix/JIRA-1234"')
    run_command('/bin/bash -c "cd /mnt/workspace && git add -A && git commit -m \'Fix JIRA-1234\'"')
    run_command('/bin/bash -c "cd /mnt/workspace && git push origin fix/JIRA-1234"')

O agente escreve o código enquanto a plataforma executa os comandos. Cada um faz o que foi desenhado para fazer. Como /mnt/workspace é respaldado por armazenamento de sessão gerenciado, você pode parar essa sessão, retornar no dia seguinte, e todo o workspace continua lá pronto para o agente continuar iterando. Esse é o padrão: o agente raciocina, execute command atua, e o filesystem persistente lembra.

Primeiros Passos

Ambas as capacidades já estão disponíveis. Aqui está como começar a usá-las:

Armazenamento de sessão gerenciado (preview público) — Adicione filesystemConfigurations com sessionStorage ao chamar CreateAgentRuntime. Especifique um caminho de montagem começando com /mnt. Tudo que seu agente escrever naquele caminho persiste entre ciclos de parada/retomada. Dados máximos permitidos são 1 GB por sessão.

Execução de comando — Chame InvokeAgentRuntimeCommand com uma string de comando e timeout em qualquer sessão ativa. O comando executa no mesmo container que seu agente, com acesso ao mesmo filesystem.

Para começar com tutoriais e código de exemplo:

Conclusão

Tudo começou com dois desafios: agentes que perdem seu trabalho quando sessões param e operações determinísticas que precisam ser roteadas através do LLM ou construídas fora do runtime. Armazenamento de sessão gerenciado e execução de comando resolvem ambos esses desafios. O filesystem compartilhado entre eles cria um loop de desenvolvimento onde o agente raciocina, comandos executam e o trabalho persiste entre sessões. As três capacidades formam um loop que não quebra quando você fecha seu laptop. Teste as novas capacidades do Amazon Bedrock AgentCore e compartilhe o que você constrói.

Fonte

Persist session state with filesystem configuration and execute shell commands (https://aws.amazon.com/blogs/machine-learning/persist-session-state-with-filesystem-configuration-and-execute-shell-commands/)

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts