agents-python-publish.yml

name: Publish agents Python packages to PyPI
run-name: Publish agents Python packages ${{ inputs.version || github.event.release.tag_name }}

on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      version:
        description: Agents release version shared by every agents package
        required: true
        type: string
      publish:
        description: Publish to PyPI; false stamps, builds, and smoke-tests only
        required: true
        default: false
        type: boolean
      skip_packages:
        description: >-
          Space-separated CLI command distributions to leave out of this upload, such as
          dex-agents-builtin-cli, when PyPI's new-project limit splits a first release; empty uploads all
        required: false
        default: ""
        type: string

permissions:
  contents: read

concurrency:
  group: agents-python-publish-${{ github.event.release.tag_name || inputs.version }}
  cancel-in-progress: false

env:
  DEXCLI_RELEASE_TAG: cli-v1.45.0
  DEXCLI_ARCHIVE: dexcli_v1.45.0_linux_amd64.tar.gz
  # Upload order: the core, the adapters, the CLI core, then the CLI commands.
  AGENTS_PYTHON_DISTRIBUTIONS: >-
    dex-agents dex-agents-openai-agents dex-agents-pydantic-ai dex-agents-langgraph dex-agents-google-adk
    dex-agents-claude-agent-sdk dex-agents-cli-core dex-agents-claude-sdk-cli dex-agents-openai-sdk-cli
    dex-agents-pydantic-ai-cli dex-agents-deepagents-cli dex-agents-google-adk-cli dex-agents-builtin-cli

jobs:
  prepare:
    name: Validate release
    if: >
      github.event_name == 'workflow_dispatch' ||
      (startsWith(github.event.release.tag_name, 'agents/v') && !github.event.release.draft)
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.release.outputs.version }}
      publish: ${{ steps.release.outputs.publish }}
      skip_packages: ${{ steps.release.outputs.skip_packages }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - name: Resolve release version
        id: release
        shell: bash
        env:
          EVENT_NAME: ${{ github.event_name }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
          DISPATCH_VERSION: ${{ inputs.version }}
          DISPATCH_PUBLISH: ${{ inputs.publish }}
          DISPATCH_SKIP_PACKAGES: ${{ inputs.skip_packages }}
          RELEASE_REF: ${{ github.ref }}
        run: |
          if [[ "${EVENT_NAME}" == "release" ]]; then
            version="${RELEASE_TAG#agents/v}"
            publish=true
            if ! git merge-base --is-ancestor HEAD origin/main; then
              echo "Release tag must point to a commit on main" >&2
              exit 1
            fi
          else
            version="${DISPATCH_VERSION}"
            publish="${DISPATCH_PUBLISH}"
            # The release tag is allowed too, so a later run uploads exactly the released commit.
            if [[ "${publish}" == "true" && "${RELEASE_REF}" != "refs/heads/main" ]]; then
              if [[ "${RELEASE_REF}" != "refs/tags/agents/v${version}" ]]; then
                echo "Manual publishing is allowed only from main or the tag agents/v${version}" >&2
                exit 1
              fi
              if ! git merge-base --is-ancestor HEAD origin/main; then
                echo "Release tag must point to a commit on main" >&2
                exit 1
              fi
            fi
          fi
          if [[ ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z]+)*$ ]]; then
            echo "Invalid agents release version: ${version}" >&2
            exit 1
          fi
          # Only CLI commands, which nothing depends on, may be skipped; every input line is read.
          read -r -d '' -a skip_packages <<< "${DISPATCH_SKIP_PACKAGES}" || true
          for skipped in "${skip_packages[@]}"; do
            if [[ "${skipped}" != dex-agents-*-cli || " ${AGENTS_PYTHON_DISTRIBUTIONS} " != *" ${skipped} "* ]]; then
              echo "skip_packages names ${skipped}, which is not a CLI command distribution" >&2
              exit 1
            fi
          done
          {
            echo "version=${version}"
            echo "publish=${publish}"
            echo "skip_packages=${skip_packages[*]}"
          } >> "${GITHUB_OUTPUT}"

  build:
    name: Build and smoke-test distributions
    needs: prepare
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v7
      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
        with:
          version: "0.12.2"
          python-version: "3.11"
          working-directory: agents/python/core
      - name: Download and verify dexcli
        env:
          GH_TOKEN: ${{ github.token }}
          DEXCLI_DIR: ${{ runner.temp }}/dexcli
        run: |
          set -euo pipefail
          mkdir -p "$DEXCLI_DIR"
          cd "$DEXCLI_DIR"
          gh release download "$DEXCLI_RELEASE_TAG" \
            --repo "$GITHUB_REPOSITORY" \
            --pattern "$DEXCLI_ARCHIVE" \
            --pattern checksums.txt
          if ! grep -E "^[0-9a-f]{64}  (\./)?${DEXCLI_ARCHIVE//./\\.}\$" checksums.txt > archive.sha256; then
            echo "checksums.txt has no entry for $DEXCLI_ARCHIVE"
            exit 1
          fi
          sha256sum --check --strict archive.sha256
          tar -xzf "$DEXCLI_ARCHIVE"
          ./dexcli --version
          echo "DEXCLI=$DEXCLI_DIR/dexcli" >> "$GITHUB_ENV"
      - name: Stamp package versions from release
        run: uv run --no-project --python 3.11 python agents/script/stamp_agents_release_version.py '${{ needs.prepare.outputs.version }}'
      - name: Build and smoke-test the built packages
        env:
          AGENTS_DIST_DIR: ${{ github.workspace }}/agents-dist
        run: agents/script/smoke-test-built-packages.sh python
      - name: Upload distributions
        uses: actions/upload-artifact@v7
        with:
          name: agents-python-distributions
          path: agents-dist/python/*
          if-no-files-found: error

  publish:
    name: Publish agents Python packages
    if: needs.prepare.outputs.publish == 'true'
    needs: [prepare, build]
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
        with:
          version: "0.12.2"
          python-version: "3.11"
      - name: Download distributions
        uses: actions/download-artifact@v7
        with:
          name: agents-python-distributions
          path: dist
      - name: Validate distributions
        shell: bash
        run: |
          shopt -s nullglob
          read -r -a distributions <<< "${AGENTS_PYTHON_DISTRIBUTIONS}"
          wheels=(dist/*.whl)
          sdists=(dist/*.tar.gz)
          if [[ "${#wheels[@]}" -ne "${#distributions[@]}" || "${#sdists[@]}" -ne "${#distributions[@]}" ]]; then
            echo "Expected ${#distributions[@]} wheels and ${#distributions[@]} source distributions" >&2
            printf '%s\n' dist/* >&2
            exit 1
          fi
      # The core publishes first so every adapter's dex-agents==<version> requirement resolves.
      # Files already on PyPI are skipped, so a rerun uploads only the rest.
      - name: Publish distributions with trusted publishing
        shell: bash
        env:
          RELEASE_VERSION: ${{ needs.prepare.outputs.version }}
          SKIP_PACKAGES: ${{ needs.prepare.outputs.skip_packages }}
        run: |
          set -euo pipefail
          read -r -a distributions <<< "${AGENTS_PYTHON_DISTRIBUTIONS}"
          for distribution in "${distributions[@]}"; do
            if [[ " ${SKIP_PACKAGES} " == *" ${distribution} "* ]]; then
              echo "::notice::Skipped ${distribution} ${RELEASE_VERSION}; publish it in a later run"
              continue
            fi
            # An unknown version or a failed lookup lists nothing; --check-url still skips identical files.
            published_files="$(curl --silent --fail "https://pypi.org/pypi/${distribution}/${RELEASE_VERSION}/json" |
              jq -r '.urls[].filename' || true)"
            pending_files=()
            for file in dist/"${distribution//-/_}"-[0-9]*; do
              if grep -qxF "${file#dist/}" <<< "${published_files}"; then
                echo "${file#dist/} is already on PyPI"
              else
                pending_files+=("${file}")
              fi
            done
            if [[ "${#pending_files[@]}" -gt 0 ]]; then
              uv publish --trusted-publishing always --check-url https://pypi.org/simple "${pending_files[@]}"
            fi
          done