sidekick

An AI-powered Slack (and Cursor) companion that helps developers discover existing internal tools, avoid duplication, and seamlessly request and launch new initiatives through a lightweight, guided workflow.

Built on AWS Bedrock AgentCore, using Strands Agents and the AG-UI Protocol.

---

Quick Start

Prerequisites

Tool	Version	Install
Python	3.12+	brew install python@3.12 or pyenv
uv	latest	curl -LsSf https://astral.sh/uv/install.sh | sh
AWS CLI	v2	Install guide
AgentCore CLI	latest	pip3 install bedrock-agentcore-starter-toolkit

Setup

# Create virtual environment
uv venv
source .venv/bin/activate

# Install dependencies (agent)
uv pip install -r agent/requirements.txt

# Copy environment template and configure the ENVs
cp agent/.env.example agent/.env

Configure AWS Credentials

You need AWS credentials with access to Amazon Bedrock.

okta-awscli --profile production --okta-profile production

Verify access:

aws bedrock list-foundation-models --region us-east-1 --query "modelSummaries[?contains(modelId, 'claude')]" | head -5

Run Locally

make run_local

This starts the AgentCore dev server on port 8080.

---

Features

• AG-UI Protocol: Streaming responses compatible with CopilotKit and other AG-UI frontends

• AgentCore Memory: Persistent conversation context across sessions

• Bedrock Guardrails: Content safety, PII protection, topic boundaries

• MCP Tool Integration: Connect to external services via Model Context Protocol

• Terraform Infrastructure: Ready-to-deploy IaC for AgentCore resources

• Docker Support: Containerized deployment

---

Environment Variables

Variable	Required	Description
AWS_REGION	Yes	AWS region (default: us-east-1)
BEDROCK_GUARDRAIL_ID	Recommended	Guardrail ID for content safety
BEDROCK_GUARDRAIL_VERSION	Recommended	Guardrail version (default: DRAFT)
BEDROCK_AGENTCORE_MEMORY_ID	Optional	AgentCore Memory resource ID
LOCAL_SESSION_CACHE	Optional	Set to true for in-process session caching (local dev)

---

Invoking the Agent

Local Development

# Start the local server first (in another terminal)
make run_local

# Then invoke the agent
make invoke env=dev prompt="Hello!"

# Or with a custom port
make invoke env=dev port=8081 prompt="Hello!"

Deployed Agent

make invoke env=staging prompt="Hello!"

# With session ID for conversation continuity
SESSION_ID='my-session' make invoke env=staging prompt="Tell me more"

---

Project Structure

├── agent/                   # Main sidekick agent (Bedrock AgentCore)
│   ├── src/
│   │   ├── main.py          # Agent entrypoint (AG-UI protocol)
│   │   ├── prompts.py       # System prompt
│   │   ├── model.py         # Bedrock model configuration
│   │   ├── mcp_client/      # MCP client integration
│   │   └── tools/           # Custom tools
│   ├── tests/               # Python unit tests
│   ├── Dockerfile           # Container image
│   └── requirements.txt
├── sidekick-slack-bot/      # Slack bot (Bolt Lambda)
├── agent/scripts/
│   └── invoke_agentcore_curl.py  # Dev tool: invoke agent via SigV4
├── infra/terraform/         # Infrastructure as Code
├── Makefile                 # Development commands
└── Makefile_ci_cd           # CI/CD build targets

---

Customizing Your Agent

1. Update the System Prompt

Edit agent/src/prompts.py to define your agent's persona and capabilities.

2. Add Custom Tools

Create tools in agent/src/tools/ using the @tool decorator:

from strands import tool

@tool
def my_custom_tool(param: str) -> str:
    """Tool description for the LLM."""
    return f"Result: {param}"

Register tools in agent/src/main.py.

3. Connect MCP Servers

Use agent/src/mcp_client/ as a reference for connecting to MCP servers. The template shows how to:

• Authenticate with external services
• Load tools dynamically
• Manage client lifecycle

4. Configure Infrastructure

Update infra/terraform/ for your deployment:

• Agent name and environment
• Memory configuration
• IAM policies

---

Deployment

Deployment is handled by Control Monkey / Terraform. GitHub Actions builds and publishes images; Control Monkey manages deployment.

Local Docker Testing

# Build
make docker_build

# Run locally
make docker_run_local

---

Guardrails

Bedrock Guardrails enforce content safety, PII protection, and topic boundaries.

Create/Update Guardrails

# Create a new guardrail
make guardrail_create

# Update existing guardrail
make guardrail_update ENV=staging

Configure

export BEDROCK_GUARDRAIL_ID=your-guardrail-id
export BEDROCK_GUARDRAIL_VERSION=1  # or DRAFT for development

---

Troubleshooting

AWS credentials issues

aws sts get-caller-identity
aws bedrock list-foundation-models --region us-east-1

Memory not working

• For local dev: Set LOCAL_SESSION_CACHE=true for in-process caching
• For deployed: Ensure BEDROCK_AGENTCORE_MEMORY_ID points to a valid Memory resource

---

Make Commands

Command	Description
make run_local	Start local dev server
make lint	Run ruff linter and formatter
make docker_build	Build Docker image
make docker_run_local	Run container locally
make deploy	(Deployment via Control Monkey / Terraform)
make invoke env=x prompt="..."	Invoke deployed agent
make guardrail_create	Create new guardrail
make guardrail_update	Update guardrail

---

Keeping Up to Date

This project was generated from a Cruft template. To update with the latest template changes:

cruft update