rapp-brainstem

name rapp-brainstem version 1.0.0 description Install and configure RAPP Brainstem -- a local-first AI agent server powered by GitHub Copilot. homepage https://microsoft.github.io/aibast-agents-library/ metadata {"emoji":"","category":"ai-agents","repo":"https://github.com/microsoft/aibast-agents-library"} RAPP Brainstem A local-first AI agent server. No API keys. No cloud setup. Just a GitHub account. The brainstem teaches you the Microsoft AI stack one layer at a time: Tier Metaphor What it does Brainstem Survival basics Local agent server -- soul, tools, conversation Spinal Cord Cloud body Deploy to Azure -- always-on, persistent storage Nervous System Enterprise reach Copilot Studio -- Teams, M365 Copilot Each tier builds on the last. Start with Tier 1. Layer up when the user is ready. Instructions for Copilot Execute these steps autonomously. Only pause and ask the user when marked with . After completing each tier, tell the user what they just learned and offer the next tier. Do not proceed to the next tier unless the user asks. Tier 1: The Brainstem The biological brainstem keeps you alive -- breathing, heartbeat, reflexes. This tier does the same for your AI: it runs the core agent loop, calls tools, and responds. Everything else builds on top of this. Step 1: Check the Environment Detect the OS and check what's already installed: uname -s python3 --version 2>/dev/null || python --version 2>/dev/null git --version 2>/dev/null gh --version 2>/dev/null On Windows , skip all manual prereq checks -- the PowerShell installer handles everything automatically: irm https://raw.githubusercontent.com/microsoft/aibast-agents-library/main/install.ps1 | iex It auto-installs Python 3.11, Git, and GitHub CLI via winget on a factory Windows 11 PC. If the user is on Windows and runs this, skip to Step 2 after it completes. If Python 3.11+ is missing (macOS/Linux): macOS: brew install python@3.11 Ubuntu/Debian: sudo apt install python3.11 python3-pip If git is missing : macOS: xcode-select --install Ubuntu/Debian: sudo apt install git If gh (GitHub CLI) is missing , install it: macOS: brew install gh Ubuntu/Debian: sudo apt install gh Windows: winget install GitHub.cli Step 2: GitHub Authentication Tell the user: ** The brainstem uses your GitHub Copilot subscription as its AI engine -- no API keys needed.** Run this to authenticate: gh auth login Let me know when you're signed in. After they confirm, verify: gh auth token >/dev/null 2>&1 && echo "yes authenticated" || echo "no not authenticated" Step 3: Install the Brainstem git clone https://github.com/microsoft/aibast-agents-library.git ~/.brainstem/src 2>/dev/null || ( cd ~/.brainstem/src && git pull) cd ~/.brainstem/src/rapp_brainstem pip3 install -r requirements.txt -q Create the CLI wrapper: mkdir -p ~/.local/bin cat > ~/.local/bin/brainstem << 'WRAPPER' #!/bin/bash cd ~/.brainstem/src/rapp_brainstem exec python3 brainstem.py " $@ " WRAPPER chmod +x ~/.local/bin/brainstem Make sure ~/.local/bin is in PATH: echo $PATH | grep -q '.local/bin' || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc Create .env from example if it doesn't exist: cd ~/.brainstem/src/rapp_brainstem [ -f . env ] || cp .env.example . env Step 4: Start and Verify Start the brainstem: cd ~/.brainstem/src/rapp_brainstem && python3 brainstem.py & sleep 3 Health check: curl -s http://localhost:7071/health Expected response contains "status": "ok" with model and agent info. Test a conversation: curl -s -X POST http://localhost:7071/chat \ -H "Content-Type: application/json" \ -d '{"user_input": "Hello! What can you do?"}' | python3 -m json.tool Step 5: Tier 1 Complete Tell the user: ** Your brainstem is alive!** Open http://localhost:7071 in your browser for the chat UI. What you just set up: A local AI agent server with tool-calling and conversation GitHub Copilot powers the AI -- no API keys, no monthly bills Agents auto-discovered from the agents/ folder Soul file ( soul.md ) defines the personality Try these next: Edit ~/.brainstem/src/rapp_brainstem/soul.md to change the personality Look at agents/hello_agent.py as a template for your own agents Open the Sources panel in the chat UI to connect remote agent repos When you're ready to give this a cloud body, say "deploy to Azure" and I'll walk you through Tier 2. Save the install state for future reference: mkdir -p ~/.config/brainstem cat > ~/.config/brainstem/state.json << 'STATE' { "tier" : 1, "install_dir" : "~/.brainstem/src/rapp_brainstem" , "local_url" : "http://localhost:7071" , "status" : "running" } STATE Do not proceed to Tier 2 unless the user asks. Tier 2: The Spinal Cord The spinal cord connects your brainstem to the rest of your body. Deploying to Azure does the same -- your agent is now always-on, reachable from anywhere, with persistent storage and monitoring. Only run this tier if the user asks to deploy to Azure. Step 6: Check Azure Prerequisites az --version 2>/dev/null | head -1 func --version 2>/dev/null If Azure CLI is missing: macOS: brew install azure-cli Ubuntu/Debian: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash Windows: winget install Microsoft.AzureCLI If Azure Functions Core Tools is missing: npm install -g azure-functions-core-tools@4 --unsafe-perm true Step 7: Azure Authentication Tell the user: ** Let's give your brainstem a cloud body.** Run az login and complete the browser authentication. Let me know when you're done. After they confirm: az account show --query "{subscription:name, id:id}" -o table If they have multiple subscriptions, list them and ask which one: az account list --query "[].{Name:name, ID:id, Default:isDefault}" -o table Set the chosen subscription: az account set --subscription "CHOSEN_SUBSCRIPTION_ID" Step 8: Deploy Azure Resources Generate unique names and deploy: SUFFIX=$(openssl rand -hex 4) RESOURCE_GROUP= "brainstem-rg- ${SUFFIX} " LOCATION= "eastus2" az group create --name $RESOURCE_GROUP --location $LOCATION -o none az deployment group create \ --resource-group $RESOURCE_GROUP \ --template-uri https://raw.githubusercontent.com/microsoft/aibast-agents-library/main/azuredeploy.json \ --parameters openAILocation=swedencentral \ -o none This creates: Function App (Python 3.11), Azure OpenAI (GPT-4o), Storage Account, Application Insights. All using Entra ID auth -- no API keys. Get the resource names: FUNC_NAME=$(az functionapp list -g $RESOURCE_GROUP --query "[0].name" -o tsv) STORAGE_NAME=$(az storage account list -g $RESOURCE_GROUP --query "[0].name" -o tsv) OPENAI_NAME=$(az cognitiveservices account list -g $RESOURCE_GROUP --query "[0].name" -o tsv) SUBSCRIPTION_ID=$(az account show --query id -o tsv) Step 9: Assign RBAC Roles USER_ID=$(az ad signed-in-user show --query id -o tsv) # Storage roles for local development az role assignment create --assignee $USER_ID \ --role "Storage Blob Data Contributor" \ --scope "/subscriptions/ ${SUBSCRIPTION_ID} /resourceGroups/ ${RESOURCE_GROUP} /providers/Microsoft.Storage/storageAccounts/ ${STORAGE_NAME} " -o none az role assignment create --assignee $USER_ID \ --role "Storage File Data Privileged Contributor" \ --scope "/subscriptions/ ${SUBSCRIPTION_ID} /resourceGroups/ ${RESOURCE_GROUP} /providers/Microsoft.Storage/storageAccounts/ ${STORAGE_NAME} " -o none # OpenAI role az role assignment create --assignee $USER_ID \ --role "Cognitive Services OpenAI User" \ --scope "/subscriptions/ ${SUBSCRIPTION_ID} /resourceGroups/ ${RESOURCE_GROUP} /providers/Microsoft.CognitiveServices/accounts/ ${OPENAI_NAME} " -o none # Function App identity + roles FUNC_IDENTITY=$(az functionapp identity assign --name $FUNC_NAME --resource-group $RESOURCE_GROUP --query principalId -o tsv) az role assignment create --assignee $FUNC_IDENTITY \ --role "Storage Blob Data Contributor" \ --scope "/subscriptions/ ${SUBSCRIPTION_ID} /resourceGroups/ ${RESOURCE_GROUP} /providers/Microsoft.Storage/storageAccounts/ ${STORAGE_NAME} " -o none az role assignment create --assignee $FUNC_IDENTITY \ --role "Storage File Data Privileged Contributor" \ --scope "/subscriptions/ ${SUBSCRIPTION_ID} /resourceGroups/ ${RESOURCE_GROUP} /providers/Microsoft.Storage/storageAccounts/ ${STORAGE_NAME} " -o none az role assignment create --assignee $FUNC_IDENTITY \ --role "Cognitive Services OpenAI User" \ --scope "/subscriptions/ ${SUBSCRIPTION_ID} /resourceGroups/ ${RESOURCE_GROUP} /providers/Microsoft.CognitiveServices/accounts/ ${OPENAI_NAME} " -o none Step 10: Deploy the Function cd ~/.brainstem/src/rapp_brainstem func azure functionapp publish $FUNC_NAME --build remote Wait for deployment (1-3 minutes). Then verify: FUNC_KEY=$(az functionapp keys list --name $FUNC_NAME --resource-group $RESOURCE_GROUP --query "functionKeys.default" -o tsv) FUNC_URL= "https:// ${FUNC_NAME} .azurewebsites.net/api/businessinsightbot_function" curl -s -X POST " ${FUNC_URL} ?code= ${FUNC_KEY} " \ -H "Content-Type: application/json" \ -d '{"user_input": "Hello", "conversation_history": []}' | python3 -m json.tool If the functions list is empty after deploy: az functionapp restart --name $FUNC_NAME --resource-group $RESOURCE_GROUP Step 11: Tier 2 Complete Save the Azure state: cat > ~/.config/brainstem/state.json << AZSTATE { "tier": 2, "install_dir": "~/.brainstem/src/rapp_brainstem", "local_url": "http://localhost:7071", "azure": { "resource_group": "${RESOURCE_GROUP}", "function_app": "${FUNC_NAME}", "function_url": "${FUNC_URL}", "storage_account": "${STORAGE_NAME}", "openai_service": "${OPENAI_NAME}" }, "status": "deployed" } AZSTATE Tell the user: ** Spinal cord connected!** Your brainstem is deployed to Azure. Azure endpoint: https://${FUNC_NAME}.azurewebsites.net Resources created: Resource Name Resource Group ${RESOURCE_GROUP} Function App ${FUNC_NAME} Storage Account ${STORAGE_NAME} Azure OpenAI ${OPENAI_NAME} What you just learned: ARM template deployment Azure Functions with Python Managed identity and RBAC (no API keys!) Azure OpenAI service provisioning When you're ready to connect this to Teams and M365 Copilot, say "connect to Copilot Studio" and I'll walk you through Tier 3. Do not proceed to Tier 3 unless the user asks. Tier 3: The Nervous System Your nervous system extends your brain's reach everywhere -- eyes, ears, hands. Copilot Studio does the same: it connects your agent to Teams, M365 Copilot, and across your organization. The same logic you tested locally now serves your entire tenant. Only run this tier if the user asks to connect to Copilot Studio. Step 12: Import the Power Platform Solution Tell the user: ** Let's give your brainstem a nervous system -- connecting it to Teams and M365 Copilot.** The repo includes a Power Platform solution that creates a declarative agent in Copilot Studio wired to your Azure Function. To import: