User's blog

Visualize apps web em tempo real enquanto seu agente de código os constrói com o Amazon Bedrock AgentCore Runtime

Written by

Make.com Service User

in

O problema que os Session Endpoints resolvem

Agentes de código já são capazes de construir aplicações web funcionais — dashboards, páginas de produto, protótipos que times de produto querem testar rapidamente. O gargalo sempre foi o ciclo de revisão: para ver o resultado de uma alteração, era necessário copiar os arquivos gerados e implantá-los em algum ambiente, o que tornava cada iteração lenta e trabalhosa.

A solução ideal é manter a aplicação rodando no mesmo lugar onde o agente a edita, de forma que cada mudança apareça no navegador em segundos. É exatamente isso que os Session Endpoints do AgentCore Runtime entregam.

O que é o Amazon Bedrock AgentCore

O Amazon Bedrock AgentCore é uma plataforma da AWS para construir, conectar e otimizar agentes em escala, com liberdade de escolha de framework e modelo de fundação (FM — Foundation Model). O AgentCore Runtime, uma das capacidades da plataforma, executa cada sessão de agente em sua própria microVM isolada.

Com os Session Endpoints, é possível abrir uma aplicação que está rodando dentro dessa sessão diretamente no navegador. Cada sessão recebe uma URL autenticada que encaminha o método HTTP, o caminho, a query string, o corpo da requisição e conexões WebSocket para as portas que você autorizar.

Como os Session Endpoints funcionam

Seis detalhes definem o comportamento dos Session Endpoints:

  • Você escolhe as portas acessíveis. O parâmetro allowedPorts é definido na chamada CreateAgentRuntime: de 1 a 5 entradas, cada uma sendo uma porta única ou um intervalo dentro de 8000–12000, excluindo as portas reservadas da plataforma. Liberar uma porta não inicia um servidor — a aplicação precisa estar ouvindo nela, vinculada a 0.0.0.0.
  • A URL chega junto com a sessão. A resposta do InvokeAgentRuntime traz a URL no header X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url, exposto pelos SDKs como sessionEndpointUrl.
  • Toda requisição é autenticada. Para runtimes que usam Gerenciamento de Identidade e Acesso da AWS (IAM), cada requisição HTTP, stream HTTP/2 e handshake WebSocket carrega uma assinatura Signature Version 4 (SigV4). O chamador também precisa da permissão bedrock-agentcore:InvokeAgentRuntimeProxy. Para runtimes com um autorizador JSON Web Token (JWT) de entrada, cada requisição carrega um bearer token. Conhecer a URL não garante acesso.
  • O hostname seleciona a porta. O cliente sempre conecta na porta 443, e um prefixo no hostname escolhe a porta dentro da sessão. Por exemplo: https://8090--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/index.html
  • Suporte a múltiplos protocolos. Requisições HTTP/1.1 e HTTP/2, incluindo server-sent events e gRPC, além de conexões WebSocket, são todas suportadas.
  • Escopo de uma única sessão. A URL exige credenciais em cada requisição e dura apenas enquanto a sessão existir. Use-a para construir, testar e revisar o que o agente produz. Para servir uma aplicação aos seus usuários finais, implante-a em um serviço de hospedagem como o AWS Amplify Hosting.

Como um navegador não consegue adicionar uma assinatura SigV4 ou um bearer token por conta própria, o cliente de Session Endpoint do SDK bedrock-agentcore abre um endpoint local na sua máquina. O navegador acessa http://localhost:8088, e esse endpoint local adiciona suas credenciais a cada requisição e handshake WebSocket antes de encaminhá-los.

Session Endpoint vs. Runtime Endpoint

É importante não confundir os dois conceitos. O runtime endpoint já é fornecido pelo AgentCore Runtime e serve para alcançar o agente em si — ele controla qual versão do agente os chamadores vão atingir, permitindo manter desenvolvimento e produção em versões diferentes. Já o Session Endpoint serve para visualizar o que o agente executa dentro da sessão, como uma prévia web. Ele alcança apenas as portas que você autorizou, funciona com qualquer versão que a sessão esteja rodando e para de funcionar quando a sessão encerra.

Visão geral da solução de exemplo

A AWS publicou um exemplo completo com quatro componentes principais:

  • Um agente de código rodando na sessão na porta 8080, que edita os arquivos do site com quatro ferramentas: listar, ler, escrever e editar.
  • Um servidor de desenvolvimento Vite na porta 8090, que serve o site e envia cada alteração salva ao navegador via hot-reload WebSocket.
  • O PreviewApp na sua máquina, que serve a página de preview, envia seus prompts ao InvokeAgentRuntime e abre um endpoint local para a porta 8090.
  • A página de preview em si, com o chat à esquerda e o site ao vivo à direita.

O fluxo funciona assim: a página de preview carrega o site do servidor Vite na porta 8090 através do endpoint local e do Session Endpoint. Quando você envia um prompt pelo chat, o PreviewApp o encaminha ao agente via InvokeAgentRuntime. O agente consulta o Claude Haiku 5.5 no Amazon Bedrock para decidir o que alterar, lê e salva os arquivos necessários. O Vite detecta a mudança e envia a atualização pelo WebSocket, de volta pelo Session Endpoint e pelo endpoint local, e o site se atualiza no navegador sem precisar de um refresh.

O exemplo completo, incluindo o notebook que acompanha o walkthrough, está disponível no repositório agentcore-samples no GitHub.

Pré-requisitos para seguir o walkthrough

O exemplo implanta o agente como um arquivo zip no Amazon S3 usando implantação direta de código para Node.js, sem necessidade de Docker ou de um repositório no Amazon Elastic Container Registry (Amazon ECR). Session Endpoints funcionam com runtimes de microVM, não com o tipo de computação Instances. As URLs são acessíveis via HTTPS público — AWS PrivateLink não é suportado para conexões de entrada.

Implantando o agente e o site

O script de implantação empacota o agente em um único arquivo, adiciona o site e suas dependências para o sistema Linux on Arm64 do runtime, faz upload do zip para o Amazon S3 e cria o runtime. O trecho abaixo de deploy.py mostra as duas configurações centrais: protocolConfiguration define onde o agente escuta o InvokeAgentRuntime, e allowedPorts lista as portas que o Session Endpoint pode alcançar — 8090 para o site e 8081 para a rota de status do agente. A porta 8080 não está na lista porque o InvokeAgentRuntime alcança o agente diretamente, sem passar pelo Session Endpoint.

agentRuntimeArtifact={"codeConfiguration": {
    "code": {"s3": {"bucket": code_bucket(), "prefix": S3_PREFIX}},
    "runtime": "NODE_22",
    "entryPoint": ["app.js"],
}},
protocolConfiguration={"serverProtocol": "HTTP", "port": 8080, "path": "/invocations"},
allowedPorts=[{"port": 8090}, {"port": 8081}],

A configuração do Vite faz o servidor de desenvolvimento ser acessível pelo Session Endpoint: ele escuta em 0.0.0.0 na porta 8090 e não restringe o header Host (server.allowedHosts é true), pois as requisições chegam com um hostname atribuído pelo runtime, não localhost. Como o Session Endpoint autentica cada requisição antes de encaminhá-la ao servidor, o servidor não precisa fazer sua própria verificação de host.

Para implantar o runtime:

git clone https://github.com/awslabs/agentcore-samples.git
cd agentcore-samples/01-features/02-host-your-agent/01-runtime/03-advanced/16-session-endpoints

Em seguida, abra o notebook session_endpoints_preview.ipynb, execute a célula de instalação das dependências Python e depois a célula %run deploy.py. A implantação leva alguns minutos, principalmente aguardando o runtime atingir o status READY.

Abrindo o preview e pedindo alterações

Com o runtime pronto, uma única chamada inicia o preview, abre um endpoint local para a porta 8090 e serve a página de preview em localhost:8087:

from preview_app import PreviewApp
app = PreviewApp().start()
print("Open", app.url)

Internamente, a primeira chamada ao InvokeAgentRuntime retorna a URL do Session Endpoint no header de resposta. O cliente então abre o endpoint local para a porta 8090:

answer = client.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn,
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": ""}).encode(),
    contentType="application/json",
)
endpoint = client.session_endpoint_client(session_endpoint_url(answer))
local = endpoint.open_local_endpoint(port=8090, local_port=8088).start()

Com a página aberta em http://localhost:8087, você verá o site à direita e um chat à esquerda. Ao pedir uma mudança — por exemplo, “Switch this website to a dark coffee-house color theme” — o agente lê os arquivos necessários, salva os alterados e o Vite empurra a mudança pelo WebSocket. O site atualiza no browser sem refresh.

Você também pode enviar prompts diretamente do Python:

for event in app.ask("Make the Order ahead button green"):
    if "step" in event:
        print(" ", event["step"])
    elif "done" in event:
        print(event["done"]["reply"])

Acessando uma segunda porta na mesma sessão

O site não é o único servidor acessível. O agente serve uma rota /status na porta 8081, que lista cada prompt recebido e os arquivos que ele alterou. O mesmo Session Endpoint alcança essa rota — a única diferença é o argumento de porta:

status = app.endpoint.request("GET", "/status", port=8081)
print("GET /status on port 8081: HTTP", status.status)
for edit in status.json()["edits"]:
    print(" ", edit["prompt"], "->", ", ".join(edit["files"]))

O que o Session Endpoint recusa

Quando o runtime recusa uma requisição, ele responde com um status HTTP, corpo vazio e um código de erro em um header de resposta. A tabela abaixo resume as recusas mais comuns:

  • Porta fora do allowedPorts: 403 AccessDenied
  • Requisição sem credenciais válidas: 403 AccessDenied ou 401 AuthenticationRequired
  • Porta permitida sem servidor ouvindo: 502 PortNotReachable
  • URL de sessão que não existe mais: 404 SessionNotFound

Como o acesso à sessão é protegido

O runtime remove seus próprios headers de autenticação antes de encaminhar uma requisição, de forma que o site nunca recebe a assinatura do chamador. As requisições são registradas no AWS CloudTrail como eventos InvokeAgentRuntimeProxy, com a fonte de evento bedrock-agentcore.amazonaws.com. Para mais detalhes, consulte a documentação sobre registro de requisições de Session Endpoint no CloudTrail.

O endpoint local age com suas credenciais, o que limita quem pode usá-lo: ele escuta apenas em 127.0.0.1, responde somente a requisições endereçadas ao seu próprio endereço local e recusa conexões WebSocket abertas por páginas de outras origens. Execute o endpoint local apenas enquanto estiver usando o preview.

Os controles de acesso não separam o site do agente — ambos rodam na mesma sessão. Por isso, conceda à execution role apenas as permissões que o agente realmente precisa. Se o runtime substituir o compute da sessão, conexões abertas se fecham e as edições do agente podem não sobreviver, a menos que a sessão use armazenamento persistente. Consulte a documentação sobre configurações de sistema de arquivos para o AgentCore Runtime se precisar que os arquivos persistam além do compute.

Se outras pessoas puderem enviar prompts ao seu agente de código, considere usar o Amazon Bedrock Guardrails para filtrar prompts e respostas prejudiciais, e revise as alterações do agente antes de publicá-las.

Limpeza dos recursos

Para evitar cobranças contínuas, pare o preview e delete os recursos criados pelo exemplo. O site editado pelo agente vive na sessão e é removido junto com ela. Execute a célula stop no notebook e pressione Enter quando solicitado — isso para a página de preview, o endpoint local e a sessão. Em seguida, execute %run cleanup.py, que deleta o runtime, o código enviado ao S3 e a role IAM.

Conclusão

Os Session Endpoints entregam acesso autenticado às aplicações dentro de uma sessão do AgentCore Runtime diretamente das suas ferramentas, via HTTP/1.1, HTTP/2 e WebSocket, nas portas que você autorizar. O resultado prático é um ciclo de desenvolvimento muito mais ágil: peça uma mudança ao agente de código e veja o resultado no browser em segundos, sem nenhum passo de implantação intermediário.

Para explorar mais, a AWS disponibiliza documentação completa sobre como conectar a sessões de runtime por um Session Endpoint, como configurar a porta e o caminho de invocação do agente, como executar comandos shell em sessões do AgentCore Runtime e como fazer implantação direta de código para Node.js. Para uma visão geral completa do serviço, consulte como hospedar agentes ou ferramentas com o Amazon Bedrock AgentCore Runtime e explore mais exemplos no repositório agentcore-samples no GitHub.

Fonte

Preview web apps live as your coding agent builds them with Amazon Bedrock AgentCore runtime (https://aws.amazon.com/blogs/machine-learning/preview-web-apps-live-as-your-coding-agent-builds-them-with-amazon-bedrock-agentcore-runtime/)

Comments

Leave a Reply

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

More posts