How aws-samples/sample-remote-swe-agents works
Main Components
• AWS Infrastructure (defined in the “cdk” directory)
– CDK constructs for provisioning AWS resources:
• Lambda functions (for handling incoming Slack webhooks)
• API Gateway (receiving requests from Slack and routing them to Lambdas)
• AppSync Events for event distribution
• DynamoDB (storing message history, job statuses, etc.)
• EC2 resources (worker units including dedicated EC2 instances and attached EBS volumes)
– Also, SSM Parameter Store is used to configure secrets (Slack tokens, GitHub tokens, etc.)
• Slack Bolt App (located in the “slack-bolt-app” directory)
– This handles the Slack App functionality and user interactions
– It translates incoming Slack messages and directs them into the AWS-driven workflow
• Worker Software Development Agents (located in the “worker” folder)
– These represent the autonomous agents that process tasks, execute commands, and interact with GitHub and other services
– Includes tools for command execution, repository management, and integration with MCP servers
• GitHub Integration
– Either via a Personal Access Token or a GitHub App (as documented)
– Configured via environment variables and SSM parameters to securely link GitHub with the AWS infrastructure
Relationships and Interactions
• The Slack Workflow:
– A Slack user sends a message via the Slack client.
– The Slack app (Slack Bolt App) receives the message via a webhook.
– API Gateway accepts the webhook and forwards it to a Lambda function.
– The Lambda function publishes events to AppSync; meanwhile, message history is logged in DynamoDB.
• The Worker System:
– When a new session (or Slack thread) is initiated, the Worker Manager (defined in CDK constructs and implemented in the “worker” project) is notified.
– It provisions a dedicated Worker Unit (EC2 instance with EBS) that subscribes to AppSync events.
– The Worker Unit processes the task (e.g., handling a code feature/bug request) and ultimately pushes status updates or replies back to the Slack channel.
• GitHub Integration:
– The agent interacts with GitHub (through either a PAT or a GitHub App) to perform repository operations, create and link issues, and manage pull requests as described in README.
• MCP Integration:
– Optional integration with MCP servers is configured (via the “claude_desktop_config.json” in the worker directory) and can be represented as an external service used by agents.
Architectural Patterns & Design Principles
• Serverless & Event-Driven:
– Lambda functions and AppSync events highlight an event-driven architecture to handle incoming Slack events and associated actions.
• Modular Infrastructure as Code:
– The use of AWS CDK is modular. The “cdk/lib/constructs” folder shows dedicated modules for EC2 worker units, Slack Bolt, storage, and more.
• Separation of Concerns:
– The project is split into discrete parts: infrastructure (cdk), Slack app logic (slack-bolt-app), and worker processing (worker).
• Secure & Configurable:
– Secrets and tokens are managed via SSM Parameter Store. Environment variables (e.g., for GitHub App and Slack restrictions) provide runtime configurability.
• Then, incorporate the detailed internal components from the CDK configuration:
– Show how the infrastructure deploys serverless functions (API Gateway and Lambda) that bridge Slack and worker management.
– Indicate the flow of events (from Slack message reception, logging in DynamoDB, to assignment to worker units).
• Configuration and integration points:
– Mark where environment configuration, SSM parameters, and GitHub integration feed into the system.
– Include any security aspects such as restricted Slack user access.
– Clear labels for every component and sub-component.