Snowflake Cortex Agents のバージョン管理および GitHub Actions での CI/CD を考えみた

-- Commit the live version to create a named version
ALTER AGENT my_agent COMMIT
  COMMENT = 'Production release for Q1';

-- Create a named version from a stage
ALTER AGENT my_agent ADD VERSION FROM @my_stage/agents/my_agent
  COMMENT = 'Imported from feature branch';

-- Assign an alias to a named version
ALTER AGENT my_agent
  MODIFY VERSION VERSION$3 SET ALIAS = production;

-- Set the default version
ALTER AGENT my_agent
  SET DEFAULT_VERSION = 'VERSION$3';

-- DEFAULT バージョンの agent_spec.yaml ディレクトリパスの取得
SHOW VERSIONS IN AGENT KITAGAWA_TEST_DB.AGENT_DEV.GENERAL_AGENT
->> SELECT "spec_file_path" FROM $1 WHERE "is_default" = 'true';

-- ファイル名の確認
-- SHOW VERSIONS で取得したディレクトリパスを LIST に渡す
LIST snow://agent/KITAGAWA_TEST_DB.AGENT_DEV.GENERAL_AGENT/versions/version$2/
->> SELECT "name" FROM $1;

# Snowflake CLI から GET
snow sql -q "GET snow://agent/KITAGAWA_TEST_DB.AGENT_DEV.GENERAL_AGENT/versions/version\$2/agent_spec.yaml file:///tmp/;"

mkdir -p ./cortex_agents/GENERAL_AGENT/
mv /tmp/agent_spec.yaml ./cortex_agents/GENERAL_AGENT/

name: Deploy Cortex Agent

on:
  push:
    branches:
      - main
    paths:
      - "cortex_agents/*/agent_spec.yaml"
  workflow_dispatch:
    inputs:
      agent_name:
        description: "Deploy target agent name (cortex_agents/<AGENT_NAME>)"
        required: true

permissions:
  id-token: write
  contents: read

defaults:
  run:
    shell: bash

env:
  # 接続情報
  SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
  # デプロイ先
  AGENT_DATABASE: KITAGAWA_TEST_DB
  AGENT_SCHEMA: AGENT_PROD
  STAGE_NAME: AGENT_SPECS

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      agents: ${{ steps.targets.outputs.agents }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Detect target agents
        id: targets
        env:
          INPUT_AGENT_NAME: ${{ inputs.agent_name }}
          BEFORE_SHA: ${{ github.event.before }}
        run: |
          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
            agents=$(jq -cn --arg a "${INPUT_AGENT_NAME}" '[$a]')
          elif git cat-file -e "${BEFORE_SHA}" 2> /dev/null; then
            # push 前のコミットと比較
            agents=$(git diff --name-only --diff-filter=d "${BEFORE_SHA}" HEAD -- 'cortex_agents/*/agent_spec.yaml' \
              | cut -d/ -f2 | sort -u | jq -Rnc '[inputs]')
          else
            # 比較元が無い場合、全エージェントを対象にする
            agents=$(git ls-files 'cortex_agents/*/agent_spec.yaml' \
              | cut -d/ -f2 | sort -u | jq -Rnc '[inputs]')
          fi
          echo "Target agents: ${agents}"
          echo "agents=${agents}" >> "$GITHUB_OUTPUT"

  deploy:
    needs: detect
    if: needs.detect.outputs.agents != '[]'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        agent_name: ${{ fromJSON(needs.detect.outputs.agents) }}
    env:
      AGENT_NAME: ${{ matrix.agent_name }}
    steps:
      - uses: actions/checkout@v7

      - name: Install Snowflake CLI
        uses: snowflakedb/snowflake-actions@v3
        with:
          use-oidc: true

      - name: Copy agent spec file to stage
        run: |
          snow stage copy \
            "cortex_agents/${AGENT_NAME}/agent_spec.yaml" \
            "@${AGENT_DATABASE}.${AGENT_SCHEMA}.${STAGE_NAME}/${AGENT_NAME}/" \
            --overwrite \
            --temporary-connection

      - name: Check if agent exists
        id: check
        run: |
          count=$(snow sql --temporary-connection --format json -q "
            SHOW AGENTS LIKE '${AGENT_NAME}' IN SCHEMA ${AGENT_DATABASE}.${AGENT_SCHEMA};
          " | jq 'length')
          echo "exists=$([ "${count}" -gt 0 ] && echo true || echo false)" >> "$GITHUB_OUTPUT"

      # 初回デプロイ: エージェント作成（VERSION$1 が自動コミットされる）
      - name: Create agent (first deploy)
        if: steps.check.outputs.exists == 'false'
        run: |
          {
            echo "CREATE AGENT ${AGENT_DATABASE}.${AGENT_SCHEMA}.${AGENT_NAME}"
            echo "  FROM SPECIFICATION"
            echo "\$\$"
            cat "cortex_agents/${AGENT_NAME}/agent_spec.yaml"
            echo "\$\$;"
          } > create_agent.sql
          snow sql --temporary-connection -f create_agent.sql

      # 2回目以降: ステージから新バージョンを追加
      - name: Add version
        if: steps.check.outputs.exists == 'true'
        run: |
          # live バージョンが残っていると ADD VERSION が失敗するため、先に COMMIT する。
          live=$(snow sql --temporary-connection --format json -q "
            SHOW VERSIONS IN AGENT ${AGENT_DATABASE}.${AGENT_SCHEMA}.${AGENT_NAME};
          " | jq 'map(select(.name == null)) | length')
          if [ "${live}" -gt 0 ]; then
            snow sql --temporary-connection -q "
              ALTER AGENT ${AGENT_DATABASE}.${AGENT_SCHEMA}.${AGENT_NAME}
                COMMIT COMMENT = 'Auto-commit leftover live version';
            "
          fi

          snow sql --temporary-connection -q "
            ALTER AGENT ${AGENT_DATABASE}.${AGENT_SCHEMA}.${AGENT_NAME}
              ADD VERSION FROM @${AGENT_DATABASE}.${AGENT_SCHEMA}.${STAGE_NAME}/${AGENT_NAME}
              COMMENT = 'Deployed from GitHub Actions (${GITHUB_SHA})';
          "

      - name: Set alias and default
        run: |
          # SHOW VERSIONS から最新の named バージョンを解決する
          version=$(snow sql --temporary-connection --format json -q "
            SHOW VERSIONS IN AGENT ${AGENT_DATABASE}.${AGENT_SCHEMA}.${AGENT_NAME};
          " | jq -r 'map(select(.name != null)) | max_by(.created_on) | .name')
          if [ -z "${version}" ] || [ "${version}" = "null" ]; then
            echo "::error::No named version found for ${AGENT_NAME}"
            exit 1
          fi
          echo "Latest version: ${version}"

          snow sql --temporary-connection -q "
            ALTER AGENT ${AGENT_DATABASE}.${AGENT_SCHEMA}.${AGENT_NAME}
              MODIFY VERSION ${version} SET ALIAS = production;

            ALTER AGENT ${AGENT_DATABASE}.${AGENT_SCHEMA}.${AGENT_NAME}
              SET DEFAULT_VERSION = '${version}';
          "

--- a/cortex_agents/GENERAL_AGENT/agent_spec.yaml
+++ b/cortex_agents/GENERAL_AGENT/agent_spec.yaml
@@ -12,4 +12,4 @@ tools:
 tool_resources:
   code_toolset_all:
     permission_policy:
-      type: "always_allow"
+      type: "always_ask"

git add .
git commit -m "Update GENERAL_AGENT agent_spec.yaml"
git push

SHOW VERSIONS IN AGENT KITAGAWA_TEST_DB.AGENT_PROD.GENERAL_AGENT;