diff --git a/.github/workflows/shared/mcp/amplifier.md b/.github/workflows/shared/mcp/amplifier.md new file mode 100644 index 0000000000..e64b03c0a8 --- /dev/null +++ b/.github/workflows/shared/mcp/amplifier.md @@ -0,0 +1,267 @@ +--- +# Amplifier - AI-powered modular development assistant +# Microsoft's research-based AI CLI with extensible modules and specialized agents +# +# Documentation: https://github.com/microsoft/amplifier +# Official Docs: https://microsoft.github.io/amplifier-docs/ +# +# This shared workflow provides: +# - Automatic amplifier installation via uv tool +# - Bash tool access for running amplifier commands +# - Configuration for AI provider credentials (Anthropic, OpenAI, Azure OpenAI, Ollama) +# +# Available agents: +# - zen-architect: System design with ruthless simplicity +# - bug-hunter: Systematic debugging +# - web-research: Web research and content fetching +# - explorer: Breadth-first exploration of local code with summaries +# - modular-builder: Code implementation +# +# Usage: +# imports: +# - shared/mcp/amplifier.md + +tools: + bash: + - "amplifier *" + - "uv *" + +steps: + - name: Install UV package manager + id: setup-uv + run: | + if ! command -v uv &> /dev/null; then + echo "Installing UV package manager..." + curl -LsSf https://astral.sh/uv/install.sh | sh + export PATH="$HOME/.cargo/bin:$PATH" + echo "$HOME/.cargo/bin" >> $GITHUB_PATH + fi + uv --version + echo "UV package manager is ready" + + - name: Install Amplifier + id: setup-amplifier + run: | + echo "Installing Amplifier from GitHub..." + uv tool install git+https://github.com/microsoft/amplifier + export PATH="$HOME/.local/bin:$PATH" + echo "$HOME/.local/bin" >> $GITHUB_PATH + amplifier --version || echo "Amplifier installed (version check not available)" + echo "Amplifier is ready" + mkdir -p /tmp/gh-aw/amplifier + + - name: Configure Amplifier Provider + id: configure-amplifier + run: | + # Check which AI provider credentials are available + if [ -n "$ANTHROPIC_API_KEY" ]; then + echo "Anthropic credentials detected" + export AMPLIFIER_PROVIDER="anthropic" + elif [ -n "$OPENAI_API_KEY" ]; then + echo "OpenAI credentials detected" + export AMPLIFIER_PROVIDER="openai" + elif [ -n "$AZURE_OPENAI_ENDPOINT" ]; then + echo "Azure OpenAI credentials detected" + export AMPLIFIER_PROVIDER="azure-openai" + else + echo "No AI provider credentials detected. Amplifier will require configuration." + echo "To use Amplifier, configure one of the following secrets:" + echo " - ANTHROPIC_API_KEY (recommended)" + echo " - OPENAI_API_KEY" + echo " - AZURE_OPENAI_ENDPOINT with AZURE_OPENAI_API_KEY" + fi + + # Create amplifier config directory if it doesn't exist + mkdir -p ~/.config/amplifier + + echo "Amplifier provider configuration complete" + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }} + AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} +--- + +# Amplifier Usage Guide + +Microsoft Amplifier is an AI-powered modular development assistant with specialized agents for different tasks. It has been installed and is available via the `amplifier` command. + +A temporary folder `/tmp/gh-aw/amplifier` is available for caching intermediate results. + +## Configuration + +Amplifier supports multiple AI providers. Configure your preferred provider using repository secrets: + +### Anthropic Claude (Recommended) +```yaml +secrets: + ANTHROPIC_API_KEY: your-api-key +``` +Get an API key at: https://console.anthropic.com/settings/keys + +### OpenAI +```yaml +secrets: + OPENAI_API_KEY: your-api-key +``` +Get an API key at: https://platform.openai.com/api-keys + +### Azure OpenAI (Enterprise) +```yaml +secrets: + AZURE_OPENAI_ENDPOINT: https://your-resource.openai.azure.com/ + AZURE_OPENAI_API_KEY: your-api-key + # Or use Azure CLI authentication with managed identity +``` + +### Ollama (Local, Free) +No API key required. Make sure Ollama is running: +```bash +ollama serve +ollama pull llama3 +``` + +## Common Amplifier Operations + +### Initialize Amplifier +```bash +# First-time setup wizard (auto-detects missing config) +amplifier init + +# Or configure programmatically +amplifier provider use anthropic --model claude-sonnet-4-5 +# or +amplifier provider use openai --model gpt-5.2 +``` + +### Single Command Execution +```bash +# Get quick answers +amplifier run "Explain async/await in Python" + +# Generate code +amplifier run "Create a REST API for a todo app with FastAPI" + +# Debug issues +amplifier run "Why does this code throw a TypeError: [paste code]" +``` + +### Using Specialized Agents + +Amplifier includes several specialized agents for focused tasks: + +```bash +# Use zen-architect for system design +amplifier run "Design a caching layer with careful consideration" + +# Use bug-hunter for systematic debugging +amplifier run "Use bug-hunter to debug this error: [paste error]" + +# Use explorer for code exploration +amplifier run "Use explorer to analyze the project structure" + +# Use web-research for online research +amplifier run "Use web-research to find best practices for error handling in Go" +``` + +### Working with Bundles + +Bundles provide additional capabilities: + +```bash +# Add capability bundles +amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-recipes@main +amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-design-intelligence@main + +# List available bundles +amplifier bundle list + +# Use a specific bundle +amplifier bundle use recipes + +# See current bundle +amplifier bundle current +``` + +### Sessions & Persistence + +```bash +# Resume most recent session +amplifier continue + +# Resume with new prompt +amplifier continue "follow-up question" + +# List recent sessions (current project only) +amplifier session list + +# List all sessions across all projects +amplifier session list --all-projects + +# View session details +amplifier session show + +# Resume a specific session +amplifier session resume +``` + +## Available Agents + +The **foundation** bundle (default) includes these specialized agents: + +- **zen-architect**: System design with ruthless simplicity +- **bug-hunter**: Systematic debugging and error resolution +- **web-research**: Web research and content fetching +- **explorer**: Breadth-first exploration of local code, docs, and files with citation-ready summaries +- **modular-builder**: Code implementation +- **git-ops**: Git operations and version control +- And more... + +Use `/agents` in interactive mode to see all available agents. + +## Interactive Chat Mode + +```bash +# Start a conversation +amplifier + +# In chat mode: +# - Context persists across messages +# - Use /help to see available commands +# - Use /tools, /agents, /status, /config to inspect session +# - Use /think and /do to toggle plan mode +# - Type 'exit' or Ctrl+C to quit +``` + +## Best Practices + +1. **Provider Selection**: Anthropic Claude is most tested and recommended +2. **Session Management**: Use session persistence for complex multi-step tasks +3. **Agent Delegation**: Let Amplifier choose the right agent, or specify explicitly when needed +4. **Bundles**: Start with the `foundation` bundle (default) which includes everything for development +5. **Timeouts**: Amplifier operations may take time depending on the AI provider. Ensure adequate workflow timeouts. + +## Notes + +- Amplifier is a research demonstrator in early preview +- Use with caution and careful human supervision +- Amplifier works best on macOS, Linux, and Windows Subsystem for Linux (WSL) +- Native Windows shells have known issues—use WSL unless actively contributing Windows fixes + +## More Information + +- GitHub Repository: https://github.com/microsoft/amplifier +- Documentation: https://microsoft.github.io/amplifier-docs/ +- Log Viewer (for debugging): https://github.com/microsoft/amplifier-app-log-viewer + + diff --git a/.github/workflows/test-amplifier-integration.lock.yml b/.github/workflows/test-amplifier-integration.lock.yml new file mode 100644 index 0000000000..5bda57cf80 --- /dev/null +++ b/.github/workflows/test-amplifier-integration.lock.yml @@ -0,0 +1,682 @@ +# +# ___ _ _ +# / _ \ | | (_) +# | |_| | __ _ ___ _ __ | |_ _ ___ +# | _ |/ _` |/ _ \ '_ \| __| |/ __| +# | | | | (_| | __/ | | | |_| | (__ +# \_| |_/\__, |\___|_| |_|\__|_|\___| +# __/ | +# _ _ |___/ +# | | | | / _| | +# | | | | ___ _ __ _ __| |_| | _____ ____ +# | |/\| |/ _ \ '__| |/ /| _| |/ _ \ \ /\ / / ___| +# \ /\ / (_) | | | | ( | | | | (_) \ V V /\__ \ +# \/ \/ \___/|_| |_|\_\|_| |_|\___/ \_/\_/ |___/ +# +# This file was automatically generated by gh-aw. DO NOT EDIT. +# +# To update this file, edit the corresponding .md file and run: +# gh aw compile +# For more information: https://github.com/github/gh-aw/blob/main/.github/aw/github-agentic-workflows.md +# +# Test workflow to validate Amplifier shared workflow integration +# +# Resolved workflow manifest: +# Imports: +# - shared/mcp/amplifier.md +# +# frontmatter-hash: 487d6ee8acdf3227131953a4513c23306fcb725de629981f3da1766c20c5b28a + +name: "test-amplifier-integration" +"on": + workflow_dispatch: + +permissions: {} + +concurrency: + group: "gh-aw-${{ github.workflow }}" + +run-name: "test-amplifier-integration" + +jobs: + activation: + runs-on: ubuntu-slim + permissions: + contents: read + outputs: + comment_id: "" + comment_repo: "" + steps: + - name: Checkout actions folder + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 + with: + sparse-checkout: | + actions + persist-credentials: false + - name: Setup Scripts + uses: ./actions/setup + with: + destination: /opt/gh-aw/actions + - name: Check workflow file timestamps + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + env: + GH_AW_WORKFLOW_FILE: "test-amplifier-integration.lock.yml" + with: + script: | + const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs'); + setupGlobals(core, github, context, exec, io); + const { main } = require('/opt/gh-aw/actions/check_workflow_timestamp_api.cjs'); + await main(); + + agent: + needs: activation + runs-on: ubuntu-latest + permissions: + contents: read + issues: read + pull-requests: read + concurrency: + group: "gh-aw-copilot-${{ github.workflow }}" + outputs: + checkout_pr_success: ${{ steps.checkout-pr.outputs.checkout_pr_success || 'true' }} + model: ${{ steps.generate_aw_info.outputs.model }} + secret_verification_result: ${{ steps.validate-secret.outputs.verification_result }} + steps: + - name: Checkout actions folder + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 + with: + sparse-checkout: | + actions + persist-credentials: false + - name: Setup Scripts + uses: ./actions/setup + with: + destination: /opt/gh-aw/actions + - name: Checkout repository + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 + with: + persist-credentials: false + - name: Create gh-aw temp directory + run: bash /opt/gh-aw/actions/create_gh_aw_tmp_dir.sh + - id: setup-uv + name: Install UV package manager + run: | + if ! command -v uv &> /dev/null; then + echo "Installing UV package manager..." + curl -LsSf https://astral.sh/uv/install.sh | sh + export PATH="$HOME/.cargo/bin:$PATH" + echo "$HOME/.cargo/bin" >> $GITHUB_PATH + fi + uv --version + echo "UV package manager is ready" + - id: setup-amplifier + name: Install Amplifier + run: | + echo "Installing Amplifier from GitHub..." + uv tool install git+https://github.com/microsoft/amplifier + export PATH="$HOME/.local/bin:$PATH" + echo "$HOME/.local/bin" >> $GITHUB_PATH + amplifier --version || echo "Amplifier installed (version check not available)" + echo "Amplifier is ready" + mkdir -p /tmp/gh-aw/amplifier + - env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} + AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + id: configure-amplifier + name: Configure Amplifier Provider + run: "# Check which AI provider credentials are available\nif [ -n \"$ANTHROPIC_API_KEY\" ]; then\n echo \"Anthropic credentials detected\"\n export AMPLIFIER_PROVIDER=\"anthropic\"\nelif [ -n \"$OPENAI_API_KEY\" ]; then\n echo \"OpenAI credentials detected\"\n export AMPLIFIER_PROVIDER=\"openai\"\nelif [ -n \"$AZURE_OPENAI_ENDPOINT\" ]; then\n echo \"Azure OpenAI credentials detected\"\n export AMPLIFIER_PROVIDER=\"azure-openai\"\nelse\n echo \"No AI provider credentials detected. Amplifier will require configuration.\"\n echo \"To use Amplifier, configure one of the following secrets:\"\n echo \" - ANTHROPIC_API_KEY (recommended)\"\n echo \" - OPENAI_API_KEY\"\n echo \" - AZURE_OPENAI_ENDPOINT with AZURE_OPENAI_API_KEY\"\nfi\n\n# Create amplifier config directory if it doesn't exist\nmkdir -p ~/.config/amplifier\n\necho \"Amplifier provider configuration complete\"\n" + + - name: Configure Git credentials + env: + REPO_NAME: ${{ github.repository }} + SERVER_URL: ${{ github.server_url }} + run: | + git config --global user.email "github-actions[bot]@users.noreply.github.com" + git config --global user.name "github-actions[bot]" + # Re-authenticate git with GitHub token + SERVER_URL_STRIPPED="${SERVER_URL#https://}" + git remote set-url origin "https://x-access-token:${{ github.token }}@${SERVER_URL_STRIPPED}/${REPO_NAME}.git" + echo "Git configured with standard GitHub Actions identity" + - name: Checkout PR branch + id: checkout-pr + if: | + github.event.pull_request + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + env: + GH_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} + with: + github-token: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} + script: | + const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs'); + setupGlobals(core, github, context, exec, io); + const { main } = require('/opt/gh-aw/actions/checkout_pr_branch.cjs'); + await main(); + - name: Validate COPILOT_GITHUB_TOKEN secret + id: validate-secret + run: /opt/gh-aw/actions/validate_multi_secret.sh COPILOT_GITHUB_TOKEN 'GitHub Copilot CLI' https://github.github.com/gh-aw/reference/engines/#github-copilot-default + env: + COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }} + - name: Install GitHub Copilot CLI + run: /opt/gh-aw/actions/install_copilot_cli.sh 0.0.402 + - name: Install awf binary + run: bash /opt/gh-aw/actions/install_awf_binary.sh v0.13.4 + - name: Determine automatic lockdown mode for GitHub MCP server + id: determine-automatic-lockdown + env: + TOKEN_CHECK: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN }} + if: env.TOKEN_CHECK != '' + uses: actions/github-script@v8 + with: + script: | + const determineAutomaticLockdown = require('/opt/gh-aw/actions/determine_automatic_lockdown.cjs'); + await determineAutomaticLockdown(github, context, core); + - name: Download container images + run: bash /opt/gh-aw/actions/download_docker_images.sh ghcr.io/github/gh-aw-firewall/agent-act:0.13.4 ghcr.io/github/gh-aw-firewall/squid:0.13.4 ghcr.io/github/gh-aw-mcpg:v0.0.98 ghcr.io/github/github-mcp-server:v0.30.3 + - name: Start MCP gateway + id: start-mcp-gateway + env: + GITHUB_MCP_LOCKDOWN: ${{ steps.determine-automatic-lockdown.outputs.lockdown == 'true' && '1' || '0' }} + GITHUB_MCP_SERVER_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} + run: | + set -eo pipefail + mkdir -p /tmp/gh-aw/mcp-config + + # Export gateway environment variables for MCP config and gateway script + export MCP_GATEWAY_PORT="80" + export MCP_GATEWAY_DOMAIN="host.docker.internal" + MCP_GATEWAY_API_KEY="" + MCP_GATEWAY_API_KEY=$(openssl rand -base64 45 | tr -d '/+=') + export MCP_GATEWAY_API_KEY + export DEBUG="*" + + # Register API key as secret to mask it from logs + echo "::add-mask::${MCP_GATEWAY_API_KEY}" + export GH_AW_ENGINE="copilot" + export MCP_GATEWAY_DOCKER_COMMAND='docker run -i --rm --network host -v /var/run/docker.sock:/var/run/docker.sock -e MCP_GATEWAY_PORT -e MCP_GATEWAY_DOMAIN -e MCP_GATEWAY_API_KEY -e DEBUG -e MCP_GATEWAY_LOG_DIR -e GH_AW_MCP_LOG_DIR -e GH_AW_SAFE_OUTPUTS -e GH_AW_SAFE_OUTPUTS_CONFIG_PATH -e GH_AW_SAFE_OUTPUTS_TOOLS_PATH -e GH_AW_ASSETS_BRANCH -e GH_AW_ASSETS_MAX_SIZE_KB -e GH_AW_ASSETS_ALLOWED_EXTS -e DEFAULT_BRANCH -e GITHUB_MCP_SERVER_TOKEN -e GITHUB_MCP_LOCKDOWN -e GITHUB_REPOSITORY -e GITHUB_SERVER_URL -e GITHUB_SHA -e GITHUB_WORKSPACE -e GITHUB_TOKEN -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RUN_ATTEMPT -e GITHUB_JOB -e GITHUB_ACTION -e GITHUB_EVENT_NAME -e GITHUB_EVENT_PATH -e GITHUB_ACTOR -e GITHUB_ACTOR_ID -e GITHUB_TRIGGERING_ACTOR -e GITHUB_WORKFLOW -e GITHUB_WORKFLOW_REF -e GITHUB_WORKFLOW_SHA -e GITHUB_REF -e GITHUB_REF_NAME -e GITHUB_REF_TYPE -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -v /opt:/opt:ro -v /tmp:/tmp:rw -v '"${GITHUB_WORKSPACE}"':'"${GITHUB_WORKSPACE}"':rw ghcr.io/github/gh-aw-mcpg:v0.0.98' + + mkdir -p /home/runner/.copilot + cat << MCPCONFIG_EOF | bash /opt/gh-aw/actions/start_mcp_gateway.sh + { + "mcpServers": { + "github": { + "type": "stdio", + "container": "ghcr.io/github/github-mcp-server:v0.30.3", + "env": { + "GITHUB_LOCKDOWN_MODE": "$GITHUB_MCP_LOCKDOWN", + "GITHUB_PERSONAL_ACCESS_TOKEN": "\${GITHUB_MCP_SERVER_TOKEN}", + "GITHUB_READ_ONLY": "1", + "GITHUB_TOOLSETS": "context,repos,issues,pull_requests" + } + } + }, + "gateway": { + "port": $MCP_GATEWAY_PORT, + "domain": "${MCP_GATEWAY_DOMAIN}", + "apiKey": "${MCP_GATEWAY_API_KEY}" + } + } + MCPCONFIG_EOF + - name: Generate agentic run info + id: generate_aw_info + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const fs = require('fs'); + + const awInfo = { + engine_id: "copilot", + engine_name: "GitHub Copilot CLI", + model: process.env.GH_AW_MODEL_AGENT_COPILOT || "", + version: "", + agent_version: "0.0.402", + workflow_name: "test-amplifier-integration", + experimental: false, + supports_tools_allowlist: true, + supports_http_transport: true, + run_id: context.runId, + run_number: context.runNumber, + run_attempt: process.env.GITHUB_RUN_ATTEMPT, + repository: context.repo.owner + '/' + context.repo.repo, + ref: context.ref, + sha: context.sha, + actor: context.actor, + event_name: context.eventName, + staged: false, + allowed_domains: ["defaults"], + firewall_enabled: true, + awf_version: "v0.13.4", + awmg_version: "v0.0.98", + steps: { + firewall: "squid" + }, + created_at: new Date().toISOString() + }; + + // Write to /tmp/gh-aw directory to avoid inclusion in PR + const tmpPath = '/tmp/gh-aw/aw_info.json'; + fs.writeFileSync(tmpPath, JSON.stringify(awInfo, null, 2)); + console.log('Generated aw_info.json at:', tmpPath); + console.log(JSON.stringify(awInfo, null, 2)); + + // Set model as output for reuse in other steps/jobs + core.setOutput('model', awInfo.model); + - name: Generate workflow overview + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const { generateWorkflowOverview } = require('/opt/gh-aw/actions/generate_workflow_overview.cjs'); + await generateWorkflowOverview(core); + - name: Create prompt with built-in context + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + GH_AW_GITHUB_ACTOR: ${{ github.actor }} + GH_AW_GITHUB_EVENT_COMMENT_ID: ${{ github.event.comment.id }} + GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER: ${{ github.event.discussion.number }} + GH_AW_GITHUB_EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }} + GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }} + GH_AW_GITHUB_REPOSITORY: ${{ github.repository }} + GH_AW_GITHUB_RUN_ID: ${{ github.run_id }} + GH_AW_GITHUB_WORKSPACE: ${{ github.workspace }} + run: | + bash /opt/gh-aw/actions/create_prompt_first.sh + cat << 'PROMPT_EOF' > "$GH_AW_PROMPT" + + PROMPT_EOF + cat "/opt/gh-aw/prompts/temp_folder_prompt.md" >> "$GH_AW_PROMPT" + cat "/opt/gh-aw/prompts/markdown.md" >> "$GH_AW_PROMPT" + cat << 'PROMPT_EOF' >> "$GH_AW_PROMPT" + + The following GitHub context information is available for this workflow: + {{#if __GH_AW_GITHUB_ACTOR__ }} + - **actor**: __GH_AW_GITHUB_ACTOR__ + {{/if}} + {{#if __GH_AW_GITHUB_REPOSITORY__ }} + - **repository**: __GH_AW_GITHUB_REPOSITORY__ + {{/if}} + {{#if __GH_AW_GITHUB_WORKSPACE__ }} + - **workspace**: __GH_AW_GITHUB_WORKSPACE__ + {{/if}} + {{#if __GH_AW_GITHUB_EVENT_ISSUE_NUMBER__ }} + - **issue-number**: #__GH_AW_GITHUB_EVENT_ISSUE_NUMBER__ + {{/if}} + {{#if __GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER__ }} + - **discussion-number**: #__GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER__ + {{/if}} + {{#if __GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER__ }} + - **pull-request-number**: #__GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER__ + {{/if}} + {{#if __GH_AW_GITHUB_EVENT_COMMENT_ID__ }} + - **comment-id**: __GH_AW_GITHUB_EVENT_COMMENT_ID__ + {{/if}} + {{#if __GH_AW_GITHUB_RUN_ID__ }} + - **workflow-run-id**: __GH_AW_GITHUB_RUN_ID__ + {{/if}} + + + PROMPT_EOF + cat << 'PROMPT_EOF' >> "$GH_AW_PROMPT" + + PROMPT_EOF + cat << 'PROMPT_EOF' >> "$GH_AW_PROMPT" + # Amplifier Usage Guide + + Microsoft Amplifier is an AI-powered modular development assistant with specialized agents for different tasks. It has been installed and is available via the `amplifier` command. + + A temporary folder `/tmp/gh-aw/amplifier` is available for caching intermediate results. + + ## Configuration + + Amplifier supports multiple AI providers. Configure your preferred provider using repository secrets: + + ### Anthropic Claude (Recommended) + ```yaml + secrets: + ANTHROPIC_API_KEY: your-api-key + ``` + Get an API key at: https://console.anthropic.com/settings/keys + + ### OpenAI + ```yaml + secrets: + OPENAI_API_KEY: your-api-key + ``` + Get an API key at: https://platform.openai.com/api-keys + + ### Azure OpenAI (Enterprise) + ```yaml + secrets: + AZURE_OPENAI_ENDPOINT: https://your-resource.openai.azure.com/ + AZURE_OPENAI_API_KEY: your-api-key + # Or use Azure CLI authentication with managed identity + ``` + + ### Ollama (Local, Free) + No API key required. Make sure Ollama is running: + ```bash + ollama serve + ollama pull llama3 + ``` + + ## Common Amplifier Operations + + ### Initialize Amplifier + ```bash + # First-time setup wizard (auto-detects missing config) + amplifier init + + # Or configure programmatically + amplifier provider use anthropic --model claude-sonnet-4-5 + # or + amplifier provider use openai --model gpt-5.2 + ``` + + ### Single Command Execution + ```bash + # Get quick answers + amplifier run "Explain async/await in Python" + + # Generate code + amplifier run "Create a REST API for a todo app with FastAPI" + + # Debug issues + amplifier run "Why does this code throw a TypeError: [paste code]" + ``` + + ### Using Specialized Agents + + Amplifier includes several specialized agents for focused tasks: + + ```bash + # Use zen-architect for system design + amplifier run "Design a caching layer with careful consideration" + + # Use bug-hunter for systematic debugging + amplifier run "Use bug-hunter to debug this error: [paste error]" + + # Use explorer for code exploration + amplifier run "Use explorer to analyze the project structure" + + # Use web-research for online research + amplifier run "Use web-research to find best practices for error handling in Go" + ``` + + ### Working with Bundles + + Bundles provide additional capabilities: + + ```bash + # Add capability bundles + amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-recipes@main + amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-design-intelligence@main + + # List available bundles + amplifier bundle list + + # Use a specific bundle + amplifier bundle use recipes + + # See current bundle + amplifier bundle current + ``` + + ### Sessions & Persistence + + ```bash + # Resume most recent session + amplifier continue + + # Resume with new prompt + amplifier continue "follow-up question" + + # List recent sessions (current project only) + amplifier session list + + # List all sessions across all projects + amplifier session list --all-projects + + # View session details + amplifier session show + + # Resume a specific session + amplifier session resume + ``` + + ## Available Agents + + The **foundation** bundle (default) includes these specialized agents: + + - **zen-architect**: System design with ruthless simplicity + - **bug-hunter**: Systematic debugging and error resolution + - **web-research**: Web research and content fetching + - **explorer**: Breadth-first exploration of local code, docs, and files with citation-ready summaries + - **modular-builder**: Code implementation + - **git-ops**: Git operations and version control + - And more... + + Use `/agents` in interactive mode to see all available agents. + + ## Interactive Chat Mode + + ```bash + # Start a conversation + amplifier + + # In chat mode: + # - Context persists across messages + # - Use /help to see available commands + # - Use /tools, /agents, /status, /config to inspect session + # - Use /think and /do to toggle plan mode + # - Type 'exit' or Ctrl+C to quit + ``` + + ## Best Practices + + 1. **Provider Selection**: Anthropic Claude is most tested and recommended + 2. **Session Management**: Use session persistence for complex multi-step tasks + 3. **Agent Delegation**: Let Amplifier choose the right agent, or specify explicitly when needed + 4. **Bundles**: Start with the `foundation` bundle (default) which includes everything for development + 5. **Timeouts**: Amplifier operations may take time depending on the AI provider. Ensure adequate workflow timeouts. + + ## Notes + + - Amplifier is a research demonstrator in early preview + - Use with caution and careful human supervision + - Amplifier works best on macOS, Linux, and Windows Subsystem for Linux (WSL) + - Native Windows shells have known issues—use WSL unless actively contributing Windows fixes + + ## More Information + + - GitHub Repository: https://github.com/microsoft/amplifier + - Documentation: https://microsoft.github.io/amplifier-docs/ + - Log Viewer (for debugging): https://github.com/microsoft/amplifier-app-log-viewer + + + + + PROMPT_EOF + cat << 'PROMPT_EOF' >> "$GH_AW_PROMPT" + {{#runtime-import workflows/test-amplifier-integration.md}} + PROMPT_EOF + - name: Substitute placeholders + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + GH_AW_GITHUB_ACTOR: ${{ github.actor }} + GH_AW_GITHUB_EVENT_COMMENT_ID: ${{ github.event.comment.id }} + GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER: ${{ github.event.discussion.number }} + GH_AW_GITHUB_EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }} + GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }} + GH_AW_GITHUB_REPOSITORY: ${{ github.repository }} + GH_AW_GITHUB_RUN_ID: ${{ github.run_id }} + GH_AW_GITHUB_WORKSPACE: ${{ github.workspace }} + with: + script: | + const substitutePlaceholders = require('/opt/gh-aw/actions/substitute_placeholders.cjs'); + + // Call the substitution function + return await substitutePlaceholders({ + file: process.env.GH_AW_PROMPT, + substitutions: { + GH_AW_GITHUB_ACTOR: process.env.GH_AW_GITHUB_ACTOR, + GH_AW_GITHUB_EVENT_COMMENT_ID: process.env.GH_AW_GITHUB_EVENT_COMMENT_ID, + GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER: process.env.GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER, + GH_AW_GITHUB_EVENT_ISSUE_NUMBER: process.env.GH_AW_GITHUB_EVENT_ISSUE_NUMBER, + GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER: process.env.GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER, + GH_AW_GITHUB_REPOSITORY: process.env.GH_AW_GITHUB_REPOSITORY, + GH_AW_GITHUB_RUN_ID: process.env.GH_AW_GITHUB_RUN_ID, + GH_AW_GITHUB_WORKSPACE: process.env.GH_AW_GITHUB_WORKSPACE + } + }); + - name: Interpolate variables and render templates + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + with: + script: | + const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs'); + setupGlobals(core, github, context, exec, io); + const { main } = require('/opt/gh-aw/actions/interpolate_prompt.cjs'); + await main(); + - name: Validate prompt placeholders + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + run: bash /opt/gh-aw/actions/validate_prompt_placeholders.sh + - name: Print prompt + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + run: bash /opt/gh-aw/actions/print_prompt_summary.sh + - name: Execute GitHub Copilot CLI + id: agentic_execution + # Copilot CLI tool arguments (sorted): + # --allow-tool github + # --allow-tool shell(amplifier *) + # --allow-tool shell(cat) + # --allow-tool shell(date) + # --allow-tool shell(echo) + # --allow-tool shell(grep) + # --allow-tool shell(head) + # --allow-tool shell(ls) + # --allow-tool shell(pwd) + # --allow-tool shell(sort) + # --allow-tool shell(tail) + # --allow-tool shell(uniq) + # --allow-tool shell(uv *) + # --allow-tool shell(wc) + # --allow-tool shell(yq) + # --allow-tool write + timeout-minutes: 20 + run: | + set -o pipefail + sudo -E awf --enable-chroot --env-all --container-workdir "${GITHUB_WORKSPACE}" --allow-domains api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,github.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com --log-level info --proxy-logs-dir /tmp/gh-aw/sandbox/firewall/logs --enable-host-access --image-tag 0.13.4 --skip-pull --agent-image act \ + -- '/usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --add-dir "${GITHUB_WORKSPACE}" --disable-builtin-mcps --allow-tool github --allow-tool '\''shell(amplifier *)'\'' --allow-tool '\''shell(cat)'\'' --allow-tool '\''shell(date)'\'' --allow-tool '\''shell(echo)'\'' --allow-tool '\''shell(grep)'\'' --allow-tool '\''shell(head)'\'' --allow-tool '\''shell(ls)'\'' --allow-tool '\''shell(pwd)'\'' --allow-tool '\''shell(sort)'\'' --allow-tool '\''shell(tail)'\'' --allow-tool '\''shell(uniq)'\'' --allow-tool '\''shell(uv *)'\'' --allow-tool '\''shell(wc)'\'' --allow-tool '\''shell(yq)'\'' --allow-tool write --allow-all-paths --share /tmp/gh-aw/sandbox/agent/logs/conversation.md --prompt "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"${GH_AW_MODEL_DETECTION_COPILOT:+ --model "$GH_AW_MODEL_DETECTION_COPILOT"}' \ + 2>&1 | tee /tmp/gh-aw/agent-stdio.log + env: + COPILOT_AGENT_RUNNER_TYPE: STANDALONE + COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }} + GH_AW_MCP_CONFIG: /home/runner/.copilot/mcp-config.json + GH_AW_MODEL_DETECTION_COPILOT: ${{ vars.GH_AW_MODEL_DETECTION_COPILOT || '' }} + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + GITHUB_HEAD_REF: ${{ github.head_ref }} + GITHUB_REF_NAME: ${{ github.ref_name }} + GITHUB_STEP_SUMMARY: ${{ env.GITHUB_STEP_SUMMARY }} + GITHUB_WORKSPACE: ${{ github.workspace }} + XDG_CONFIG_HOME: /home/runner + - name: Copy Copilot session state files to logs + if: always() + continue-on-error: true + run: | + # Copy Copilot session state files to logs folder for artifact collection + # This ensures they are in /tmp/gh-aw/ where secret redaction can scan them + SESSION_STATE_DIR="$HOME/.copilot/session-state" + LOGS_DIR="/tmp/gh-aw/sandbox/agent/logs" + + if [ -d "$SESSION_STATE_DIR" ]; then + echo "Copying Copilot session state files from $SESSION_STATE_DIR to $LOGS_DIR" + mkdir -p "$LOGS_DIR" + cp -v "$SESSION_STATE_DIR"/*.jsonl "$LOGS_DIR/" 2>/dev/null || true + echo "Session state files copied successfully" + else + echo "No session-state directory found at $SESSION_STATE_DIR" + fi + - name: Stop MCP gateway + if: always() + continue-on-error: true + env: + MCP_GATEWAY_PORT: ${{ steps.start-mcp-gateway.outputs.gateway-port }} + MCP_GATEWAY_API_KEY: ${{ steps.start-mcp-gateway.outputs.gateway-api-key }} + GATEWAY_PID: ${{ steps.start-mcp-gateway.outputs.gateway-pid }} + run: | + bash /opt/gh-aw/actions/stop_mcp_gateway.sh "$GATEWAY_PID" + - name: Redact secrets in logs + if: always() + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs'); + setupGlobals(core, github, context, exec, io); + const { main } = require('/opt/gh-aw/actions/redact_secrets.cjs'); + await main(); + env: + GH_AW_SECRET_NAMES: 'ANTHROPIC_API_KEY,AZURE_OPENAI_API_KEY,AZURE_OPENAI_ENDPOINT,COPILOT_GITHUB_TOKEN,GH_AW_GITHUB_MCP_SERVER_TOKEN,GH_AW_GITHUB_TOKEN,GITHUB_TOKEN,OPENAI_API_KEY' + SECRET_ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + SECRET_AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} + SECRET_AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }} + SECRET_COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }} + SECRET_GH_AW_GITHUB_MCP_SERVER_TOKEN: ${{ secrets.GH_AW_GITHUB_MCP_SERVER_TOKEN }} + SECRET_GH_AW_GITHUB_TOKEN: ${{ secrets.GH_AW_GITHUB_TOKEN }} + SECRET_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + SECRET_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + - name: Upload engine output files + uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0 + with: + name: agent_outputs + path: | + /tmp/gh-aw/sandbox/agent/logs/ + /tmp/gh-aw/redacted-urls.log + if-no-files-found: ignore + - name: Parse agent logs for step summary + if: always() + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + env: + GH_AW_AGENT_OUTPUT: /tmp/gh-aw/sandbox/agent/logs/ + with: + script: | + const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs'); + setupGlobals(core, github, context, exec, io); + const { main } = require('/opt/gh-aw/actions/parse_copilot_log.cjs'); + await main(); + - name: Parse MCP gateway logs for step summary + if: always() + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs'); + setupGlobals(core, github, context, exec, io); + const { main } = require('/opt/gh-aw/actions/parse_mcp_gateway_log.cjs'); + await main(); + - name: Print firewall logs + if: always() + continue-on-error: true + env: + AWF_LOGS_DIR: /tmp/gh-aw/sandbox/firewall/logs + run: | + # Fix permissions on firewall logs so they can be uploaded as artifacts + # AWF runs with sudo, creating files owned by root + sudo chmod -R a+r /tmp/gh-aw/sandbox/firewall/logs 2>/dev/null || true + awf logs summary | tee -a "$GITHUB_STEP_SUMMARY" + - name: Upload agent artifacts + if: always() + continue-on-error: true + uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0 + with: + name: agent-artifacts + path: | + /tmp/gh-aw/aw-prompts/prompt.txt + /tmp/gh-aw/aw_info.json + /tmp/gh-aw/mcp-logs/ + /tmp/gh-aw/sandbox/firewall/logs/ + /tmp/gh-aw/agent-stdio.log + if-no-files-found: ignore + diff --git a/.github/workflows/test-amplifier-integration.md b/.github/workflows/test-amplifier-integration.md new file mode 100644 index 0000000000..e3991fcd66 --- /dev/null +++ b/.github/workflows/test-amplifier-integration.md @@ -0,0 +1,29 @@ +--- +name: test-amplifier-integration +description: Test workflow to validate Amplifier shared workflow integration +engine: copilot + +imports: + - shared/mcp/amplifier.md + +permissions: + contents: read + issues: read + pull-requests: read + +on: + workflow_dispatch: +--- + +# Test Amplifier Integration + +This is a test workflow to validate that the Amplifier shared workflow component is properly configured and can be used in agentic workflows. + +Please perform the following tasks: + +1. Verify that the `amplifier` command is available in your environment +2. Run a simple amplifier command to test the installation: `amplifier --version` or `amplifier --help` +3. Test that UV package manager is installed and working +4. Report the versions of both tools and confirm they are functioning correctly + +If any step fails, report the error details so we can fix the shared workflow configuration. diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index 5d20cd6fb2..b58aaba197 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -141,6 +141,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Test Dispatcher Workflow](https://github.com/github/gh-aw/blob/main/.github/workflows/test-dispatcher.md) | copilot | [![Test Dispatcher Workflow](https://github.com/github/gh-aw/actions/workflows/test-dispatcher.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/test-dispatcher.lock.yml) | - | - | | [Test Project URL Explicit Requirement](https://github.com/github/gh-aw/blob/main/.github/workflows/test-project-url-default.md) | copilot | [![Test Project URL Explicit Requirement](https://github.com/github/gh-aw/actions/workflows/test-project-url-default.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/test-project-url-default.lock.yml) | - | - | | [Test Workflow](https://github.com/github/gh-aw/blob/main/.github/workflows/test-workflow.md) | copilot | [![Test Workflow](https://github.com/github/gh-aw/actions/workflows/test-workflow.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/test-workflow.lock.yml) | - | - | +| [test-amplifier-integration](https://github.com/github/gh-aw/blob/main/.github/workflows/test-amplifier-integration.md) | copilot | [![test-amplifier-integration](https://github.com/github/gh-aw/actions/workflows/test-amplifier-integration.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/test-amplifier-integration.lock.yml) | - | - | | [The Daily Repository Chronicle](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-repo-chronicle.md) | copilot | [![The Daily Repository Chronicle](https://github.com/github/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml) | `0 16 * * 1-5` | - | | [The Great Escapi](https://github.com/github/gh-aw/blob/main/.github/workflows/firewall-escape.md) | copilot | [![The Great Escapi](https://github.com/github/gh-aw/actions/workflows/firewall-escape.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/firewall-escape.lock.yml) | - | - | | [Tidy](https://github.com/github/gh-aw/blob/main/.github/workflows/tidy.md) | copilot | [![Tidy](https://github.com/github/gh-aw/actions/workflows/tidy.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/tidy.lock.yml) | `0 7 * * *` | - |