Spring AI e Bedrock AgentCore: um agente Java em produção com uma anotação e dois endpoints

Se você tem uma equipe enterprise em Java, a história com agentes costuma ser assim: alguém montou uma demo em Python, todos gostaram, e depois se descobre que ela não se encaixa no seu CI/CD, no monitoramento e no modelo de acesso. Em uma nova análise, a AWS propõe outro caminho: não trocar de stack, mas conectar agentes por meio do Spring AI e do Bedrock AgentCore.

Como um agente difere de uma chamada ao modelo

Um chat completion comum gera texto, mas não decide o que fazer a seguir, não acessa sistemas externos e não lembra da conversa de ontem. Um agente reúne três coisas: planejamento (dividir o objetivo em etapas e revisar o plano ao longo do caminho), ferramentas (APIs, bancos de dados, interpretador de código) e memória (dentro da sessão e entre sessões).

Uma aplicação RAG não é um agente: ela tem busca, mas não tem um ciclo de planejamento. O agente trabalha em loop até cumprir a tarefa ou decidir que não pode continuar.

Como isso aparece no código

O AgentCore é uma plataforma gerenciada da AWS que não está atrelada a um framework ou modelo. O runtime exige do seu serviço apenas dois endpoints: POST /invocations para requisições (JSON ou SSE em streaming) e GET /ping para verificação de saúde. Se a tarefa for longa, o serviço deve responder HealthyBusy; caso contrário, o runtime pode reduzir sua escala.

O Spring AI AgentCore SDK esconde esse contrato atrás da anotação @AgentCoreInvocation: ela mesma cria os dois endpoints, serializa o JSON e formata o SSE. O mesmo serviço pode servir REST para uma interface React, então não é preciso um backend separado para o agente.

As ferramentas são conectadas no mesmo estilo Spring. Você marca um método com @Tool e uma descrição, registra no ChatClient via defaultTools, e o modelo decide por conta própria quando chamá-lo. Para uma resposta estruturada, pede-se um record Java, e para documentos anexa-se um arquivo à mensagem do usuário. A memória é conectada por meio de advisors: interceptadores que adicionam contexto ao prompt antes da chamada ao modelo. O trecho sobre memória no texto original é interrompido, então consulte o original para os detalhes.

De um agente para vários

O segundo exemplo é um sistema de processamento de documentos com cinco especialistas: jurídico, hipoteca, seguros, impostos e um agente geral. Um classificador determina o tipo de documento e o encaminha ao especialista adequado. Ele devolve um JSON estruturado com uma pontuação de confiança. Em seguida, regras em SpEL do application.yml decidem o que fazer: enviar um ALERT, bloquear ou encaminhar o documento para revisão manual.

São três padrões: roteador (apenas despacho, sem lógica de domínio), avaliador (regras de negócio sobre as respostas) e fan-out paralelo. O último não está implementado na solução base: o processamento em lote é sequencial. Se o fan-out for adicionado, o tempo de análise será determinado pelo agente mais lento, e não pela soma de todas as chamadas.

Limitações

Primeira: este é um material da AWS, voltado ao ecossistema da AWS. Bedrock Converse API, AgentCore, Graviton e módulos Terraform: tudo em um único pacote. A portabilidade para outras nuvens não é discutida no artigo.

Segunda: a saída estruturada em um record Java foi testada com o Claude Sonnet 4.5. O Spring AI adiciona o esquema ao prompt e faz o parsing da resposta, mas às vezes o modelo devolve dados fora do esquema. Para maior rigor, é preciso um provedor com controle nativo de esquema ou validação com nova solicitação.

Terceira: em chamadas de ferramentas com vários argumentos, os autores recomendam obter a resposta com um call() bloqueante e depois dividi-la em chunks, para que os argumentos sejam associados de forma confiável. Isso reduz o benefício do streaming de verdade.

O que fazer

Se você tem uma stack Java e já está na AWS, comece pelo assistente de viagens: um agente, ferramentas e memória. Verifique como o seu modelo se comporta com saída estruturada e só depois adicione o roteador e as regras. Os requisitos são rigorosos: JDK 21, Spring Boot 4.1 com Spring AI 2.0, Terraform 1.5+ e Docker com Buildx para a imagem ARM64. Certifique-se antecipadamente de que o seu projeto suportará essa atualização.