Agentes de IA em Produção: Simplificando a Complexidade
A inteligência artificial agêntica está transformando a forma como as organizações utilizam modelos generativos. Em vez de simples interações de pergunta-resposta, os agentes agênticos conseguem planejar, executar e completar tarefas complexas em múltiplas etapas de forma autônoma. Embora as primeiras implementações desse tipo despertem entusiasmo nos stakeholders de negócio, escalar essas soluções para produção apresenta desafios significativos: escalabilidade, governança e segurança.
A Amazon Bedrock AgentCore foi desenvolvida como uma plataforma de IA agêntica para construir, implantar e operar agentes em escala, utilizando qualquer framework e modelo. Mas havia um problema: desenvolvedores Java queriam construir esses agentes usando os padrões familiares do Spring, porém a implantação em produção exigia uma infraestrutura complexa de ser implementada do início.
O Novo SDK Spring AI AgentCore
Com o lançamento do SDK Spring AI AgentCore em disponibilidade geral, essa barreira foi removida. O SDK é uma biblioteca de código aberto que integra as capacidades do Amazon Bedrock AgentCore diretamente em aplicações Spring AI, usando padrões já conhecidos pelos desenvolvedores: anotações, auto-configuração e advisors compostos.
Anteriormente, integrar essas capacidades em uma aplicação Spring exigia semanas de trabalho em infraestrutura: escrever controladores customizados, gerenciar streaming de Server-Sent Events (SSE), implementar verificações de saúde, controlar limitação de taxa (rate limiting) e conectar advisors do Spring, repositórios de memória e definições de ferramentas. Agora, basta adicionar uma dependência, anotar um método, e o SDK cuida do resto.
Capacidades Fundamentais do SDK
Entendendo o Contrato do AgentCore Runtime
O AgentCore Runtime gerencia o ciclo de vida e a escalabilidade dos agentes com modelo de preço por uso — você não paga por computação ociosa. O runtime roteia requisições de entrada para seu agente e monitora sua saúde, mas para isso exige que o agente siga um contrato específico.
Esse contrato demanda dois endpoints principais: o endpoint /invocations recebe requisições e retorna respostas em formato JSON ou como streaming SSE, enquanto o endpoint de saúde /ping relata status Healthy (saudável) ou HealthyBusy (saudável mas ocupado). Tarefas de longa duração precisam sinalizar o status ocupado, caso contrário o runtime pode reduzi-las para economizar custos.
O SDK implementa esse contrato automaticamente, incluindo detecção assíncrona de tarefas que reporta o status ocupado quando seu agente está processando. Além disso, oferece recursos adicionais para cargas de trabalho em produção, como tratamento apropriado de respostas SSE com framing correto, gerenciamento de backpressure e ciclo de vida de conexão para respostas grandes. Também fornece rate limiting para proteger o agente contra picos de tráfego e limitar o consumo por usuário.
Design Principles do SDK
O SDK foi construído sobre três princípios de design:
Convenção em vez de configuração: Padrões sensatos se alinham com as expectativas do AgentCore (porta 8080, caminhos de endpoints, tratamento de content-type) sem necessidade de configuração explícita.
Desenvolvimento orientado por anotações: Uma simples anotação @AgentCoreInvocation transforma qualquer método de um bean Spring em um endpoint compatível com AgentCore, com serialização automática, detecção de streaming e formatação de resposta.
Flexibilidade de implantação: O SDK funciona tanto com o AgentCore Runtime para implantação totalmente gerenciada quanto com módulos individuais (Memória, Navegador, Interpretador de Código) em aplicações rodando em Amazon EKS, Amazon ECS ou qualquer outra infraestrutura.
Construindo Seu Primeiro Agente
Passo 1: Adicionar a Dependência
Comece adicionando o BOM (Bill of Materials) Spring AI AgentCore ao seu projeto Maven, junto com o starter de runtime:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springaicommunity</groupId>
<artifactId>spring-ai-agentcore-bom</artifactId>
<version>1.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springaicommunity</groupId>
<artifactId>spring-ai-agentcore-runtime-starter</artifactId>
</dependency>
</dependencies>Passo 2: Criar o Agente
A anotação @AgentCoreInvocation informa ao SDK que o método manipula requisições de agentes. O SDK auto-configura os endpoints POST /invocations e GET /ping, gerencia a serialização JSON e relata o status de saúde automaticamente:
@Service
public class MyAgent {
private final ChatClient chatClient;
public MyAgent(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
@AgentCoreInvocation
public String chat(PromptRequest request) {
return chatClient.prompt()
.user(request.prompt())
.call()
.content();
}
}
record PromptRequest(String prompt) {}Passo 3: Configurar Amazon Bedrock
Defina o modelo e a região AWS no arquivo application.properties:
spring.ai.bedrock.aws.region=us-east-1
spring.ai.bedrock.converse.chat.options.model=global.anthropic.claude-sonnet-4-5-20250929-v1:0Passo 4: Testar Localmente
Inicie a aplicação e envie uma requisição:
mvn spring-boot:run
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "What is Spring AI?"}'Pronto: um agente compatível com AgentCore completo, sem controladores customizados, sem manipulação de protocolo, sem implementação manual de verificação de saúde.
Passo 5: Adicionar Streaming de Respostas
Para fazer o agente transmitir respostas conforme são geradas, altere o tipo de retorno para Flux<String>. O SDK muda automaticamente para saída SSE:
@AgentCoreInvocation
public Flux<String> streamingChat(PromptRequest request) {
return chatClient.prompt()
.user(request.prompt())
.stream()
.content();
}O SDK gerencia framing SSE, headers Content-Type, preservação de quebras de linha e ciclo de vida de conexão. Seu código permanece focado apenas na lógica de IA.
Passo 6: Adicionar Memória ao Agente
Agentes reais precisam lembrar o que usuários disseram anteriormente em uma conversa (memória de curto prazo) e o que aprenderam ao longo do tempo (memória de longo prazo). O SDK integra a AgentCore Memory através do padrão de advisors do Spring AI — interceptadores que enriquecem prompts com contexto antes de alcançarem o modelo.
A memória de curto prazo mantém mensagens recentes em uma janela deslizante, enquanto a memória de longo prazo persiste conhecimento entre sessões usando quatro estratégias: Semântica (informações factuais sobre usuários), Preferência do Usuário (configurações e escolhas explícitas), Resumo (histórico de conversa condensado) e Episódica (interações passadas e lições aprendidas). O AgentCore consolida essas estratégias de forma assíncrona, extraindo informações relevantes sem intervenção manual do desenvolvedor.
Adicione a dependência de memória e ative a auto-descoberta. No modo auto-descoberta, o SDK detecta automaticamente estratégias de memória de longo prazo disponíveis e namespaces sem configuração manual:
agentcore.memory.memory-id=${AGENTCORE_MEMORY_ID}
agentcore.memory.long-term.auto-discovery=trueDepois, injete AgentCoreMemory e componha-o no cliente de chat:
private final AgentCoreMemory agentCoreMemory;
public MyAgent(ChatClient.Builder builder, AgentCoreMemory agentCoreMemory) {
this.agentCoreMemory = agentCoreMemory;
this.chatClient = builder.build();
}
@AgentCoreInvocation
public String chat(PromptRequest request, AgentCoreContext context) {
String sessionId = context.getHeader(AgentCoreHeaders.SESSION_ID);
return chatClient.prompt()
.user(request.prompt())
.advisors(agentCoreMemory.advisors)
.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "user:" + sessionId))
.call()
.content();
}Passo 7: Estender Agentes com Ferramentas
O AgentCore oferece ferramentas especializadas que o SDK expõe como callbacks de ferramenta do Spring AI através da interface ToolCallbackProvider.
Automação de navegador: Agentes conseguem navegar em websites, extrair conteúdo, capturar telas e interagir com elementos da página usando o AgentCore Browser:
<dependency>
<groupId>org.springaicommunity</groupId>
<artifactId>spring-ai-agentcore-browser</artifactId>
</dependency>Interpretador de código: Agentes conseguem escrever e executar Python, JavaScript ou TypeScript em um sandbox seguro usando o AgentCore Code Interpreter. O sandbox inclui numpy, pandas e matplotlib. Arquivos gerados são capturados através do artifact store:
<dependency>
<groupId>org.springaicommunity</groupId>
<artifactId>spring-ai-agentcore-code-interpreter</artifactId>
</dependency>Ambas as ferramentas se integram através da interface ToolCallbackProvider do Spring AI. Aqui está o MyAgent final com memória, navegador e interpretador de código compostos em conjunto:
@Service
public class MyAgent {
private final ChatClient chatClient;
private final AgentCoreMemory agentCoreMemory;
public MyAgent(
ChatClient.Builder builder,
AgentCoreMemory agentCoreMemory,
@Qualifier("browserToolCallbackProvider") ToolCallbackProvider browserTools,
@Qualifier("codeInterpreterToolCallbackProvider") ToolCallbackProvider codeInterpreterTools) {
this.agentCoreMemory = agentCoreMemory;
this.chatClient = builder
.defaultToolCallbacks(browserTools, codeInterpreterTools)
.build();
}
@AgentCoreInvocation
public Flux<String> chat(PromptRequest request, AgentCoreContext context) {
String sessionId = context.getHeader(AgentCoreHeaders.SESSION_ID);
return chatClient.prompt()
.user(request.prompt())
.advisors(agentCoreMemory.advisors)
.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "user:" + sessionId))
.stream()
.content();
}
}O modelo vê todas as ferramentas igualmente e decide qual usar baseado na requisição do usuário. Embora este artigo focalize Amazon Bedrock para acessar modelos de fundação, o Spring AI suporta múltiplos provedores LLM (Large Language Model), incluindo OpenAI e Anthropic, permitindo que você escolha os modelos que melhor se adequam às suas necessidades.
Implantação do Agente
O SDK suporta dois modelos de implantação:
AgentCore Runtime: Para infraestrutura totalmente gerenciada, empacote sua aplicação como container ARM64, envie-a para o Amazon Elastic Container Registry (Amazon ECR), e crie um AgentCore Runtime que referencie a imagem. O runtime gerencia escalabilidade e monitoramento de saúde. O diretório examples/terraform fornece infraestrutura como código com opções de autenticação IAM e OAuth2.
Implantação autônoma: Use módulos AgentCore de Memory, Browser ou Code Interpreter em aplicações rodando em Amazon EKS, Amazon ECS, Amazon EC2 ou on-premises. Com essa abordagem, equipes conseguem adotar capacidades AgentCore incrementalmente — por exemplo, adicionando memória a um serviço Spring Boot existente antes de migrar para o AgentCore Runtime posteriormente.
Autenticação, Autorização e Ferramentas Corporativas
O AgentCore Runtime suporta dois métodos de autenticação: SigV4 baseado em IAM para chamadas serviço-a-serviço AWS e OAuth2 para aplicações voltadas para usuários. Quando seu agente Spring AI é implantado no AgentCore Runtime, autenticação é gerenciada na camada de infraestrutura. Sua aplicação recebe a identidade do usuário autenticado através do AgentCoreContext, permitindo que autorização de granularidade fina seja implementada usando padrões Spring Security convencionais.
Para implantações autônomas, sua aplicação Spring é responsável por fornecer autenticação e autorização usando Spring Security. Nesse caso, chamadas para serviços AgentCore são protegidas usando mecanismos padrão de credencial do AWS SDK.
Agentes Spring AI conseguem acessar ferramentas corporativas através do AgentCore Gateway, que fornece suporte para Model Context Protocol (MCP) com autenticação de saída e registro semântico de ferramentas. Para usar o Gateway, configure seu endpoint MCP client para apontar ao AgentCore Gateway e autentique usando SigV4 IAM ou OAuth2, permitindo que agentes descubram e invoquem ferramentas corporativas enquanto o Gateway gerencia credenciais para serviços downstream.
Próximos Passos e Recursos
O SDK continua evoluindo. Integrações futuras incluem suporte a observabilidade com integração de tracing, métricas e logging do Spring AI, além de suporte a ferramentas externas como LangFuse, Datadog e Dynatrace usando OpenTelemetry. Também estão planejados frameworks de testes e avaliação de qualidade para respostas de agentes, e gerenciamento de identidade avançado.
Para começar:
- Explore o SDK Spring AI AgentCore SDK on GitHub. O repositório inclui aplicações de exemplo que você pode usar como ponto de partida.
- Leia a documentação Amazon AgentCore para detalhes sobre Runtime, Memory, Browser e serviços Code Interpreter.
- Experimente o console Amazon Bedrock para habilitar acesso a modelos e explorar modelos de fundação disponíveis.
- Para um aprofundamento prático, tente o workshop Building Java AI agents with Spring AI and Amazon AgentCore. Em cerca de quatro horas, você constrói um assistente completo de gerenciamento de viagens e despesas, adicionando progressivamente persona, memória, recuperação de conhecimento, navegação web, execução de código, integração de ferramentas MCP e implanta sem servidor no AgentCore Runtime com autenticação e observabilidade. Nenhuma experiência prévia em IA/ML é necessária.
A comunidade é bem-vinda para contribuir. Deixe um comentário para compartilhar sua experiência ou abra uma issue no GitHub repository.
Fonte
Spring AI SDK for Amazon Bedrock AgentCore is now Generally Available (https://aws.amazon.com/blogs/machine-learning/spring-ai-sdk-for-amazon-bedrock-agentcore-is-now-generally-available/)
Leave a Reply