Como Integrar o Amazon Bedrock AgentCore com Slack: Guia Prático com AWS CDK

Visão geral da integração entre Amazon Bedrock AgentCore e Slack

Integrar o Amazon Bedrock AgentCore ao Slack permite que equipes acessem agentes de IA diretamente em seu ambiente de trabalho, sem a necessidade de alternar entre aplicativos, perder o histórico de conversas ou se reautenticar. Essa integração aborda três desafios técnicos principais: validação segura dos eventos do Slack, manutenção do contexto das conversas em threads e gerenciamento de respostas que ultrapassam o limite de timeout do Slack.

O uso do AWS Cloud Development Kit (AWS CDK) simplifica a implantação da infraestrutura necessária, composta por funções AWS Lambda especializadas, Amazon API Gateway, Amazon Simple Queue Service (SQS) e AWS Secrets Manager, garantindo uma arquitetura serverless escalável e segura.

Componentes da solução e arquitetura

A solução é dividida em três seções principais:

• Construção da imagem do agente: Utiliza AWS CodeBuild para criar imagens containerizadas otimizadas para AWS Graviton (ARM64), armazenadas no Amazon Elastic Container Registry (ECR).
• Componentes do AgentCore: Implementa o AgentCore Runtime, Gateway e Memory, utilizando o Strands Agents SDK para orquestrar invocações de modelos, chamadas a ferramentas e gerenciamento do histórico de conversas.
• Infraestrutura de integração com Slack: Composta por API Gateway, Secrets Manager, três funções Lambda e SQS para validação, enfileiramento e processamento assíncrono das mensagens do Slack.

O fluxo de requisição funciona da seguinte forma: o usuário envia uma mensagem no Slack; o Slack encaminha um webhook ao API Gateway; a função Lambda de verificação valida a requisição usando segredos armazenados no Secrets Manager; após a verificação, a mensagem é colocada na fila SQS e processada pela função Lambda de integração com o AgentCore, que consulta o histórico da conversa, invoca o modelo Amazon Bedrock Nova Pro e retorna a resposta atualizada ao Slack.

Pré-requisitos para implantação

• Conta AWS com permissões para Amazon Bedrock AgentCore, Lambda, API Gateway, SQS, ECR, CodeBuild, IAM e Secrets Manager.
• AWS CLI v2 configurado com credenciais.
• Node.js v18 ou superior e npm instalados.
• AWS CDK instalado e configurado (comando npm install -g aws-cdk e cdk bootstrap).
• Conta Slack com permissões para criar apps ou acesso a workspace sandbox para testes.

Passo a passo para criar a integração

1. Criar um app no Slack

1. Acesse Slack API e clique em “Create New App”.
2. Escolha “From scratch”, defina o nome “agent-core-weather-agent” e selecione o workspace.
3. Em “OAuth & Permissions”, adicione as seguintes permissões ao Bot Token Scopes: app_mentions:read, chat:write, im:history, im:read, im:write.
4. Instale o app no workspace e copie o “Bot User OAuth Token” e o “Signing Secret” para uso posterior.
5. Em “App Home”, habilite o envio de comandos Slash e mensagens na aba de mensagens.

2. Implantar a infraestrutura com AWS CDK

Clone o repositório oficial do GitHub:

git clone https://github.com/aws-samples/sample-Integrating-Amazon-Bedrock-AgentCore-with-Slack
cd sample-Integrating-Amazon-Bedrock-AgentCore-with-Slack

Configure as variáveis de ambiente com as credenciais do Slack:

export SLACK_BOT_TOKEN="xoxb-seu-token-aqui"
export SLACK_SIGNING_SECRET="seu-signing-secret-aqui"

Execute o script de deploy:

./deploy.sh

Essa etapa cria três stacks CDK e pode levar de 10 a 15 minutos. Ao final, será exibida a URL do webhook necessária para a configuração no Slack.

3. Configurar assinaturas de eventos no Slack

1. Retorne ao app no Slack API e acesse “Event Subscriptions”.
2. Ative “Enable Events” e cole a URL do webhook fornecida pela implantação no campo “Request URL”. Aguarde a verificação com o ícone verde.
3. Em “Subscribe to bot events”, adicione os eventos app_mention e im.
4. Salve as alterações e reinstale o app no workspace para ativar as permissões.

4. Testar a integração no Slack

Localize o app “agent-core-weather-agent” na seção de Apps do Slack. Você pode convidar o app para um canal com o comando /invite @agent-core-weather-agent ou interagir via mensagem direta.

Exemplo de comando: “What’s the weather in Dallas today”. O app responde inicialmente com “Processing your request…” e, após o processamento pelo AgentCore, atualiza a mensagem com a resposta do agente.

O histórico da conversa é mantido graças ao AgentCore Memory, permitindo continuidade sem repetição de contexto.

Detalhes técnicos da integração

Gerenciamento de sessões e contexto

O AgentCore utiliza o timestamp da thread do Slack como session ID e o ID do usuário como actor ID para identificar e manter o histórico da conversa. Essa abordagem elimina a necessidade de gerenciamento externo de estado e isola conversas em threads distintas.

Processamento assíncrono para respeitar timeout do Slack

Como as respostas do agente podem ultrapassar o limite de 3 segundos do Slack para webhooks, a arquitetura usa três funções Lambda:

• Verification Lambda: valida a assinatura do Slack e responde imediatamente.
• SQS Integration Lambda: filtra eventos e coloca as mensagens na fila SQS.
• Agent Integration Lambda: processa a fila, invoca o AgentCore e atualiza as mensagens no Slack.

Comunicação segura e acesso a ferramentas

O AgentCore Gateway utiliza autenticação AWS Signature Version 4 (SigV4) para comunicação segura e o protocolo Model Context Protocol (MCP) para invocar ferramentas, como o agente de clima usado no exemplo.

É possível estender o modelo para permitir autenticação individual de usuários via Identity Provider (IdP), embora essa funcionalidade não seja abordada neste tutorial.

Personalização e reutilização da solução

A camada de integração Slack pode ser reaproveitada para diferentes agentes construídos com AgentCore. Basta substituir as ferramentas do agente no stack AgentCore para adaptá-lo a outras necessidades de negócio, mantendo o gerenciamento de memória e padrões de comunicação.

Limpeza e remoção dos recursos

Para remover todos os recursos criados, execute o script:

./cleanup.sh

Links úteis para aprofundamento

• Repositório GitHub da solução
• Documentação Amazon Bedrock AgentCore
• Guia AWS CDK
• Documentação Slack API
• Amazon API Gateway