feat(library): enhance folder and agent management with error handling improvements

- Added support for updating the folder ID in the `update_library_agent` function, allowing agents to be moved to different folders.
- Implemented cleanup of schedules and webhooks for affected agents during folder deletion, ensuring proper resource management.
- Improved error handling in various folder-related API endpoints, standardizing error messages to provide clearer feedback to users.
- Updated the `LibraryFolderEditDialog` to handle API errors more effectively, enhancing user experience during folder operations.

These changes improve the functionality and reliability of folder and agent management within the library, providing users with a smoother experience when organizing their agents.

.claude/settings.json

@@ -1,10 +0,0 @@
-{
-  "permissions": {
-    "allowedTools": [
-      "Read", "Grep", "Glob",
-      "Bash(ls:*)", "Bash(cat:*)", "Bash(grep:*)", "Bash(find:*)",
-      "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git worktree:*)",
-      "Bash(tmux:*)", "Bash(sleep:*)", "Bash(branchlet:*)"
-    ]
-  }
-}

.github/workflows/classic-autogpt-ci.yml

@@ -6,15 +6,11 @@ on:
     paths:
       - '.github/workflows/classic-autogpt-ci.yml'
       - 'classic/original_autogpt/**'
-      - 'classic/direct_benchmark/**'
-      - 'classic/forge/**'
   pull_request:
     branches: [ master, dev, release-* ]
     paths:
       - '.github/workflows/classic-autogpt-ci.yml'
       - 'classic/original_autogpt/**'
-      - 'classic/direct_benchmark/**'
-      - 'classic/forge/**'
 
 concurrency:
   group: ${{ format('classic-autogpt-ci-{0}', github.head_ref && format('{0}-{1}', github.event_name, github.event.pull_request.number) || github.sha) }}
@@ -23,22 +19,47 @@ concurrency:
 defaults:
   run:
     shell: bash
-    working-directory: classic
+    working-directory: classic/original_autogpt
 
 jobs:
   test:
     permissions:
       contents: read
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+        platform-os: [ubuntu, macos, macos-arm64, windows]
+    runs-on: ${{ matrix.platform-os != 'macos-arm64' && format('{0}-latest', matrix.platform-os) || 'macos-14' }}
 
     steps:
-      - name: Start MinIO service
+      # Quite slow on macOS (2~4 minutes to set up Docker)
+      # - name: Set up Docker (macOS)
+      #   if: runner.os == 'macOS'
+      #   uses: crazy-max/ghaction-setup-docker@v3
+
+      - name: Start MinIO service (Linux)
+        if: runner.os == 'Linux'
         working-directory: '.'
         run: |
           docker pull minio/minio:edge-cicd
           docker run -d -p 9000:9000 minio/minio:edge-cicd
 
+      - name: Start MinIO service (macOS)
+        if: runner.os == 'macOS'
+        working-directory: ${{ runner.temp }}
+        run: |
+          brew install minio/stable/minio
+          mkdir data
+          minio server ./data &
+
+      # No MinIO on Windows:
+      # - Windows doesn't support running Linux Docker containers
+      # - It doesn't seem possible to start background processes on Windows. They are
+      #   killed after the step returns.
+      #   See: https://github.com/actions/runner/issues/598#issuecomment-2011890429
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
@@ -50,23 +71,41 @@ jobs:
           git config --global user.name "Auto-GPT-Bot"
           git config --global user.email "github-bot@agpt.co"
 
-      - name: Set up Python 3.12
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
 
       - id: get_date
         name: Get date
         run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
 
       - name: Set up Python dependency cache
+        # On Windows, unpacking cached dependencies takes longer than just installing them
+        if: runner.os != 'Windows'
         uses: actions/cache@v4
         with:
-          path: ~/.cache/pypoetry
-          key: poetry-${{ runner.os }}-${{ hashFiles('classic/poetry.lock') }}
+          path: ${{ runner.os == 'macOS' && '~/Library/Caches/pypoetry' || '~/.cache/pypoetry' }}
+          key: poetry-${{ runner.os }}-${{ hashFiles('classic/original_autogpt/poetry.lock') }}
 
-      - name: Install Poetry
-        run: curl -sSL https://install.python-poetry.org | python3 -
+      - name: Install Poetry (Unix)
+        if: runner.os != 'Windows'
+        run: |
+          curl -sSL https://install.python-poetry.org | python3 -
+
+          if [ "${{ runner.os }}" = "macOS" ]; then
+            PATH="$HOME/.local/bin:$PATH"
+            echo "$HOME/.local/bin" >> $GITHUB_PATH
+          fi
+
+      - name: Install Poetry (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+
+          $env:PATH += ";$env:APPDATA\Python\Scripts"
+          echo "$env:APPDATA\Python\Scripts" >> $env:GITHUB_PATH
 
       - name: Install Python dependencies
         run: poetry install
@@ -77,13 +116,12 @@ jobs:
             --cov=autogpt --cov-branch --cov-report term-missing --cov-report xml \
             --numprocesses=logical --durations=10 \
             --junitxml=junit.xml -o junit_family=legacy \
-            original_autogpt/tests/unit original_autogpt/tests/integration
+            tests/unit tests/integration
         env:
           CI: true
           PLAIN_OUTPUT: True
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          S3_ENDPOINT_URL: http://127.0.0.1:9000
+          S3_ENDPOINT_URL: ${{ runner.os != 'Windows' && 'http://127.0.0.1:9000' || '' }}
           AWS_ACCESS_KEY_ID: minioadmin
           AWS_SECRET_ACCESS_KEY: minioadmin
 
@@ -97,11 +135,11 @@ jobs:
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-          flags: autogpt-agent
+          flags: autogpt-agent,${{ runner.os }}
 
       - name: Upload logs to artifact
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: test-logs
-          path: classic/logs/
+          path: classic/original_autogpt/logs/

.github/workflows/classic-autogpts-ci.yml

@@ -11,6 +11,9 @@ on:
       - 'classic/original_autogpt/**'
       - 'classic/forge/**'
       - 'classic/benchmark/**'
+      - 'classic/run'
+      - 'classic/cli.py'
+      - 'classic/setup.py'
       - '!**/*.md'
   pull_request:
     branches: [ master, dev, release-* ]
@@ -19,6 +22,9 @@ on:
       - 'classic/original_autogpt/**'
       - 'classic/forge/**'
       - 'classic/benchmark/**'
+      - 'classic/run'
+      - 'classic/cli.py'
+      - 'classic/setup.py'
       - '!**/*.md'
 
 defaults:
@@ -29,9 +35,13 @@ defaults:
 jobs:
   serve-agent-protocol:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        agent-name: [ original_autogpt ]
+      fail-fast: false
     timeout-minutes: 20
     env:
-      min-python-version: '3.12'
+      min-python-version: '3.10'
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -45,22 +55,22 @@ jobs:
           python-version: ${{ env.min-python-version }}
 
       - name: Install Poetry
+        working-directory: ./classic/${{ matrix.agent-name }}/
         run: |
           curl -sSL https://install.python-poetry.org | python -
 
-      - name: Install dependencies
-        run: poetry install
-
-      - name: Run smoke tests with direct-benchmark
+      - name: Run regression tests
         run: |
-          poetry run direct-benchmark run \
-            --strategies one_shot \
-            --models claude \
-            --tests ReadFile,WriteFile \
-            --json
+          ./run agent start ${{ matrix.agent-name }}
+          cd ${{ matrix.agent-name }}
+          poetry run agbenchmark --mock --test=BasicRetrieval --test=Battleship --test=WebArenaTask_0
+          poetry run agbenchmark --test=WriteFile
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          AGENT_NAME: ${{ matrix.agent-name }}
           REQUESTS_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt
-          NONINTERACTIVE_MODE: "true"
-          CI: true
+          HELICONE_CACHE_ENABLED: false
+          HELICONE_PROPERTY_AGENT: ${{ matrix.agent-name }}
+          REPORTS_FOLDER: ${{ format('../../reports/{0}', matrix.agent-name) }}
+          TELEMETRY_ENVIRONMENT: autogpt-ci
+          TELEMETRY_OPT_IN: ${{ github.ref_name == 'master' }}

.github/workflows/classic-benchmark-ci.yml

@@ -1,21 +1,17 @@
-name: Classic - Direct Benchmark CI
+name: Classic - AGBenchmark CI
 
 on:
   push:
     branches: [ master, dev, ci-test* ]
     paths:
-      - 'classic/direct_benchmark/**'
-      - 'classic/benchmark/agbenchmark/challenges/**'
-      - 'classic/original_autogpt/**'
-      - 'classic/forge/**'
+      - 'classic/benchmark/**'
+      - '!classic/benchmark/reports/**'
       - .github/workflows/classic-benchmark-ci.yml
   pull_request:
     branches: [ master, dev, release-* ]
     paths:
-      - 'classic/direct_benchmark/**'
-      - 'classic/benchmark/agbenchmark/challenges/**'
-      - 'classic/original_autogpt/**'
-      - 'classic/forge/**'
+      - 'classic/benchmark/**'
+      - '!classic/benchmark/reports/**'
       - .github/workflows/classic-benchmark-ci.yml
 
 concurrency:
@@ -27,16 +23,23 @@ defaults:
     shell: bash
 
 env:
-  min-python-version: '3.12'
+  min-python-version: '3.10'
 
 jobs:
-  benchmark-tests:
-    runs-on: ubuntu-latest
+  test:
+    permissions:
+      contents: read
     timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+        platform-os: [ubuntu, macos, macos-arm64, windows]
+    runs-on: ${{ matrix.platform-os != 'macos-arm64' && format('{0}-latest', matrix.platform-os) || 'macos-14' }}
     defaults:
       run:
         shell: bash
-        working-directory: classic
+        working-directory: classic/benchmark
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -44,88 +47,71 @@ jobs:
           fetch-depth: 0
           submodules: true
 
-      - name: Set up Python ${{ env.min-python-version }}
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.min-python-version }}
+          python-version: ${{ matrix.python-version }}
 
       - name: Set up Python dependency cache
+        # On Windows, unpacking cached dependencies takes longer than just installing them
+        if: runner.os != 'Windows'
         uses: actions/cache@v4
         with:
-          path: ~/.cache/pypoetry
-          key: poetry-${{ runner.os }}-${{ hashFiles('classic/poetry.lock') }}
+          path: ${{ runner.os == 'macOS' && '~/Library/Caches/pypoetry' || '~/.cache/pypoetry' }}
+          key: poetry-${{ runner.os }}-${{ hashFiles('classic/benchmark/poetry.lock') }}
 
-      - name: Install Poetry
+      - name: Install Poetry (Unix)
+        if: runner.os != 'Windows'
         run: |
           curl -sSL https://install.python-poetry.org | python3 -
 
-      - name: Install dependencies
+          if [ "${{ runner.os }}" = "macOS" ]; then
+            PATH="$HOME/.local/bin:$PATH"
+            echo "$HOME/.local/bin" >> $GITHUB_PATH
+          fi
+
+      - name: Install Poetry (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+
+          $env:PATH += ";$env:APPDATA\Python\Scripts"
+          echo "$env:APPDATA\Python\Scripts" >> $env:GITHUB_PATH
+
+      - name: Install Python dependencies
         run: poetry install
 
-      - name: Run basic benchmark tests
+      - name: Run pytest with coverage
         run: |
-          echo "Testing ReadFile challenge with one_shot strategy..."
-          poetry run direct-benchmark run \
-            --fresh \
-            --strategies one_shot \
-            --models claude \
-            --tests ReadFile \
-            --json
-
-          echo "Testing WriteFile challenge..."
-          poetry run direct-benchmark run \
-            --fresh \
-            --strategies one_shot \
-            --models claude \
-            --tests WriteFile \
-            --json
+          poetry run pytest -vv \
+            --cov=agbenchmark --cov-branch --cov-report term-missing --cov-report xml \
+            --durations=10 \
+            --junitxml=junit.xml -o junit_family=legacy \
+            tests
         env:
           CI: true
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          NONINTERACTIVE_MODE: "true"
 
-      - name: Test category filtering
-        run: |
-          echo "Testing coding category..."
-          poetry run direct-benchmark run \
-            --fresh \
-            --strategies one_shot \
-            --models claude \
-            --categories coding \
-            --tests ReadFile,WriteFile \
-            --json
-        env:
-          CI: true
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          NONINTERACTIVE_MODE: "true"
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}  # Run even if tests fail
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
 
-      - name: Test multiple strategies
-        run: |
-          echo "Testing multiple strategies..."
-          poetry run direct-benchmark run \
-            --fresh \
-            --strategies one_shot,plan_execute \
-            --models claude \
-            --tests ReadFile \
-            --parallel 2 \
-            --json
-        env:
-          CI: true
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          NONINTERACTIVE_MODE: "true"
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          flags: agbenchmark,${{ runner.os }}
 
-  # Run regression tests on maintain challenges
-  regression-tests:
+  self-test-with-agent:
     runs-on: ubuntu-latest
-    timeout-minutes: 45
-    if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/dev'
-    defaults:
-      run:
-        shell: bash
-        working-directory: classic
+    strategy:
+      matrix:
+        agent-name: [forge]
+      fail-fast: false
+    timeout-minutes: 20
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -140,23 +126,51 @@ jobs:
 
       - name: Install Poetry
         run: |
-          curl -sSL https://install.python-poetry.org | python3 -
-
-      - name: Install dependencies
-        run: poetry install
+          curl -sSL https://install.python-poetry.org | python -
 
       - name: Run regression tests
+        working-directory: classic
         run: |
-          echo "Running regression tests (previously beaten challenges)..."
-          poetry run direct-benchmark run \
-            --fresh \
-            --strategies one_shot \
-            --models claude \
-            --maintain \
-            --parallel 4 \
-            --json
+          ./run agent start ${{ matrix.agent-name }}
+          cd ${{ matrix.agent-name }}
+
+          set +e # Ignore non-zero exit codes and continue execution
+          echo "Running the following command: poetry run agbenchmark --maintain --mock"
+          poetry run agbenchmark --maintain --mock
+          EXIT_CODE=$?
+          set -e  # Stop ignoring non-zero exit codes
+          # Check if the exit code was 5, and if so, exit with 0 instead
+          if [ $EXIT_CODE -eq 5 ]; then
+            echo "regression_tests.json is empty."
+          fi
+
+          echo "Running the following command: poetry run agbenchmark --mock"
+          poetry run agbenchmark --mock
+
+          echo "Running the following command: poetry run agbenchmark --mock --category=data"
+          poetry run agbenchmark --mock --category=data
+
+          echo "Running the following command: poetry run agbenchmark --mock --category=coding"
+          poetry run agbenchmark --mock --category=coding
+
+          # echo "Running the following command: poetry run agbenchmark --test=WriteFile"
+          # poetry run agbenchmark --test=WriteFile
+          cd ../benchmark
+          poetry install
+          echo "Adding the BUILD_SKILL_TREE environment variable. This will attempt to add new elements in the skill tree. If new elements are added, the CI fails because they should have been pushed"
+          export BUILD_SKILL_TREE=true
+
+          # poetry run agbenchmark --mock
+
+          # CHANGED=$(git diff --name-only | grep -E '(agbenchmark/challenges)|(../classic/frontend/assets)') || echo "No diffs"
+          # if [ ! -z "$CHANGED" ]; then
+          #   echo "There are unstaged changes please run agbenchmark and commit those changes since they are needed."
+          #   echo "$CHANGED"
+          #   exit 1
+          # else
+          #   echo "No unstaged changes."
+          # fi
         env:
-          CI: true
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          NONINTERACTIVE_MODE: "true"
+          TELEMETRY_ENVIRONMENT: autogpt-benchmark-ci
+          TELEMETRY_OPT_IN: ${{ github.ref_name == 'master' }}

.github/workflows/classic-forge-ci.yml

@@ -6,11 +6,13 @@ on:
     paths:
       - '.github/workflows/classic-forge-ci.yml'
       - 'classic/forge/**'
+      - '!classic/forge/tests/vcr_cassettes'
   pull_request:
     branches: [ master, dev, release-* ]
     paths:
       - '.github/workflows/classic-forge-ci.yml'
       - 'classic/forge/**'
+      - '!classic/forge/tests/vcr_cassettes'
 
 concurrency:
   group: ${{ format('forge-ci-{0}', github.head_ref && format('{0}-{1}', github.event_name, github.event.pull_request.number) || github.sha) }}
@@ -19,60 +21,131 @@ concurrency:
 defaults:
   run:
     shell: bash
-    working-directory: classic
+    working-directory: classic/forge
 
 jobs:
   test:
     permissions:
       contents: read
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+        platform-os: [ubuntu, macos, macos-arm64, windows]
+    runs-on: ${{ matrix.platform-os != 'macos-arm64' && format('{0}-latest', matrix.platform-os) || 'macos-14' }}
 
     steps:
-      - name: Start MinIO service
+      # Quite slow on macOS (2~4 minutes to set up Docker)
+      # - name: Set up Docker (macOS)
+      #   if: runner.os == 'macOS'
+      #   uses: crazy-max/ghaction-setup-docker@v3
+
+      - name: Start MinIO service (Linux)
+        if: runner.os == 'Linux'
         working-directory: '.'
         run: |
           docker pull minio/minio:edge-cicd
           docker run -d -p 9000:9000 minio/minio:edge-cicd
 
+      - name: Start MinIO service (macOS)
+        if: runner.os == 'macOS'
+        working-directory: ${{ runner.temp }}
+        run: |
+          brew install minio/stable/minio
+          mkdir data
+          minio server ./data &
+
+      # No MinIO on Windows:
+      # - Windows doesn't support running Linux Docker containers
+      # - It doesn't seem possible to start background processes on Windows. They are
+      #   killed after the step returns.
+      #   See: https://github.com/actions/runner/issues/598#issuecomment-2011890429
+
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: true
 
-      - name: Set up Python 3.12
+      - name: Checkout cassettes
+        if: ${{ startsWith(github.event_name, 'pull_request') }}
+        env:
+          PR_BASE: ${{ github.event.pull_request.base.ref }}
+          PR_BRANCH: ${{ github.event.pull_request.head.ref }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          cassette_branch="${PR_AUTHOR}-${PR_BRANCH}"
+          cassette_base_branch="${PR_BASE}"
+          cd tests/vcr_cassettes
+
+          if ! git ls-remote --exit-code --heads origin $cassette_base_branch ; then
+            cassette_base_branch="master"
+          fi
+
+          if git ls-remote --exit-code --heads origin $cassette_branch ; then
+            git fetch origin $cassette_branch
+            git fetch origin $cassette_base_branch
+
+            git checkout $cassette_branch
+
+            # Pick non-conflicting cassette updates from the base branch
+            git merge --no-commit --strategy-option=ours origin/$cassette_base_branch
+            echo "Using cassettes from mirror branch '$cassette_branch'," \
+              "synced to upstream branch '$cassette_base_branch'."
+          else
+            git checkout -b $cassette_branch
+            echo "Branch '$cassette_branch' does not exist in cassette submodule." \
+              "Using cassettes from '$cassette_base_branch'."
+          fi
+
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
 
       - name: Set up Python dependency cache
+        # On Windows, unpacking cached dependencies takes longer than just installing them
+        if: runner.os != 'Windows'
         uses: actions/cache@v4
         with:
-          path: ~/.cache/pypoetry
-          key: poetry-${{ runner.os }}-${{ hashFiles('classic/poetry.lock') }}
+          path: ${{ runner.os == 'macOS' && '~/Library/Caches/pypoetry' || '~/.cache/pypoetry' }}
+          key: poetry-${{ runner.os }}-${{ hashFiles('classic/forge/poetry.lock') }}
 
-      - name: Install Poetry
-        run: curl -sSL https://install.python-poetry.org | python3 -
+      - name: Install Poetry (Unix)
+        if: runner.os != 'Windows'
+        run: |
+          curl -sSL https://install.python-poetry.org | python3 -
+
+          if [ "${{ runner.os }}" = "macOS" ]; then
+            PATH="$HOME/.local/bin:$PATH"
+            echo "$HOME/.local/bin" >> $GITHUB_PATH
+          fi
+
+      - name: Install Poetry (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+
+          $env:PATH += ";$env:APPDATA\Python\Scripts"
+          echo "$env:APPDATA\Python\Scripts" >> $env:GITHUB_PATH
 
       - name: Install Python dependencies
         run: poetry install
 
-      - name: Install Playwright browsers
-        run: poetry run playwright install chromium
-
       - name: Run pytest with coverage
         run: |
           poetry run pytest -vv \
             --cov=forge --cov-branch --cov-report term-missing --cov-report xml \
             --durations=10 \
             --junitxml=junit.xml -o junit_family=legacy \
-            forge/forge forge/tests
+            forge
         env:
           CI: true
           PLAIN_OUTPUT: True
-          # API keys - tests that need these will skip if not available
-          # Secrets are not available to fork PRs (GitHub security feature)
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          S3_ENDPOINT_URL: http://127.0.0.1:9000
+          S3_ENDPOINT_URL: ${{ runner.os != 'Windows' && 'http://127.0.0.1:9000' || '' }}
           AWS_ACCESS_KEY_ID: minioadmin
           AWS_SECRET_ACCESS_KEY: minioadmin
 
@@ -86,11 +159,85 @@ jobs:
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-          flags: forge
+          flags: forge,${{ runner.os }}
+
+      - id: setup_git_auth
+        name: Set up git token authentication
+        # Cassettes may be pushed even when tests fail
+        if: success() || failure()
+        run: |
+          config_key="http.${{ github.server_url }}/.extraheader"
+          if [ "${{ runner.os }}" = 'macOS' ]; then
+            base64_pat=$(echo -n "pat:${{ secrets.PAT_REVIEW }}" | base64)
+          else
+            base64_pat=$(echo -n "pat:${{ secrets.PAT_REVIEW }}" | base64 -w0)
+          fi
+
+          git config "$config_key" \
+            "Authorization: Basic $base64_pat"
+
+          cd tests/vcr_cassettes
+          git config "$config_key" \
+            "Authorization: Basic $base64_pat"
+
+          echo "config_key=$config_key" >> $GITHUB_OUTPUT
+
+      - id: push_cassettes
+        name: Push updated cassettes
+        # For pull requests, push updated cassettes even when tests fail
+        if: github.event_name == 'push' || (! github.event.pull_request.head.repo.fork && (success() || failure()))
+        env:
+          PR_BRANCH: ${{ github.event.pull_request.head.ref }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          if [ "${{ startsWith(github.event_name, 'pull_request') }}" = "true" ]; then
+            is_pull_request=true
+            cassette_branch="${PR_AUTHOR}-${PR_BRANCH}"
+          else
+            cassette_branch="${{ github.ref_name }}"
+          fi
+
+          cd tests/vcr_cassettes
+          # Commit & push changes to cassettes if any
+          if ! git diff --quiet; then
+            git add .
+            git commit -m "Auto-update cassettes"
+            git push origin HEAD:$cassette_branch
+            if [ ! $is_pull_request ]; then
+              cd ../..
+              git add tests/vcr_cassettes
+              git commit -m "Update cassette submodule"
+              git push origin HEAD:$cassette_branch
+            fi
+            echo "updated=true" >> $GITHUB_OUTPUT
+          else
+            echo "updated=false" >> $GITHUB_OUTPUT
+            echo "No cassette changes to commit"
+          fi
+
+      - name: Post Set up git token auth
+        if: steps.setup_git_auth.outcome == 'success'
+        run: |
+          git config --unset-all '${{ steps.setup_git_auth.outputs.config_key }}'
+          git submodule foreach git config --unset-all '${{ steps.setup_git_auth.outputs.config_key }}'
+
+      - name: Apply "behaviour change" label and comment on PR
+        if: ${{ startsWith(github.event_name, 'pull_request') }}
+        run: |
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          TOKEN="${{ secrets.PAT_REVIEW }}"
+          REPO="${{ github.repository }}"
+
+          if [[ "${{ steps.push_cassettes.outputs.updated }}" == "true" ]]; then
+            echo "Adding label and comment..."
+            echo $TOKEN | gh auth login --with-token
+            gh issue edit $PR_NUMBER --add-label "behaviour change"
+            gh issue comment $PR_NUMBER --body "You changed AutoGPT's behaviour on ${{ runner.os }}. The cassettes have been updated and will be merged to the submodule when this Pull Request gets merged."
+          fi
 
       - name: Upload logs to artifact
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: test-logs
-          path: classic/logs/
+          path: classic/forge/logs/

.github/workflows/classic-frontend-ci.yml

@@ -0,0 +1,60 @@
+name: Classic - Frontend CI/CD
+
+on:
+  push:
+    branches:
+      - master
+      - dev
+      - 'ci-test*' # This will match any branch that starts with "ci-test"
+    paths:
+      - 'classic/frontend/**'
+      - '.github/workflows/classic-frontend-ci.yml'
+  pull_request:
+    paths:
+      - 'classic/frontend/**'
+      - '.github/workflows/classic-frontend-ci.yml'
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    env:
+      BUILD_BRANCH: ${{ format('classic-frontend-build/{0}', github.ref_name) }}
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Setup Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: '3.13.2'
+
+      - name: Build Flutter to Web
+        run: |
+          cd classic/frontend
+          flutter build web --base-href /app/
+
+      # - name: Commit and Push to ${{ env.BUILD_BRANCH }}
+      #   if: github.event_name == 'push'
+      #   run: |
+      #     git config --local user.email "action@github.com"
+      #     git config --local user.name "GitHub Action"
+      #     git add classic/frontend/build/web
+      #     git checkout -B ${{ env.BUILD_BRANCH }}
+      #     git commit -m "Update frontend build to ${GITHUB_SHA:0:7}" -a
+      #     git push -f origin ${{ env.BUILD_BRANCH }}
+
+      - name: Create PR ${{ env.BUILD_BRANCH }} -> ${{ github.ref_name }}
+        if: github.event_name == 'push'
+        uses: peter-evans/create-pull-request@v8
+        with:
+          add-paths: classic/frontend/build/web
+          base: ${{ github.ref_name }}
+          branch: ${{ env.BUILD_BRANCH }}
+          delete-branch: true
+          title: "Update frontend build in `${{ github.ref_name }}`"
+          body: "This PR updates the frontend build based on commit ${{ github.sha }}."
+          commit-message: "Update frontend build based on commit ${{ github.sha }}"

.github/workflows/classic-python-checks.yml

@@ -7,9 +7,7 @@ on:
       - '.github/workflows/classic-python-checks-ci.yml'
       - 'classic/original_autogpt/**'
       - 'classic/forge/**'
-      - 'classic/direct_benchmark/**'
-      - 'classic/pyproject.toml'
-      - 'classic/poetry.lock'
+      - 'classic/benchmark/**'
       - '**.py'
       - '!classic/forge/tests/vcr_cassettes'
   pull_request:
@@ -18,9 +16,7 @@ on:
       - '.github/workflows/classic-python-checks-ci.yml'
       - 'classic/original_autogpt/**'
       - 'classic/forge/**'
-      - 'classic/direct_benchmark/**'
-      - 'classic/pyproject.toml'
-      - 'classic/poetry.lock'
+      - 'classic/benchmark/**'
       - '**.py'
       - '!classic/forge/tests/vcr_cassettes'
 
@@ -31,13 +27,44 @@ concurrency:
 defaults:
   run:
     shell: bash
-    working-directory: classic
 
 jobs:
+  get-changed-parts:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - id: changes-in
+        name: Determine affected subprojects
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            original_autogpt:
+              - classic/original_autogpt/autogpt/**
+              - classic/original_autogpt/tests/**
+              - classic/original_autogpt/poetry.lock
+            forge:
+              - classic/forge/forge/**
+              - classic/forge/tests/**
+              - classic/forge/poetry.lock
+            benchmark:
+              - classic/benchmark/agbenchmark/**
+              - classic/benchmark/tests/**
+              - classic/benchmark/poetry.lock
+    outputs:
+      changed-parts: ${{ steps.changes-in.outputs.changes }}
+
   lint:
+    needs: get-changed-parts
     runs-on: ubuntu-latest
     env:
-      min-python-version: "3.12"
+      min-python-version: "3.10"
+
+    strategy:
+      matrix:
+        sub-package: ${{ fromJson(needs.get-changed-parts.outputs.changed-parts) }}
+      fail-fast: false
 
     steps:
       - name: Checkout repository
@@ -54,31 +81,42 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.cache/pypoetry
-          key: ${{ runner.os }}-poetry-${{ hashFiles('classic/poetry.lock') }}
+          key: ${{ runner.os }}-poetry-${{ hashFiles(format('{0}/poetry.lock', matrix.sub-package)) }}
 
       - name: Install Poetry
         run: curl -sSL https://install.python-poetry.org | python3 -
 
+      # Install dependencies
+
       - name: Install Python dependencies
-        run: poetry install
+        run: poetry -C classic/${{ matrix.sub-package }} install
 
       # Lint
 
       - name: Lint (isort)
         run: poetry run isort --check .
+        working-directory: classic/${{ matrix.sub-package }}
 
       - name: Lint (Black)
         if: success() || failure()
         run: poetry run black --check .
+        working-directory: classic/${{ matrix.sub-package }}
 
       - name: Lint (Flake8)
         if: success() || failure()
         run: poetry run flake8 .
+        working-directory: classic/${{ matrix.sub-package }}
 
   types:
+    needs: get-changed-parts
     runs-on: ubuntu-latest
     env:
-      min-python-version: "3.12"
+      min-python-version: "3.10"
+
+    strategy:
+      matrix:
+        sub-package: ${{ fromJson(needs.get-changed-parts.outputs.changed-parts) }}
+      fail-fast: false
 
     steps:
       - name: Checkout repository
@@ -95,16 +133,19 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.cache/pypoetry
-          key: ${{ runner.os }}-poetry-${{ hashFiles('classic/poetry.lock') }}
+          key: ${{ runner.os }}-poetry-${{ hashFiles(format('{0}/poetry.lock', matrix.sub-package)) }}
 
       - name: Install Poetry
         run: curl -sSL https://install.python-poetry.org | python3 -
 
+      # Install dependencies
+
       - name: Install Python dependencies
-        run: poetry install
+        run: poetry -C classic/${{ matrix.sub-package }} install
 
       # Typecheck
 
       - name: Typecheck
         if: success() || failure()
         run: poetry run pyright
+        working-directory: classic/${{ matrix.sub-package }}

.gitignore

@@ -3,7 +3,6 @@
 classic/original_autogpt/keys.py
 classic/original_autogpt/*.json
 auto_gpt_workspace/*
-.autogpt/
 *.mpeg
 .env
 # Root .env files
@@ -160,10 +159,6 @@ CURRENT_BULLETIN.md
 
 # AgBenchmark
 classic/benchmark/agbenchmark/reports/
-classic/reports/
-classic/direct_benchmark/reports/
-classic/.benchmark_workspaces/
-classic/direct_benchmark/.benchmark_workspaces/
 
 # Nodejs
 package-lock.json
@@ -182,11 +177,7 @@ autogpt_platform/backend/settings.py
 
 *.ign.*
 .test-contents
-**/.claude/settings.local.json
 .claude/settings.local.json
 CLAUDE.local.md
 /autogpt_platform/backend/logs
-
-# Test database
-test.db
-.next
+.next

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "classic/forge/tests/vcr_cassettes"]
+	path = classic/forge/tests/vcr_cassettes
+	url = https://github.com/Significant-Gravitas/Auto-GPT-test-cassettes

.pre-commit-config.yaml

@@ -43,10 +43,29 @@ repos:
         pass_filenames: false
 
       - id: poetry-install
-        name: Check & Install dependencies - Classic
-        alias: poetry-install-classic
-        entry: poetry -C classic install
-        files: ^classic/poetry\.lock$
+        name: Check & Install dependencies - Classic - AutoGPT
+        alias: poetry-install-classic-autogpt
+        entry: poetry -C classic/original_autogpt install
+        # include forge source (since it's a path dependency)
+        files: ^classic/(original_autogpt|forge)/poetry\.lock$
+        types: [file]
+        language: system
+        pass_filenames: false
+
+      - id: poetry-install
+        name: Check & Install dependencies - Classic - Forge
+        alias: poetry-install-classic-forge
+        entry: poetry -C classic/forge install
+        files: ^classic/forge/poetry\.lock$
+        types: [file]
+        language: system
+        pass_filenames: false
+
+      - id: poetry-install
+        name: Check & Install dependencies - Classic - Benchmark
+        alias: poetry-install-classic-benchmark
+        entry: poetry -C classic/benchmark install
+        files: ^classic/benchmark/poetry\.lock$
         types: [file]
         language: system
         pass_filenames: false
@@ -97,10 +116,26 @@ repos:
         language: system
 
       - id: isort
-        name: Lint (isort) - Classic
-        alias: isort-classic
-        entry: bash -c 'cd classic && poetry run isort $(echo "$@" | sed "s|classic/||g")' --
-        files: ^classic/(original_autogpt|forge|direct_benchmark)/
+        name: Lint (isort) - Classic - AutoGPT
+        alias: isort-classic-autogpt
+        entry: poetry -P classic/original_autogpt run isort -p autogpt
+        files: ^classic/original_autogpt/
+        types: [file, python]
+        language: system
+
+      - id: isort
+        name: Lint (isort) - Classic - Forge
+        alias: isort-classic-forge
+        entry: poetry -P classic/forge run isort -p forge
+        files: ^classic/forge/
+        types: [file, python]
+        language: system
+
+      - id: isort
+        name: Lint (isort) - Classic - Benchmark
+        alias: isort-classic-benchmark
+        entry: poetry -P classic/benchmark run isort -p agbenchmark
+        files: ^classic/benchmark/
         types: [file, python]
         language: system
 
@@ -114,13 +149,26 @@ repos:
 
   - repo: https://github.com/PyCQA/flake8
     rev: 7.0.0
-    # Use consolidated flake8 config at classic/.flake8
+    # To have flake8 load the config of the individual subprojects, we have to call
+    # them separately.
     hooks:
       - id: flake8
-        name: Lint (Flake8) - Classic
-        alias: flake8-classic
-        files: ^classic/(original_autogpt|forge|direct_benchmark)/
-        args: [--config=classic/.flake8]
+        name: Lint (Flake8) - Classic - AutoGPT
+        alias: flake8-classic-autogpt
+        files: ^classic/original_autogpt/(autogpt|scripts|tests)/
+        args: [--config=classic/original_autogpt/.flake8]
+
+      - id: flake8
+        name: Lint (Flake8) - Classic - Forge
+        alias: flake8-classic-forge
+        files: ^classic/forge/(forge|tests)/
+        args: [--config=classic/forge/.flake8]
+
+      - id: flake8
+        name: Lint (Flake8) - Classic - Benchmark
+        alias: flake8-classic-benchmark
+        files: ^classic/benchmark/(agbenchmark|tests)/((?!reports).)*[/.]
+        args: [--config=classic/benchmark/.flake8]
 
   - repo: local
     hooks:
@@ -156,10 +204,29 @@ repos:
         pass_filenames: false
 
       - id: pyright
-        name: Typecheck - Classic
-        alias: pyright-classic
-        entry: poetry -C classic run pyright
-        files: ^classic/(original_autogpt|forge|direct_benchmark)/.*\.py$|^classic/poetry\.lock$
+        name: Typecheck - Classic - AutoGPT
+        alias: pyright-classic-autogpt
+        entry: poetry -C classic/original_autogpt run pyright
+        # include forge source (since it's a path dependency) but exclude *_test.py files:
+        files: ^(classic/original_autogpt/((autogpt|scripts|tests)/|poetry\.lock$)|classic/forge/(forge/.*(?<!_test)\.py|poetry\.lock)$)
+        types: [file]
+        language: system
+        pass_filenames: false
+
+      - id: pyright
+        name: Typecheck - Classic - Forge
+        alias: pyright-classic-forge
+        entry: poetry -C classic/forge run pyright
+        files: ^classic/forge/(forge/|poetry\.lock$)
+        types: [file]
+        language: system
+        pass_filenames: false
+
+      - id: pyright
+        name: Typecheck - Classic - Benchmark
+        alias: pyright-classic-benchmark
+        entry: poetry -C classic/benchmark run pyright
+        files: ^classic/benchmark/(agbenchmark/|tests/|poetry\.lock$)
         types: [file]
         language: system
         pass_filenames: false

autogpt_platform/backend/backend/api/features/library/db.py

@@ -7,6 +7,7 @@ import prisma.errors
 import prisma.models
 import prisma.types
 
+from backend.api.features.library.exceptions import FolderValidationError
 import backend.api.features.store.exceptions as store_exceptions
 import backend.api.features.store.image_gen as store_image_gen
 import backend.api.features.store.media as store_media
@@ -42,6 +43,8 @@ async def list_library_agents(
     page: int = 1,
     page_size: int = 50,
     include_executions: bool = False,
+    folder_id: Optional[str] = None,
+    include_root_only: bool = False,
 ) -> library_model.LibraryAgentResponse:
     """
     Retrieves a paginated list of LibraryAgent records for a given user.
@@ -52,6 +55,8 @@ async def list_library_agents(
         sort_by: Sorting field (createdAt, updatedAt, isFavorite, isCreatedByUser).
         page: Current page (1-indexed).
         page_size: Number of items per page.
+        folder_id: Filter by folder ID. If provided, only returns agents in this folder.
+        include_root_only: If True, only returns agents without a folder (root-level).
         include_executions: Whether to include execution data for status calculation.
             Defaults to False for performance (UI fetches status separately).
             Set to True when accurate status/metrics are needed (e.g., agent generator).
@@ -82,6 +87,13 @@ async def list_library_agents(
         "isArchived": False,
     }
 
+    # Apply folder filter (skip when searching — search spans all folders)
+    if folder_id is not None and not search_term:
+        where_clause["folderId"] = folder_id
+    elif include_root_only and not search_term:
+        where_clause["folderId"] = None
+
+    # Build search filter if applicable
     if search_term:
         where_clause["OR"] = [
             {
@@ -634,6 +646,7 @@ async def update_library_agent(
     is_archived: Optional[bool] = None,
     is_deleted: Optional[Literal[False]] = None,
     settings: Optional[GraphSettings] = None,
+    folder_id: Optional[str] = None,
 ) -> library_model.LibraryAgent:
     """
     Updates the specified LibraryAgent record.
@@ -646,6 +659,7 @@ async def update_library_agent(
         is_favorite: Whether this agent is marked as a favorite.
         is_archived: Whether this agent is archived.
         settings: User-specific settings for this library agent.
+        folder_id: Folder ID to move agent to (empty string "" for root, None to skip).
 
     Returns:
         The updated LibraryAgent.
@@ -673,13 +687,10 @@ async def update_library_agent(
             )
         update_fields["isDeleted"] = is_deleted
     if settings is not None:
-        existing_agent = await get_library_agent(id=library_agent_id, user_id=user_id)
-        current_settings_dict = (
-            existing_agent.settings.model_dump() if existing_agent.settings else {}
-        )
-        new_settings = settings.model_dump(exclude_unset=True)
-        merged_settings = {**current_settings_dict, **new_settings}
-        update_fields["settings"] = SafeJson(merged_settings)
+        update_fields["settings"] = SafeJson(settings.model_dump())
+    if folder_id is not None:
+        # Empty string means "move to root" (no folder)
+        update_fields["folderId"] = None if folder_id == "" else folder_id
 
     try:
         # If graph_version is provided, update to that specific version
@@ -918,6 +929,813 @@ async def add_store_agent_to_library(
         raise DatabaseError("Failed to add agent to library") from e
 
 
+##############################################
+############ Folder DB Functions #############
+##############################################
+
+MAX_FOLDER_DEPTH = 5
+
+
+async def list_folders(
+    user_id: str,
+    parent_id: Optional[str] = None,
+    include_counts: bool = True,
+) -> list[library_model.LibraryFolder]:
+    """
+    Lists folders for a user, optionally filtered by parent.
+
+    Args:
+        user_id: The ID of the user.
+        parent_id: If provided, only returns folders with this parent.
+                   If None, returns root-level folders.
+        include_counts: Whether to include agent and subfolder counts.
+
+    Returns:
+        A list of LibraryFolder objects.
+    """
+    logger.debug(f"Listing folders for user #{user_id}, parent_id={parent_id}")
+
+    try:
+        where_clause: prisma.types.LibraryFolderWhereInput = {
+            "userId": user_id,
+            "isDeleted": False,
+            "parentId": parent_id,
+        }
+
+        folders = await prisma.models.LibraryFolder.prisma().find_many(
+            where=where_clause,
+            order={"createdAt": "asc"},
+            include=(
+                {
+                    "LibraryAgents": {"where": {"isDeleted": False}},
+                    "Children": {"where": {"isDeleted": False}},
+                }
+                if include_counts
+                else None
+            ),
+        )
+
+        result = []
+        for folder in folders:
+            agent_count = len(folder.LibraryAgents) if folder.LibraryAgents else 0
+            subfolder_count = len(folder.Children) if folder.Children else 0
+            result.append(
+                library_model.LibraryFolder.from_db(
+                    folder,
+                    agent_count=agent_count,
+                    subfolder_count=subfolder_count,
+                )
+            )
+
+        return result
+
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error listing folders: {e}")
+        raise DatabaseError("Failed to list folders") from e
+
+
+async def get_folder_tree(
+    user_id: str,
+) -> list[library_model.LibraryFolderTree]:
+    """
+    Gets the full folder tree for a user.
+
+    Args:
+        user_id: The ID of the user.
+
+    Returns:
+        A list of LibraryFolderTree objects (root folders with nested children).
+    """
+    logger.debug(f"Getting folder tree for user #{user_id}")
+
+    try:
+        # Fetch all folders for the user
+        all_folders = await prisma.models.LibraryFolder.prisma().find_many(
+            where={
+                "userId": user_id,
+                "isDeleted": False,
+            },
+            order={"createdAt": "asc"},
+            include={
+                "LibraryAgents": {"where": {"isDeleted": False}},
+                "Children": {"where": {"isDeleted": False}},
+            },
+        )
+
+        # Build a map of folder ID to folder data
+        folder_map: dict[str, library_model.LibraryFolderTree] = {}
+        for folder in all_folders:
+            agent_count = len(folder.LibraryAgents) if folder.LibraryAgents else 0
+            subfolder_count = len(folder.Children) if folder.Children else 0
+            folder_map[folder.id] = library_model.LibraryFolderTree(
+                **library_model.LibraryFolder.from_db(
+                    folder,
+                    agent_count=agent_count,
+                    subfolder_count=subfolder_count,
+                ).model_dump(),
+                children=[],
+            )
+
+        # Build the tree structure
+        root_folders: list[library_model.LibraryFolderTree] = []
+        for folder in all_folders:
+            tree_folder = folder_map[folder.id]
+            if folder.parentId and folder.parentId in folder_map:
+                folder_map[folder.parentId].children.append(tree_folder)
+            else:
+                root_folders.append(tree_folder)
+
+        return root_folders
+
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error getting folder tree: {e}")
+        raise DatabaseError("Failed to get folder tree") from e
+
+
+async def get_folder(
+    folder_id: str,
+    user_id: str,
+) -> library_model.LibraryFolder:
+    """
+    Gets a single folder by ID.
+
+    Args:
+        folder_id: The ID of the folder.
+        user_id: The ID of the user (for ownership verification).
+
+    Returns:
+        The LibraryFolder object.
+
+    Raises:
+        NotFoundError: If the folder doesn't exist or doesn't belong to the user.
+    """
+    try:
+        folder = await prisma.models.LibraryFolder.prisma().find_first(
+            where={
+                "id": folder_id,
+                "userId": user_id,
+                "isDeleted": False,
+            },
+            include={
+                "LibraryAgents": {"where": {"isDeleted": False}},
+                "Children": {"where": {"isDeleted": False}},
+            },
+        )
+
+        if not folder:
+            raise NotFoundError(f"Folder #{folder_id} not found")
+
+        agent_count = len(folder.LibraryAgents) if folder.LibraryAgents else 0
+        subfolder_count = len(folder.Children) if folder.Children else 0
+
+        return library_model.LibraryFolder.from_db(
+            folder,
+            agent_count=agent_count,
+            subfolder_count=subfolder_count,
+        )
+
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error getting folder: {e}")
+        raise DatabaseError("Failed to get folder") from e
+
+
+async def get_folder_depth(folder_id: str, user_id: str) -> int:
+    """
+    Calculate the depth of a folder in the hierarchy (root=0).
+
+    Args:
+        folder_id: The ID of the folder.
+        user_id: The ID of the user.
+
+    Returns:
+        The depth of the folder (0 for root-level folders).
+    """
+    depth = 0
+    current_id: str | None = folder_id
+
+    while current_id:
+        folder = await prisma.models.LibraryFolder.prisma().find_first(
+            where={
+                "id": current_id,
+                "userId": user_id,
+                "isDeleted": False,
+            }
+        )
+        if not folder:
+            break
+        if folder.parentId:
+            depth += 1
+            current_id = folder.parentId
+        else:
+            break
+
+    return depth
+
+
+async def is_descendant_of(
+    folder_id: str,
+    potential_ancestor_id: str,
+    user_id: str,
+) -> bool:
+    """
+    Check if folder_id is a descendant of potential_ancestor_id.
+
+    Args:
+        folder_id: The ID of the folder to check.
+        potential_ancestor_id: The ID of the potential ancestor.
+        user_id: The ID of the user.
+
+    Returns:
+        True if folder_id is a descendant of potential_ancestor_id.
+    """
+    current_id: str | None = folder_id
+
+    while current_id:
+        if current_id == potential_ancestor_id:
+            return True
+
+        folder = await prisma.models.LibraryFolder.prisma().find_first(
+            where={
+                "id": current_id,
+                "userId": user_id,
+                "isDeleted": False,
+            }
+        )
+        if not folder or not folder.parentId:
+            break
+        current_id = folder.parentId
+
+    return False
+
+
+async def validate_folder_operation(
+    folder_id: Optional[str],
+    target_parent_id: Optional[str],
+    user_id: str,
+    max_depth: int = MAX_FOLDER_DEPTH,
+) -> None:
+    """
+    Validate that a folder move/create operation is valid.
+
+    Args:
+        folder_id: The ID of the folder being moved (None for create).
+        target_parent_id: The target parent ID (None for root).
+        user_id: The ID of the user.
+        max_depth: Maximum allowed nesting depth.
+
+    Raises:
+        FolderValidationError: If the operation is invalid.
+    """
+    # Cannot move folder into itself
+    if folder_id and folder_id == target_parent_id:
+        raise FolderValidationError("Cannot move folder into itself")
+
+    # Check for circular reference
+    if folder_id and target_parent_id:
+        if await is_descendant_of(target_parent_id, folder_id, user_id):
+            raise FolderValidationError("Cannot move folder into its own descendant")
+
+    # Check depth limit
+    if target_parent_id:
+        parent_depth = await get_folder_depth(target_parent_id, user_id)
+        if parent_depth + 1 >= max_depth:
+            raise FolderValidationError(
+                f"Maximum folder nesting depth of {max_depth} exceeded"
+            )
+
+
+async def create_folder(
+    user_id: str,
+    name: str,
+    parent_id: Optional[str] = None,
+    icon: Optional[str] = None,
+    color: Optional[str] = None,
+) -> library_model.LibraryFolder:
+    """
+    Creates a new folder for the user.
+
+    Args:
+        user_id: The ID of the user.
+        name: The folder name.
+        parent_id: Optional parent folder ID.
+        icon: Optional icon identifier.
+        color: Optional hex color code.
+
+    Returns:
+        The created LibraryFolder.
+
+    Raises:
+        FolderValidationError: If validation fails.
+        DatabaseError: If there's a database error.
+    """
+    logger.debug(f"Creating folder '{name}' for user #{user_id}")
+
+    try:
+        # Validate operation
+        await validate_folder_operation(
+            folder_id=None,
+            target_parent_id=parent_id,
+            user_id=user_id,
+        )
+
+        # Verify parent exists if provided
+        if parent_id:
+            parent = await prisma.models.LibraryFolder.prisma().find_first(
+                where={
+                    "id": parent_id,
+                    "userId": user_id,
+                    "isDeleted": False,
+                }
+            )
+            if not parent:
+                raise NotFoundError(f"Parent folder #{parent_id} not found")
+
+        # Build data dict conditionally - don't include Parent key if no parent_id
+        create_data: dict = {
+            "name": name,
+            "User": {"connect": {"id": user_id}},
+        }
+        if icon is not None:
+            create_data["icon"] = icon
+        if color is not None:
+            create_data["color"] = color
+        if parent_id:
+            create_data["Parent"] = {"connect": {"id": parent_id}}
+
+        folder = await prisma.models.LibraryFolder.prisma().create(data=create_data)
+
+        return library_model.LibraryFolder.from_db(folder)
+
+    except prisma.errors.UniqueViolationError:
+        raise FolderValidationError(
+            "A folder with this name already exists in this location"
+        )
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error creating folder: {e}")
+        raise DatabaseError("Failed to create folder") from e
+
+
+async def create_folder_with_unique_name(
+    user_id: str,
+    base_name: str,
+    parent_id: Optional[str] = None,
+    icon: Optional[str] = None,
+    color: Optional[str] = None,
+) -> library_model.LibraryFolder:
+    """
+    Creates a folder, appending (2), (3), etc. if name exists.
+
+    Args:
+        user_id: The ID of the user.
+        base_name: The base folder name.
+        parent_id: Optional parent folder ID.
+        icon: Optional icon identifier.
+        color: Optional hex color code.
+
+    Returns:
+        The created LibraryFolder.
+    """
+    name = base_name
+    suffix = 1
+
+    while True:
+        try:
+            return await create_folder(
+                user_id=user_id,
+                name=name,
+                parent_id=parent_id,
+                icon=icon,
+                color=color,
+            )
+        except FolderValidationError as e:
+            if "already exists" in str(e):
+                suffix += 1
+                name = f"{base_name} ({suffix})"
+            else:
+                raise
+
+
+async def update_folder(
+    folder_id: str,
+    user_id: str,
+    name: Optional[str] = None,
+    icon: Optional[str] = None,
+    color: Optional[str] = None,
+) -> library_model.LibraryFolder:
+    """
+    Updates a folder's properties.
+
+    Args:
+        folder_id: The ID of the folder to update.
+        user_id: The ID of the user.
+        name: New folder name.
+        icon: New icon identifier.
+        color: New hex color code.
+
+    Returns:
+        The updated LibraryFolder.
+
+    Raises:
+        NotFoundError: If the folder doesn't exist.
+        DatabaseError: If there's a database error.
+    """
+    logger.debug(f"Updating folder #{folder_id} for user #{user_id}")
+
+    try:
+        # Verify folder exists and belongs to user
+        existing = await prisma.models.LibraryFolder.prisma().find_first(
+            where={
+                "id": folder_id,
+                "userId": user_id,
+                "isDeleted": False,
+            }
+        )
+        if not existing:
+            raise NotFoundError(f"Folder #{folder_id} not found")
+
+        update_data: prisma.types.LibraryFolderUpdateInput = {}
+        if name is not None:
+            update_data["name"] = name
+        if icon is not None:
+            update_data["icon"] = icon
+        if color is not None:
+            update_data["color"] = color
+
+        if not update_data:
+            return await get_folder(folder_id, user_id)
+
+        folder = await prisma.models.LibraryFolder.prisma().update(
+            where={"id": folder_id},
+            data=update_data,
+            include={
+                "LibraryAgents": {"where": {"isDeleted": False}},
+                "Children": {"where": {"isDeleted": False}},
+            },
+        )
+
+        if not folder:
+            raise NotFoundError(f"Folder #{folder_id} not found")
+
+        agent_count = len(folder.LibraryAgents) if folder.LibraryAgents else 0
+        subfolder_count = len(folder.Children) if folder.Children else 0
+
+        return library_model.LibraryFolder.from_db(
+            folder,
+            agent_count=agent_count,
+            subfolder_count=subfolder_count,
+        )
+
+    except prisma.errors.UniqueViolationError:
+        raise FolderValidationError(
+            "A folder with this name already exists in this location"
+        )
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error updating folder: {e}")
+        raise DatabaseError("Failed to update folder") from e
+
+
+async def move_folder(
+    folder_id: str,
+    user_id: str,
+    target_parent_id: Optional[str],
+) -> library_model.LibraryFolder:
+    """
+    Moves a folder to a new parent.
+
+    Args:
+        folder_id: The ID of the folder to move.
+        user_id: The ID of the user.
+        target_parent_id: The target parent ID (None for root).
+
+    Returns:
+        The moved LibraryFolder.
+
+    Raises:
+        FolderValidationError: If the move is invalid.
+        NotFoundError: If the folder doesn't exist.
+        DatabaseError: If there's a database error.
+    """
+    logger.debug(f"Moving folder #{folder_id} to parent #{target_parent_id}")
+
+    try:
+        # Validate operation
+        await validate_folder_operation(
+            folder_id=folder_id,
+            target_parent_id=target_parent_id,
+            user_id=user_id,
+        )
+
+        # Verify folder exists
+        existing = await prisma.models.LibraryFolder.prisma().find_first(
+            where={
+                "id": folder_id,
+                "userId": user_id,
+                "isDeleted": False,
+            }
+        )
+        if not existing:
+            raise NotFoundError(f"Folder #{folder_id} not found")
+
+        # Verify target parent exists if provided
+        if target_parent_id:
+            parent = await prisma.models.LibraryFolder.prisma().find_first(
+                where={
+                    "id": target_parent_id,
+                    "userId": user_id,
+                    "isDeleted": False,
+                }
+            )
+            if not parent:
+                raise NotFoundError(
+                    f"Target parent folder #{target_parent_id} not found"
+                )
+
+        folder = await prisma.models.LibraryFolder.prisma().update(
+            where={"id": folder_id},
+            data={
+                "parentId": target_parent_id,
+            },
+            include={
+                "LibraryAgents": {"where": {"isDeleted": False}},
+                "Children": {"where": {"isDeleted": False}},
+            },
+        )
+
+        if not folder:
+            raise NotFoundError(f"Folder #{folder_id} not found")
+
+        agent_count = len(folder.LibraryAgents) if folder.LibraryAgents else 0
+        subfolder_count = len(folder.Children) if folder.Children else 0
+
+        return library_model.LibraryFolder.from_db(
+            folder,
+            agent_count=agent_count,
+            subfolder_count=subfolder_count,
+        )
+
+    except prisma.errors.UniqueViolationError:
+        raise FolderValidationError(
+            "A folder with this name already exists in this location"
+        )
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error moving folder: {e}")
+        raise DatabaseError("Failed to move folder") from e
+
+
+async def delete_folder(
+    folder_id: str,
+    user_id: str,
+    soft_delete: bool = True,
+) -> None:
+    """
+    Deletes a folder and all its contents (cascade).
+
+    Args:
+        folder_id: The ID of the folder to delete.
+        user_id: The ID of the user.
+        soft_delete: If True, soft-deletes; otherwise hard-deletes.
+
+    Raises:
+        NotFoundError: If the folder doesn't exist.
+        DatabaseError: If there's a database error.
+    """
+    logger.debug(f"Deleting folder #{folder_id} for user #{user_id}")
+
+    try:
+        # Verify folder exists
+        existing = await prisma.models.LibraryFolder.prisma().find_first(
+            where={
+                "id": folder_id,
+                "userId": user_id,
+                "isDeleted": False,
+            }
+        )
+        if not existing:
+            raise NotFoundError(f"Folder #{folder_id} not found")
+
+        # Collect all folder IDs (target + descendants) before the transaction
+        async with transaction() as tx:
+            descendant_ids = await _get_descendant_folder_ids(folder_id, user_id, tx)
+        all_folder_ids = [folder_id] + descendant_ids
+
+        if soft_delete:
+            # Clean up schedules/webhooks for each affected agent before
+            # soft-deleting, matching what delete_library_agent() does.
+            affected_agents = await prisma.models.LibraryAgent.prisma().find_many(
+                where={
+                    "folderId": {"in": all_folder_ids},
+                    "userId": user_id,
+                    "isDeleted": False,
+                },
+            )
+            for agent in affected_agents:
+                try:
+                    await _cleanup_schedules_for_graph(
+                        graph_id=agent.agentGraphId, user_id=user_id
+                    )
+                    await _cleanup_webhooks_for_graph(
+                        graph_id=agent.agentGraphId, user_id=user_id
+                    )
+                except Exception as e:
+                    logger.warning(
+                        f"Cleanup failed for agent {agent.id} "
+                        f"(graph {agent.agentGraphId}): {e}"
+                    )
+
+        async with transaction() as tx:
+            if soft_delete:
+                # Soft-delete all agents in these folders
+                await prisma.models.LibraryAgent.prisma(tx).update_many(
+                    where={
+                        "folderId": {"in": all_folder_ids},
+                        "userId": user_id,
+                    },
+                    data={"isDeleted": True},
+                )
+
+                # Soft-delete all folders
+                await prisma.models.LibraryFolder.prisma(tx).update_many(
+                    where={
+                        "id": {"in": all_folder_ids},
+                        "userId": user_id,
+                    },
+                    data={"isDeleted": True},
+                )
+            else:
+                # Move agents to root (or could hard-delete them)
+                await prisma.models.LibraryAgent.prisma(tx).update_many(
+                    where={
+                        "folderId": {"in": all_folder_ids},
+                        "userId": user_id,
+                    },
+                    data={"folderId": None},
+                )
+
+                # Hard-delete folders (children first due to FK constraints)
+                for fid in reversed(all_folder_ids):
+                    await prisma.models.LibraryFolder.prisma(tx).delete(
+                        where={"id": fid}
+                    )
+
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error deleting folder: {e}")
+        raise DatabaseError("Failed to delete folder") from e
+
+
+async def _get_descendant_folder_ids(
+    folder_id: str,
+    user_id: str,
+    tx: Optional[prisma.Prisma] = None,
+) -> list[str]:
+    """
+    Recursively get all descendant folder IDs.
+
+    Args:
+        folder_id: The ID of the parent folder.
+        user_id: The ID of the user.
+        tx: Optional transaction.
+
+    Returns:
+        A list of descendant folder IDs.
+    """
+    prisma_client = prisma.models.LibraryFolder.prisma(tx)
+    children = await prisma_client.find_many(
+        where={
+            "parentId": folder_id,
+            "userId": user_id,
+            "isDeleted": False,
+        }
+    )
+
+    result: list[str] = []
+    for child in children:
+        result.append(child.id)
+        result.extend(await _get_descendant_folder_ids(child.id, user_id, tx))
+
+    return result
+
+
+async def move_agent_to_folder(
+    library_agent_id: str,
+    folder_id: Optional[str],
+    user_id: str,
+) -> library_model.LibraryAgent:
+    """
+    Moves a library agent to a folder.
+
+    Args:
+        library_agent_id: The ID of the library agent.
+        folder_id: The target folder ID (None for root).
+        user_id: The ID of the user.
+
+    Returns:
+        The updated LibraryAgent.
+
+    Raises:
+        NotFoundError: If the agent or folder doesn't exist.
+        DatabaseError: If there's a database error.
+    """
+    logger.debug(f"Moving agent #{library_agent_id} to folder #{folder_id}")
+
+    try:
+        # Verify agent exists
+        agent = await prisma.models.LibraryAgent.prisma().find_first(
+            where={
+                "id": library_agent_id,
+                "userId": user_id,
+                "isDeleted": False,
+            }
+        )
+        if not agent:
+            raise NotFoundError(f"Library agent #{library_agent_id} not found")
+
+        # Verify folder exists if provided
+        if folder_id:
+            folder = await prisma.models.LibraryFolder.prisma().find_first(
+                where={
+                    "id": folder_id,
+                    "userId": user_id,
+                    "isDeleted": False,
+                }
+            )
+            if not folder:
+                raise NotFoundError(f"Folder #{folder_id} not found")
+
+        await prisma.models.LibraryAgent.prisma().update(
+            where={"id": library_agent_id},
+            data={"folderId": folder_id},
+        )
+
+        return await get_library_agent(library_agent_id, user_id)
+
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error moving agent to folder: {e}")
+        raise DatabaseError("Failed to move agent to folder") from e
+
+
+async def bulk_move_agents_to_folder(
+    agent_ids: list[str],
+    folder_id: Optional[str],
+    user_id: str,
+) -> list[library_model.LibraryAgent]:
+    """
+    Moves multiple library agents to a folder.
+
+    Args:
+        agent_ids: The IDs of the library agents.
+        folder_id: The target folder ID (None for root).
+        user_id: The ID of the user.
+
+    Returns:
+        The updated LibraryAgents.
+
+    Raises:
+        NotFoundError: If any agent or the folder doesn't exist.
+        DatabaseError: If there's a database error.
+    """
+    logger.debug(f"Bulk moving {len(agent_ids)} agents to folder #{folder_id}")
+
+    try:
+        # Verify folder exists if provided
+        if folder_id:
+            folder = await prisma.models.LibraryFolder.prisma().find_first(
+                where={
+                    "id": folder_id,
+                    "userId": user_id,
+                    "isDeleted": False,
+                }
+            )
+            if not folder:
+                raise NotFoundError(f"Folder #{folder_id} not found")
+
+        # Update all agents
+        await prisma.models.LibraryAgent.prisma().update_many(
+            where={
+                "id": {"in": agent_ids},
+                "userId": user_id,
+                "isDeleted": False,
+            },
+            data={"folderId": folder_id},
+        )
+
+        # Fetch and return updated agents
+        agents = await prisma.models.LibraryAgent.prisma().find_many(
+            where={
+                "id": {"in": agent_ids},
+                "userId": user_id,
+            },
+            include=library_agent_include(
+                user_id, include_nodes=False, include_executions=False
+            ),
+        )
+
+        return [library_model.LibraryAgent.from_db(agent) for agent in agents]
+
+    except prisma.errors.PrismaError as e:
+        logger.error(f"Database error bulk moving agents to folder: {e}")
+        raise DatabaseError("Failed to bulk move agents to folder") from e
+
+
 ##############################################
 ########### Presets DB Functions #############
 ##############################################

autogpt_platform/backend/backend/api/features/library/exceptions.py

@@ -0,0 +1,4 @@
+class FolderValidationError(Exception):
+    """Raised when folder operations fail validation."""
+
+    pass

autogpt_platform/backend/backend/api/features/library/model.py

@@ -26,6 +26,95 @@ class LibraryAgentStatus(str, Enum):
     ERROR = "ERROR"
 
 
+# === Folder Models ===
+
+
+class LibraryFolder(pydantic.BaseModel):
+    """Represents a folder for organizing library agents."""
+
+    id: str
+    user_id: str
+    name: str
+    icon: str | None = None
+    color: str | None = None
+    parent_id: str | None = None
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+    agent_count: int = 0  # Direct agents in folder
+    subfolder_count: int = 0  # Direct child folders
+
+    @staticmethod
+    def from_db(
+        folder: prisma.models.LibraryFolder,
+        agent_count: int = 0,
+        subfolder_count: int = 0,
+    ) -> "LibraryFolder":
+        """Factory method that constructs a LibraryFolder from a Prisma model."""
+        return LibraryFolder(
+            id=folder.id,
+            user_id=folder.userId,
+            name=folder.name,
+            icon=folder.icon,
+            color=folder.color,
+            parent_id=folder.parentId,
+            created_at=folder.createdAt,
+            updated_at=folder.updatedAt,
+            agent_count=agent_count,
+            subfolder_count=subfolder_count,
+        )
+
+
+class LibraryFolderTree(LibraryFolder):
+    """Folder with nested children for tree view."""
+
+    children: list["LibraryFolderTree"] = []
+
+
+class FolderCreateRequest(pydantic.BaseModel):
+    """Request model for creating a folder."""
+
+    name: str = pydantic.Field(..., min_length=1, max_length=100)
+    icon: str | None = None
+    color: str | None = pydantic.Field(
+        None, pattern=r"^#[0-9A-Fa-f]{6}$", description="Hex color code (#RRGGBB)"
+    )
+    parent_id: str | None = None
+
+
+class FolderUpdateRequest(pydantic.BaseModel):
+    """Request model for updating a folder."""
+
+    name: str | None = pydantic.Field(None, min_length=1, max_length=100)
+    icon: str | None = None
+    color: str | None = None
+
+
+class FolderMoveRequest(pydantic.BaseModel):
+    """Request model for moving a folder to a new parent."""
+
+    target_parent_id: str | None = None  # None = move to root
+
+
+class BulkMoveAgentsRequest(pydantic.BaseModel):
+    """Request model for moving multiple agents to a folder."""
+
+    agent_ids: list[str]
+    folder_id: str | None = None  # None = move to root
+
+
+class FolderListResponse(pydantic.BaseModel):
+    """Response schema for a list of folders."""
+
+    folders: list[LibraryFolder]
+    pagination: Pagination
+
+
+class FolderTreeResponse(pydantic.BaseModel):
+    """Response schema for folder tree structure."""
+
+    tree: list[LibraryFolderTree]
+
+
 class MarketplaceListingCreator(pydantic.BaseModel):
     """Creator information for a marketplace listing."""
 
@@ -120,6 +209,9 @@ class LibraryAgent(pydantic.BaseModel):
     can_access_graph: bool
     is_latest_version: bool
     is_favorite: bool
+    folder_id: str | None = None
+    folder_name: str | None = None  # Denormalized for display
+
     recommended_schedule_cron: str | None = None
     settings: GraphSettings = pydantic.Field(default_factory=GraphSettings)
     marketplace_listing: Optional["MarketplaceListing"] = None
@@ -228,6 +320,10 @@ class LibraryAgent(pydantic.BaseModel):
                 creator=creator_data,
             )
 
+        # Folder information
+        folder_id = agent.folderId
+        folder_name = agent.Folder.name if agent.Folder else None
+
         return LibraryAgent(
             id=agent.id,
             graph_id=agent.agentGraphId,
@@ -259,6 +355,8 @@ class LibraryAgent(pydantic.BaseModel):
             can_access_graph=can_access_graph,
             is_latest_version=is_latest_version,
             is_favorite=agent.isFavorite,
+            folder_id=folder_id,
+            folder_name=folder_name,
             recommended_schedule_cron=agent.AgentGraph.recommendedScheduleCron,
             settings=_parse_settings(agent.settings),
             marketplace_listing=marketplace_listing_data,
@@ -470,3 +568,7 @@ class LibraryAgentUpdateRequest(pydantic.BaseModel):
     settings: Optional[GraphSettings] = pydantic.Field(
         default=None, description="User-specific settings for this library agent"
     )
+    folder_id: Optional[str] = pydantic.Field(
+        default=None,
+        description="Folder ID to move agent to (empty string for root)",
+    )

autogpt_platform/backend/backend/api/features/library/routes/__init__.py

@@ -1,9 +1,11 @@
 import fastapi
 
 from .agents import router as agents_router
+from .folders import router as folders_router
 from .presets import router as presets_router
 
 router = fastapi.APIRouter()
 
 router.include_router(presets_router)
+router.include_router(folders_router)
 router.include_router(agents_router)

autogpt_platform/backend/backend/api/features/library/routes/agents.py

@@ -41,17 +41,34 @@ async def list_library_agents(
         ge=1,
         description="Number of agents per page (must be >= 1)",
     ),
+    folder_id: Optional[str] = Query(
+        None,
+        description="Filter by folder ID",
+    ),
+    include_root_only: bool = Query(
+        False,
+        description="Only return agents without a folder (root-level agents)",
+    ),
 ) -> library_model.LibraryAgentResponse:
     """
     Get all agents in the user's library (both created and saved).
     """
-    return await library_db.list_library_agents(
-        user_id=user_id,
-        search_term=search_term,
-        sort_by=sort_by,
-        page=page,
-        page_size=page_size,
-    )
+    try:
+        return await library_db.list_library_agents(
+            user_id=user_id,
+            search_term=search_term,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            folder_id=folder_id,
+            include_root_only=include_root_only,
+        )
+    except Exception as e:
+        logger.error(f"Could not list library agents for user #{user_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=str(e),
+        ) from e
 
 
 @router.get(
@@ -160,15 +177,38 @@ async def update_library_agent(
     """
     Update the library agent with the given fields.
     """
-    return await library_db.update_library_agent(
-        library_agent_id=library_agent_id,
-        user_id=user_id,
-        auto_update_version=payload.auto_update_version,
-        graph_version=payload.graph_version,
-        is_favorite=payload.is_favorite,
-        is_archived=payload.is_archived,
-        settings=payload.settings,
-    )
+    try:
+        return await library_db.update_library_agent(
+            library_agent_id=library_agent_id,
+            user_id=user_id,
+            auto_update_version=payload.auto_update_version,
+            graph_version=payload.graph_version,
+            is_favorite=payload.is_favorite,
+            is_archived=payload.is_archived,
+            settings=payload.settings,
+            folder_id=payload.folder_id,
+        )
+    except NotFoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    except DatabaseError as e:
+        logger.error(
+            f"Database error while updating library agent: {e}", exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"message": "Internal server error", "hint": "Contact support"},
+        ) from e
+    except Exception as e:
+        logger.error(
+            f"Unexpected error while updating library agent: {e}", exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={"message": "Internal server error", "hint": "Contact support"},
+        ) from e
 
 
 @router.delete(

autogpt_platform/backend/backend/api/features/library/routes/folders.py

@@ -0,0 +1,408 @@
+import logging
+from typing import Optional
+
+import autogpt_libs.auth as autogpt_auth_lib
+from fastapi import APIRouter, HTTPException, Query, Security, status
+from fastapi.responses import Response
+
+from backend.util.exceptions import DatabaseError, NotFoundError
+
+from .. import db as library_db
+from .. import model as library_model
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+    prefix="/folders",
+    tags=["library", "folders", "private"],
+    dependencies=[Security(autogpt_auth_lib.requires_user)],
+)
+
+
+@router.get(
+    "",
+    summary="List Library Folders",
+    response_model=library_model.FolderListResponse,
+    responses={
+        200: {"description": "List of folders"},
+        500: {"description": "Server error"},
+    },
+)
+async def list_folders(
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+    parent_id: Optional[str] = Query(
+        None,
+        description="Filter by parent folder ID. If not provided, returns root-level folders.",
+    ),
+    include_counts: bool = Query(
+        True,
+        description="Include agent and subfolder counts",
+    ),
+) -> library_model.FolderListResponse:
+    """
+    List folders for the authenticated user.
+
+    Args:
+        user_id: ID of the authenticated user.
+        parent_id: Optional parent folder ID to filter by.
+        include_counts: Whether to include agent and subfolder counts.
+
+    Returns:
+        A FolderListResponse containing folders.
+    """
+    try:
+        folders = await library_db.list_folders(
+            user_id=user_id,
+            parent_id=parent_id,
+            include_counts=include_counts,
+        )
+        return library_model.FolderListResponse(
+            folders=folders,
+            pagination=library_model.Pagination(
+                total_items=len(folders),
+                total_pages=1,
+                current_page=1,
+                page_size=len(folders),
+            ),
+        )
+    except Exception as e:
+        logger.error(f"Could not list folders for user #{user_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e
+
+
+@router.get(
+    "/tree",
+    summary="Get Folder Tree",
+    response_model=library_model.FolderTreeResponse,
+    responses={
+        200: {"description": "Folder tree structure"},
+        500: {"description": "Server error"},
+    },
+)
+async def get_folder_tree(
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.FolderTreeResponse:
+    """
+    Get the full folder tree for the authenticated user.
+
+    Args:
+        user_id: ID of the authenticated user.
+
+    Returns:
+        A FolderTreeResponse containing the nested folder structure.
+    """
+    try:
+        tree = await library_db.get_folder_tree(user_id=user_id)
+        return library_model.FolderTreeResponse(tree=tree)
+    except Exception as e:
+        logger.error(f"Could not get folder tree for user #{user_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e
+
+
+@router.get(
+    "/{folder_id}",
+    summary="Get Folder",
+    response_model=library_model.LibraryFolder,
+    responses={
+        200: {"description": "Folder details"},
+        404: {"description": "Folder not found"},
+        500: {"description": "Server error"},
+    },
+)
+async def get_folder(
+    folder_id: str,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Get a specific folder.
+
+    Args:
+        folder_id: ID of the folder to retrieve.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The requested LibraryFolder.
+    """
+    try:
+        return await library_db.get_folder(folder_id=folder_id, user_id=user_id)
+    except NotFoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    except Exception as e:
+        logger.error(f"Could not get folder #{folder_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e
+
+
+@router.post(
+    "",
+    summary="Create Folder",
+    status_code=status.HTTP_201_CREATED,
+    response_model=library_model.LibraryFolder,
+    responses={
+        201: {"description": "Folder created successfully"},
+        400: {"description": "Validation error"},
+        404: {"description": "Parent folder not found"},
+        409: {"description": "Folder name conflict"},
+        500: {"description": "Server error"},
+    },
+)
+async def create_folder(
+    payload: library_model.FolderCreateRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Create a new folder.
+
+    Args:
+        payload: The folder creation request.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The created LibraryFolder.
+    """
+    try:
+        return await library_db.create_folder(
+            user_id=user_id,
+            name=payload.name,
+            parent_id=payload.parent_id,
+            icon=payload.icon,
+            color=payload.color,
+        )
+    except library_db.FolderValidationError as e:
+        if "already exists" in str(e):
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=str(e),
+            ) from e
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+    except NotFoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    except DatabaseError as e:
+        logger.error(f"Database error creating folder: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e
+
+
+@router.patch(
+    "/{folder_id}",
+    summary="Update Folder",
+    response_model=library_model.LibraryFolder,
+    responses={
+        200: {"description": "Folder updated successfully"},
+        400: {"description": "Validation error"},
+        404: {"description": "Folder not found"},
+        409: {"description": "Folder name conflict"},
+        500: {"description": "Server error"},
+    },
+)
+async def update_folder(
+    folder_id: str,
+    payload: library_model.FolderUpdateRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Update a folder's properties.
+
+    Args:
+        folder_id: ID of the folder to update.
+        payload: The folder update request.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The updated LibraryFolder.
+    """
+    try:
+        return await library_db.update_folder(
+            folder_id=folder_id,
+            user_id=user_id,
+            name=payload.name,
+            icon=payload.icon,
+            color=payload.color,
+        )
+    except library_db.FolderValidationError as e:
+        if "already exists" in str(e):
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=str(e),
+            ) from e
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+    except NotFoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    except DatabaseError as e:
+        logger.error(f"Database error updating folder #{folder_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e
+
+
+@router.post(
+    "/{folder_id}/move",
+    summary="Move Folder",
+    response_model=library_model.LibraryFolder,
+    responses={
+        200: {"description": "Folder moved successfully"},
+        400: {"description": "Validation error (circular reference, depth exceeded)"},
+        404: {"description": "Folder or target parent not found"},
+        409: {"description": "Folder name conflict in target location"},
+        500: {"description": "Server error"},
+    },
+)
+async def move_folder(
+    folder_id: str,
+    payload: library_model.FolderMoveRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Move a folder to a new parent.
+
+    Args:
+        folder_id: ID of the folder to move.
+        payload: The move request with target parent.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The moved LibraryFolder.
+    """
+    try:
+        return await library_db.move_folder(
+            folder_id=folder_id,
+            user_id=user_id,
+            target_parent_id=payload.target_parent_id,
+        )
+    except library_db.FolderValidationError as e:
+        if "already exists" in str(e):
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=str(e),
+            ) from e
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+    except NotFoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    except DatabaseError as e:
+        logger.error(f"Database error moving folder #{folder_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e
+
+
+@router.delete(
+    "/{folder_id}",
+    summary="Delete Folder",
+    status_code=status.HTTP_204_NO_CONTENT,
+    responses={
+        204: {"description": "Folder deleted successfully"},
+        404: {"description": "Folder not found"},
+        500: {"description": "Server error"},
+    },
+)
+async def delete_folder(
+    folder_id: str,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> Response:
+    """
+    Soft-delete a folder and all its contents.
+
+    Args:
+        folder_id: ID of the folder to delete.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        204 No Content if successful.
+    """
+    try:
+        await library_db.delete_folder(
+            folder_id=folder_id,
+            user_id=user_id,
+            soft_delete=True,
+        )
+        return Response(status_code=status.HTTP_204_NO_CONTENT)
+    except NotFoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    except DatabaseError as e:
+        logger.error(f"Database error deleting folder #{folder_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e
+
+
+# === Bulk Agent Operations ===
+
+
+@router.post(
+    "/agents/bulk-move",
+    summary="Bulk Move Agents",
+    response_model=list[library_model.LibraryAgent],
+    responses={
+        200: {"description": "Agents moved successfully"},
+        404: {"description": "Folder not found"},
+        500: {"description": "Server error"},
+    },
+)
+async def bulk_move_agents(
+    payload: library_model.BulkMoveAgentsRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> list[library_model.LibraryAgent]:
+    """
+    Move multiple agents to a folder.
+
+    Args:
+        payload: The bulk move request with agent IDs and target folder.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The updated LibraryAgents.
+    """
+    try:
+        return await library_db.bulk_move_agents_to_folder(
+            agent_ids=payload.agent_ids,
+            folder_id=payload.folder_id,
+            user_id=user_id,
+        )
+    except NotFoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(e),
+        ) from e
+    except DatabaseError as e:
+        logger.error(f"Database error bulk moving agents: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e

autogpt_platform/backend/backend/data/includes.py

@@ -105,6 +105,7 @@ def library_agent_include(
     """
     result: prisma.types.LibraryAgentInclude = {
         "Creator": True,  # Always needed for creator info
+        "Folder": True,  # Always needed for folder info
     }
 
     # Build AgentGraph include based on requested options

autogpt_platform/backend/migrations/20260123110033_add_folders_in_library/migration.sql

@@ -0,0 +1,50 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `search` on the `StoreListingVersion` table. All the data in the column will be lost.
+
+*/
+-- DropIndex
+DROP INDEX "UnifiedContentEmbedding_search_idx";
+
+-- AlterTable
+ALTER TABLE "LibraryAgent" ADD COLUMN     "folderId" TEXT;
+
+-- AlterTable
+ALTER TABLE "StoreListingVersion" DROP COLUMN "search";
+
+-- CreateTable
+CREATE TABLE "LibraryFolder" (
+    "id" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "userId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "icon" TEXT,
+    "color" TEXT,
+    "parentId" TEXT,
+    "isDeleted" BOOLEAN NOT NULL DEFAULT false,
+
+    CONSTRAINT "LibraryFolder_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "LibraryFolder_userId_isDeleted_idx" ON "LibraryFolder"("userId", "isDeleted");
+
+-- CreateIndex
+CREATE INDEX "LibraryFolder_parentId_idx" ON "LibraryFolder"("parentId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "LibraryFolder_userId_parentId_name_key" ON "LibraryFolder"("userId", "parentId", "name");
+
+-- CreateIndex
+CREATE INDEX "LibraryAgent_folderId_idx" ON "LibraryAgent"("folderId");
+
+-- AddForeignKey
+ALTER TABLE "LibraryAgent" ADD CONSTRAINT "LibraryAgent_folderId_fkey" FOREIGN KEY ("folderId") REFERENCES "LibraryFolder"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "LibraryFolder" ADD CONSTRAINT "LibraryFolder_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "LibraryFolder" ADD CONSTRAINT "LibraryFolder_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "LibraryFolder"("id") ON DELETE CASCADE ON UPDATE CASCADE;

autogpt_platform/backend/schema.prisma

@@ -51,6 +51,7 @@ model User {
   ChatSessions         ChatSession[]
   AgentPresets         AgentPreset[]
   LibraryAgents        LibraryAgent[]
+  LibraryFolders       LibraryFolder[]
 
   Profile               Profile[]
   UserOnboarding        UserOnboarding?
@@ -395,6 +396,9 @@ model LibraryAgent {
   creatorId String?
   Creator   Profile? @relation(fields: [creatorId], references: [id])
 
+  folderId String?
+  Folder   LibraryFolder? @relation(fields: [folderId], references: [id], onDelete: Restrict)
+
   useGraphIsActiveVersion Boolean @default(false)
 
   isFavorite      Boolean @default(false)
@@ -407,6 +411,32 @@ model LibraryAgent {
   @@unique([userId, agentGraphId, agentGraphVersion])
   @@index([agentGraphId, agentGraphVersion])
   @@index([creatorId])
+  @@index([folderId])
+}
+
+model LibraryFolder {
+  id        String   @id @default(uuid())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @default(now()) @updatedAt
+
+  userId String
+  User   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  name  String
+  icon  String?
+  color String?
+
+  parentId String?
+  Parent   LibraryFolder?  @relation("FolderHierarchy", fields: [parentId], references: [id], onDelete: Cascade)
+  Children LibraryFolder[] @relation("FolderHierarchy")
+
+  isDeleted Boolean @default(false)
+
+  LibraryAgents LibraryAgent[]
+
+  @@unique([userId, parentId, name]) // Name unique per parent per user
+  @@index([userId, isDeleted])
+  @@index([parentId])
 }
 
 ////////////////////////////////////////////////////////////

autogpt_platform/frontend/package.json

@@ -32,6 +32,7 @@
   "dependencies": {
     "@ai-sdk/react": "3.0.61",
     "@faker-js/faker": "10.0.0",
+    "@ferrucc-io/emoji-picker": "0.0.48",
     "@hookform/resolvers": "5.2.2",
     "@next/third-parties": "15.4.6",
     "@phosphor-icons/react": "2.1.10",

autogpt_platform/frontend/pnpm-lock.yaml

@@ -18,6 +18,9 @@ importers:
       '@faker-js/faker':
         specifier: 10.0.0
         version: 10.0.0
+      '@ferrucc-io/emoji-picker':
+        specifier: 0.0.48
+        version: 0.0.48(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(tailwindcss@3.4.17)
       '@hookform/resolvers':
         specifier: 5.2.2
         version: 5.2.2(react-hook-form@7.66.0(react@18.3.1))
@@ -1507,6 +1510,14 @@ packages:
     resolution: {integrity: sha512-UollFEUkVXutsaP+Vndjxar40Gs5JL2HeLcl8xO1QAjJgOdhc3OmBFWyEylS+RddWaaBiAzH+5/17PLQJwDiLw==}
     engines: {node: ^20.19.0 || ^22.13.0 || ^23.5.0 || >=24.0.0, npm: '>=10'}
 
+  '@ferrucc-io/emoji-picker@0.0.48':
+    resolution: {integrity: sha512-DJ5u+6VLF9OK7x+S/luwrVb5CHC6W16jL5b8vBUYNpxKWSuFgyliDHVtw1SGe6+dr5RUbf8WQwPJdKZmU3Ittg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      react: ^18.2.0 || ^19.0.0
+      react-dom: ^18.2.0 || ^19.0.0
+      tailwindcss: '>=3.0.0'
+
   '@floating-ui/core@1.7.3':
     resolution: {integrity: sha512-sGnvb5dmrJaKEZ+LDIpguvdX3bDlEllmv4/ClQ9awcmCZrlx5jQyyMWFM5kBI+EyNOCDDiKk8il0zeuX3Zlg/w==}
 
@@ -3114,6 +3125,10 @@ packages:
   '@shikijs/vscode-textmate@10.0.2':
     resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
 
+  '@sindresorhus/is@4.6.0':
+    resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
+    engines: {node: '>=10'}
+
   '@standard-schema/spec@1.0.0':
     resolution: {integrity: sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA==}
 
@@ -3381,10 +3396,19 @@ packages:
       react: '>=16.8'
       react-dom: '>=16.8'
 
+  '@tanstack/react-virtual@3.13.18':
+    resolution: {integrity: sha512-dZkhyfahpvlaV0rIKnvQiVoWPyURppl6w4m9IwMDpuIjcJ1sD9YGWrt0wISvgU7ewACXx2Ct46WPgI6qAD4v6A==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   '@tanstack/table-core@8.21.3':
     resolution: {integrity: sha512-ldZXEhOBb8Is7xLs01fR3YEc3DERiz5silj8tnGkFZytt1abEvl/GhUmCE0PMLaMPTa3Jk4HbKmRlHmu+gCftg==}
     engines: {node: '>=12'}
 
+  '@tanstack/virtual-core@3.13.18':
+    resolution: {integrity: sha512-Mx86Hqu1k39icq2Zusq+Ey2J6dDWTjDvEv43PJtRCoEYTLyfaPnxIQ6iy7YAOK0NV/qOEmZQ/uCufrppZxTgcg==}
+
   '@testing-library/dom@10.4.1':
     resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
     engines: {node: '>=18'}
@@ -4378,6 +4402,10 @@ packages:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
+  char-regex@1.0.2:
+    resolution: {integrity: sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==}
+    engines: {node: '>=10'}
+
   character-entities-html4@2.1.0:
     resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
 
@@ -4995,6 +5023,9 @@ packages:
   emoji-regex@9.2.2:
     resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
 
+  emojilib@2.4.0:
+    resolution: {integrity: sha512-5U0rVMU5Y2n2+ykNLQqMoqklN9ICBT/KsvC1Gz6vqHbz2AXXGkG+Pm5rMWk/8Vjrr/mY9985Hi8DYzn1F09Nyw==}
+
   emojis-list@3.0.0:
     resolution: {integrity: sha512-/kyM18EfinwXZbno9FyUGeFh87KC8HRQBQGildHZbEuRyWFOmv1U10o9BBp8XVZDVNNuQKyIGIu5ZYAAXJ0V2Q==}
     engines: {node: '>= 4'}
@@ -5975,6 +6006,24 @@ packages:
     resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
     hasBin: true
 
+  jotai@2.17.1:
+    resolution: {integrity: sha512-TFNZZDa/0ewCLQyRC/Sq9crtixNj/Xdf/wmj9631xxMuKToVJZDbqcHIYN0OboH+7kh6P6tpIK7uKWClj86PKw==}
+    engines: {node: '>=12.20.0'}
+    peerDependencies:
+      '@babel/core': '>=7.0.0'
+      '@babel/template': '>=7.0.0'
+      '@types/react': '>=17.0.0'
+      react: '>=17.0.0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      '@babel/template':
+        optional: true
+      '@types/react':
+        optional: true
+      react:
+        optional: true
+
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
@@ -6593,6 +6642,10 @@ packages:
   node-abort-controller@3.1.1:
     resolution: {integrity: sha512-AGK2yQKIjRuqnc6VkX2Xj5d+QW8xZ87pa1UK6yA6ouUyuxfHuMP6umE5QK7UmTeOAymo+Zx1Fxiuw9rVx8taHQ==}
 
+  node-emoji@2.2.0:
+    resolution: {integrity: sha512-Z3lTE9pLaJF47NyMhd4ww1yFTAP8YhYI8SleJiHzM46Fgpm5cnNzSl9XfzFNqbaz+VlJrIj3fXQ4DeN1Rjm6cw==}
+    engines: {node: '>=18'}
+
   node-fetch-h2@2.3.0:
     resolution: {integrity: sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==}
     engines: {node: 4.x || >=6.0.0}
@@ -7691,6 +7744,10 @@ packages:
     resolution: {integrity: sha512-LH7FpTAkeD+y5xQC4fzS+tFtaNlvt3Ib1zKzvhjv/Y+cioV4zIuw4IZr2yhRLu67CWL7FR9/6KXKnjRoZTvGGQ==}
     engines: {node: '>=12'}
 
+  skin-tone@2.0.0:
+    resolution: {integrity: sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA==}
+    engines: {node: '>=8'}
+
   slash@3.0.0:
     resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
     engines: {node: '>=8'}
@@ -8168,6 +8225,13 @@ packages:
     resolution: {integrity: sha512-dA8WbNeb2a6oQzAQ55YlT5vQAWGV9WXOsi3SskE3bcCdM0P4SDd+24zS/OCacdRq5BkdsRj9q3Pg6YyQoxIGqg==}
     engines: {node: '>=4'}
 
+  unicode-emoji-json@0.8.0:
+    resolution: {integrity: sha512-3wDXXvp6YGoKGhS2O2H7+V+bYduOBydN1lnI0uVfr1cIdY02uFFiEH1i3kE5CCE4l6UqbLKVmEFW9USxTAMD1g==}
+
+  unicode-emoji-modifier-base@1.0.0:
+    resolution: {integrity: sha512-yLSH4py7oFH3oG/9K+XWrz1pSi3dfUrWEnInbxMfArOfc1+33BlGPQtLsOYwvdMy11AwUBetYuaRxSPqgkq+8g==}
+    engines: {node: '>=4'}
+
   unicode-match-property-ecmascript@2.0.0:
     resolution: {integrity: sha512-5kaZCrbp5mmbz5ulBkDkbY0SsPOjKqVS35VpL9ulMPfSl0J0Xsm+9Evphv9CoIZFwre7aJoa94AY6seMKGVN5Q==}
     engines: {node: '>=4'}
@@ -9777,6 +9841,22 @@ snapshots:
 
   '@faker-js/faker@10.0.0': {}
 
+  '@ferrucc-io/emoji-picker@0.0.48(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(tailwindcss@3.4.17)':
+    dependencies:
+      '@tanstack/react-virtual': 3.13.18(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      clsx: 2.1.1
+      jotai: 2.17.1(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react@18.3.1)
+      node-emoji: 2.2.0
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      tailwind-merge: 2.6.0
+      tailwindcss: 3.4.17
+      unicode-emoji-json: 0.8.0
+    transitivePeerDependencies:
+      - '@babel/core'
+      - '@babel/template'
+      - '@types/react'
+
   '@floating-ui/core@1.7.3':
     dependencies:
       '@floating-ui/utils': 0.2.10
@@ -11538,6 +11618,8 @@ snapshots:
 
   '@shikijs/vscode-textmate@10.0.2': {}
 
+  '@sindresorhus/is@4.6.0': {}
+
   '@standard-schema/spec@1.0.0': {}
 
   '@standard-schema/spec@1.1.0': {}
@@ -12011,8 +12093,16 @@ snapshots:
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
 
+  '@tanstack/react-virtual@3.13.18(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@tanstack/virtual-core': 3.13.18
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
   '@tanstack/table-core@8.21.3': {}
 
+  '@tanstack/virtual-core@3.13.18': {}
+
   '@testing-library/dom@10.4.1':
     dependencies:
       '@babel/code-frame': 7.27.1
@@ -13104,6 +13194,8 @@ snapshots:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
+  char-regex@1.0.2: {}
+
   character-entities-html4@2.1.0: {}
 
   character-entities-legacy@3.0.0: {}
@@ -13747,6 +13839,8 @@ snapshots:
 
   emoji-regex@9.2.2: {}
 
+  emojilib@2.4.0: {}
+
   emojis-list@3.0.0: {}
 
   endent@2.1.0:
@@ -15028,6 +15122,13 @@ snapshots:
 
   jiti@2.6.1: {}
 
+  jotai@2.17.1(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react@18.3.1):
+    optionalDependencies:
+      '@babel/core': 7.28.5
+      '@babel/template': 7.27.2
+      '@types/react': 18.3.17
+      react: 18.3.1
+
   js-tokens@4.0.0: {}
 
   js-yaml@4.1.0:
@@ -15896,6 +15997,13 @@ snapshots:
 
   node-abort-controller@3.1.1: {}
 
+  node-emoji@2.2.0:
+    dependencies:
+      '@sindresorhus/is': 4.6.0
+      char-regex: 1.0.2
+      emojilib: 2.4.0
+      skin-tone: 2.0.0
+
   node-fetch-h2@2.3.0:
     dependencies:
       http2-client: 1.3.5
@@ -17196,6 +17304,10 @@ snapshots:
     dependencies:
       jsep: 1.4.0
 
+  skin-tone@2.0.0:
+    dependencies:
+      unicode-emoji-modifier-base: 1.0.0
+
   slash@3.0.0: {}
 
   sonner@2.0.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
@@ -17711,6 +17823,10 @@ snapshots:
 
   unicode-canonical-property-names-ecmascript@2.0.1: {}
 
+  unicode-emoji-json@0.8.0: {}
+
+  unicode-emoji-modifier-base@1.0.0: {}
+
   unicode-match-property-ecmascript@2.0.0:
     dependencies:
       unicode-canonical-property-names-ecmascript: 2.0.1

autogpt_platform/frontend/src/app/(platform)/library/components/FavoritesSection/FavoritesSection.tsx

@@ -1,17 +1,25 @@
 "use client";
 
 import { LibraryAgent } from "@/app/api/__generated__/models/libraryAgent";
+import { LibraryAgentSort } from "@/app/api/__generated__/models/libraryAgentSort";
 import { Text } from "@/components/atoms/Text/Text";
+import { LoadingSpinner } from "@/components/atoms/LoadingSpinner/LoadingSpinner";
 import { InfiniteScroll } from "@/components/contextual/InfiniteScroll/InfiniteScroll";
 import { HeartIcon } from "@phosphor-icons/react";
 import { useFavoriteAgents } from "../../hooks/useFavoriteAgents";
 import { LibraryAgentCard } from "../LibraryAgentCard/LibraryAgentCard";
+import { LibraryTabs, Tab } from "../LibraryTabs/LibraryTabs";
+import { LibraryActionSubHeader } from "../LibraryActionSubHeader/LibraryActionSubHeader";
 
 interface Props {
   searchTerm: string;
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
+  setLibrarySort: (value: LibraryAgentSort) => void;
 }
 
-export function FavoritesSection({ searchTerm }: Props) {
+export function FavoritesSection({ searchTerm, tabs, activeTab, onTabChange, setLibrarySort }: Props) {
   const {
     allAgents: favoriteAgents,
     agentLoading: isLoading,
@@ -21,38 +29,26 @@ export function FavoritesSection({ searchTerm }: Props) {
     isFetchingNextPage,
   } = useFavoriteAgents({ searchTerm });
 
-  if (isLoading || favoriteAgents.length === 0) {
-    return null;
-  }
-
   return (
-    <div className="!mb-8">
-      <div className="mb-3 flex items-center gap-2 p-2">
-        <HeartIcon className="h-5 w-5" weight="fill" />
-        <div className="flex items-baseline gap-2">
-          <Text variant="h4">Favorites</Text>
-          {!isLoading && (
-            <Text
-              variant="body"
-              data-testid="agents-count"
-              className="relative bottom-px text-zinc-500"
-            >
-              {agentCount}
-            </Text>
-          )}
-        </div>
-      </div>
+    <>
+      <LibraryActionSubHeader agentCount={agentCount} setLibrarySort={setLibrarySort} />
+      <LibraryTabs tabs={tabs} activeTab={activeTab} onTabChange={onTabChange} />
 
-      <div className="relative">
+      {isLoading ? (
+        <div className="flex h-[200px] items-center justify-center">
+          <LoadingSpinner size="large" />
+        </div>
+      ) : favoriteAgents.length === 0 ? (
+        <div className="flex h-[200px] flex-col items-center justify-center gap-2 text-zinc-500">
+          <HeartIcon className="h-10 w-10" />
+          <Text variant="body">No favorite agents yet</Text>
+        </div>
+      ) : (
         <InfiniteScroll
           isFetchingNextPage={isFetchingNextPage}
           fetchNextPage={fetchNextPage}
           hasNextPage={hasNextPage}
-          loader={
-            <div className="flex h-8 w-full items-center justify-center">
-              <div className="h-6 w-6 animate-spin rounded-full border-b-2 border-t-2 border-neutral-800" />
-            </div>
-          }
+          loader={<LoadingSpinner size="medium" />}
         >
           <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
             {favoriteAgents.map((agent: LibraryAgent) => (
@@ -60,9 +56,7 @@ export function FavoritesSection({ searchTerm }: Props) {
             ))}
           </div>
         </InfiniteScroll>
-      </div>
-
-      {favoriteAgents.length > 0 && <div className="!mt-10 border-t" />}
-    </div>
+      )}
+    </>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/FlyingHeart/FlyingHeart.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { motion, AnimatePresence } from "framer-motion";
+import { HeartIcon } from "@phosphor-icons/react";
+import { useEffect, useState } from "react";
+
+interface FlyingHeartProps {
+  startPosition: { x: number; y: number } | null;
+  targetPosition: { x: number; y: number } | null;
+  onAnimationComplete: () => void;
+}
+
+export function FlyingHeart({
+  startPosition,
+  targetPosition,
+  onAnimationComplete,
+}: FlyingHeartProps) {
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    if (startPosition && targetPosition) {
+      setIsVisible(true);
+    }
+  }, [startPosition, targetPosition]);
+
+  if (!startPosition || !targetPosition) return null;
+
+  return (
+    <AnimatePresence>
+      {isVisible && (
+        <motion.div
+          className="pointer-events-none fixed z-50"
+          initial={{
+            x: startPosition.x,
+            y: startPosition.y,
+            scale: 1,
+            opacity: 1,
+          }}
+          animate={{
+            x: targetPosition.x,
+            y: targetPosition.y,
+            scale: 0.5,
+            opacity: 0,
+          }}
+          exit={{ opacity: 0 }}
+          transition={{
+            type: "spring",
+            damping: 20,
+            stiffness: 200,
+            duration: 0.5,
+          }}
+          onAnimationComplete={() => {
+            setIsVisible(false);
+            onAnimationComplete();
+          }}
+        >
+          <HeartIcon
+            size={24}
+            weight="fill"
+            className="text-red-500 drop-shadow-md"
+          />
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryActionSubHeader/LibraryActionSubHeader.tsx

@@ -13,7 +13,7 @@ export function LibraryActionSubHeader({ agentCount, setLibrarySort }: Props) {
   return (
     <div className="flex items-baseline justify-between">
       <div className="flex items-baseline gap-4">
-        <Text variant="h4">My agents</Text>
+        <Text variant="h5">My agents</Text>
         <Text
           variant="body"
           data-testid="agents-count"

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/LibraryAgentCard.tsx

@@ -4,6 +4,7 @@ import { Text } from "@/components/atoms/Text/Text";
 import { CaretCircleRightIcon } from "@phosphor-icons/react";
 import Image from "next/image";
 import NextLink from "next/link";
+import { motion } from "framer-motion";
 
 import { LibraryAgent } from "@/app/api/__generated__/models/libraryAgent";
 import Avatar, {
@@ -14,13 +15,24 @@ import { Link } from "@/components/atoms/Link/Link";
 import { AgentCardMenu } from "./components/AgentCardMenu";
 import { FavoriteButton } from "./components/FavoriteButton";
 import { useLibraryAgentCard } from "./useLibraryAgentCard";
+import { useFavoriteAnimation } from "../../context/FavoriteAnimationContext";
 
 interface Props {
   agent: LibraryAgent;
+  draggable?: boolean;
 }
 
-export function LibraryAgentCard({ agent }: Props) {
+export function LibraryAgentCard({
+  agent,
+  draggable = true,
+}: Props) {
   const { id, name, graph_id, can_access_graph, image_url } = agent;
+  const { triggerFavoriteAnimation } = useFavoriteAnimation();
+
+  function handleDragStart(e: React.DragEvent<HTMLDivElement>) {
+    e.dataTransfer.setData("application/agent-id", id);
+    e.dataTransfer.effectAllowed = "move";
+  }
 
   const {
     isFromMarketplace,
@@ -28,14 +40,29 @@ export function LibraryAgentCard({ agent }: Props) {
     profile,
     creator_image_url,
     handleToggleFavorite,
-  } = useLibraryAgentCard({ agent });
+  } = useLibraryAgentCard({
+    agent,
+    onFavoriteAdd: triggerFavoriteAnimation,
+  });
 
   return (
     <div
-      data-testid="library-agent-card"
-      data-agent-id={id}
-      className="group relative inline-flex h-[10.625rem] w-full max-w-[25rem] flex-col items-start justify-start gap-2.5 rounded-medium border border-zinc-100 bg-white transition-all duration-300 hover:shadow-md"
+      draggable={draggable}
+      onDragStart={handleDragStart}
+      className="cursor-grab active:cursor-grabbing"
     >
+      <motion.div
+        layoutId={`agent-card-${id}`}
+        data-testid="library-agent-card"
+        data-agent-id={id}
+        className="group relative inline-flex h-[10.625rem] w-full max-w-[25rem] flex-col items-start justify-start gap-2.5 rounded-medium border border-zinc-100 bg-white hover:shadow-md"
+        transition={{
+          type: "spring",
+          damping: 25,
+          stiffness: 300,
+        }}
+        style={{ willChange: "transform" }}
+      >
       <NextLink href={`/library/agents/${id}`} className="flex-shrink-0">
         <div className="relative flex items-center gap-2 px-4 pt-3">
           <Avatar className="h-4 w-4 rounded-full">
@@ -125,6 +152,7 @@ export function LibraryAgentCard({ agent }: Props) {
           )}
         </div>
       </div>
+      </motion.div>
     </div>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/components/AgentCardMenu.tsx

@@ -5,6 +5,10 @@ import {
   useDeleteV2DeleteLibraryAgent,
   usePostV2ForkLibraryAgent,
 } from "@/app/api/__generated__/endpoints/library/library";
+import {
+  usePostV2BulkMoveAgents,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
 import { LibraryAgent } from "@/app/api/__generated__/models/libraryAgent";
 import { Button } from "@/components/atoms/Button/Button";
 import { Text } from "@/components/atoms/Text/Text";
@@ -22,6 +26,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import Link from "next/link";
 import { useRouter } from "next/navigation";
 import { useState } from "react";
+import { MoveToFolderDialog } from "../../MoveToFolderDialog/MoveToFolderDialog";
 
 interface AgentCardMenuProps {
   agent: LibraryAgent;
@@ -32,11 +37,25 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
   const queryClient = useQueryClient();
   const router = useRouter();
   const [showDeleteDialog, setShowDeleteDialog] = useState(false);
+  const [showMoveDialog, setShowMoveDialog] = useState(false);
   const [isDeletingAgent, setIsDeletingAgent] = useState(false);
   const [isDuplicatingAgent, setIsDuplicatingAgent] = useState(false);
+  const [isRemovingFromFolder, setIsRemovingFromFolder] = useState(false);
 
   const { mutateAsync: deleteAgent } = useDeleteV2DeleteLibraryAgent();
   const { mutateAsync: forkAgent } = usePostV2ForkLibraryAgent();
+  const { mutateAsync: bulkMoveAgents } = usePostV2BulkMoveAgents({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+      },
+    },
+  });
 
   async function handleDuplicateAgent() {
     if (!agent.id) return;
@@ -70,6 +89,37 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
     }
   }
 
+  async function handleRemoveFromFolder() {
+    if (!agent.id) return;
+
+    setIsRemovingFromFolder(true);
+
+    try {
+      await bulkMoveAgents({
+        data: {
+          agent_ids: [agent.id],
+          folder_id: undefined,
+        },
+      });
+
+      toast({
+        title: "Removed from folder",
+        description: "Agent has been moved back to your library.",
+      });
+    } catch (error: unknown) {
+      toast({
+        title: "Failed to remove from folder",
+        description:
+          error instanceof Error
+            ? error.message
+            : "An unexpected error occurred.",
+        variant: "destructive",
+      });
+    } finally {
+      setIsRemovingFromFolder(false);
+    }
+  }
+
   async function handleDeleteAgent() {
     if (!agent.id) return;
 
@@ -138,6 +188,31 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
             Duplicate agent
           </DropdownMenuItem>
           <DropdownMenuSeparator />
+          <DropdownMenuItem
+            onClick={(e) => {
+              e.stopPropagation();
+              setShowMoveDialog(true);
+            }}
+            className="flex items-center gap-2"
+          >
+            Move to folder
+          </DropdownMenuItem>
+          {agent.folder_id && (
+            <>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem
+                onClick={(e) => {
+                  e.stopPropagation();
+                  handleRemoveFromFolder();
+                }}
+                disabled={isRemovingFromFolder}
+                className="flex items-center gap-2"
+              >
+                Remove from folder
+              </DropdownMenuItem>
+            </>
+          )}
+          <DropdownMenuSeparator />
           <DropdownMenuItem
             onClick={(e) => {
               e.stopPropagation();
@@ -183,6 +258,14 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
           </div>
         </Dialog.Content>
       </Dialog>
+
+      <MoveToFolderDialog
+        agentId={agent.id}
+        agentName={agent.name}
+        currentFolderId={agent.folder_id}
+        isOpen={showMoveDialog}
+        setIsOpen={setShowMoveDialog}
+      />
     </>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/components/FavoriteButton.tsx

@@ -3,10 +3,12 @@
 import { cn } from "@/lib/utils";
 import { HeartIcon } from "@phosphor-icons/react";
 import type { MouseEvent } from "react";
+import { useRef } from "react";
+import { motion, AnimatePresence } from "framer-motion";
 
 interface FavoriteButtonProps {
   isFavorite: boolean;
-  onClick: (e: MouseEvent<HTMLButtonElement>) => void;
+  onClick: (e: MouseEvent<HTMLButtonElement>, position: { x: number; y: number }) => void;
   className?: string;
 }
 
@@ -15,25 +17,46 @@ export function FavoriteButton({
   onClick,
   className,
 }: FavoriteButtonProps) {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  function handleClick(e: MouseEvent<HTMLButtonElement>) {
+    const rect = buttonRef.current?.getBoundingClientRect();
+    const position = rect
+      ? { x: rect.left + rect.width / 2 - 12, y: rect.top + rect.height / 2 - 12 }
+      : { x: 0, y: 0 };
+    onClick(e, position);
+  }
+
   return (
     <button
-      onClick={onClick}
+      ref={buttonRef}
+      onClick={handleClick}
       className={cn(
         "rounded-full p-2 transition-all duration-200",
-        "hover:scale-110",
+        "hover:scale-110 active:scale-95",
         !isFavorite && "opacity-0 group-hover:opacity-100",
         className,
       )}
       aria-label={isFavorite ? "Remove from favorites" : "Add to favorites"}
     >
-      <HeartIcon
-        size={20}
-        weight={isFavorite ? "fill" : "regular"}
-        className={cn(
-          "transition-colors duration-200",
-          isFavorite ? "text-red-500" : "text-gray-600 hover:text-red-500",
-        )}
-      />
+      <AnimatePresence mode="wait" initial={false}>
+        <motion.div
+          key={isFavorite ? "filled" : "empty"}
+          initial={{ scale: 0.5, opacity: 0 }}
+          animate={{ scale: 1, opacity: 1 }}
+          exit={{ scale: 0.5, opacity: 0 }}
+          transition={{ type: "spring", damping: 15, stiffness: 300 }}
+        >
+          <HeartIcon
+            size={20}
+            weight={isFavorite ? "fill" : "regular"}
+            className={cn(
+              "transition-colors duration-200",
+              isFavorite ? "text-red-500" : "text-gray-600 hover:text-red-500",
+            )}
+          />
+        </motion.div>
+      </AnimatePresence>
     </button>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/useLibraryAgentCard.ts

@@ -14,11 +14,11 @@ import { updateFavoriteInQueries } from "./helpers";
 
 interface Props {
   agent: LibraryAgent;
+  onFavoriteAdd?: (position: { x: number; y: number }) => void;
 }
 
-export function useLibraryAgentCard({ agent }: Props) {
-  const { id, name, is_favorite, creator_image_url, marketplace_listing } =
-    agent;
+export function useLibraryAgentCard({ agent, onFavoriteAdd }: Props) {
+  const { id, is_favorite, creator_image_url, marketplace_listing } = agent;
 
   const isFromMarketplace = Boolean(marketplace_listing);
   const [isFavorite, setIsFavorite] = useState(is_favorite);
@@ -49,26 +49,31 @@ export function useLibraryAgentCard({ agent }: Props) {
     });
   }
 
-  async function handleToggleFavorite(e: React.MouseEvent) {
+  async function handleToggleFavorite(
+    e: React.MouseEvent,
+    position: { x: number; y: number }
+  ) {
     e.preventDefault();
     e.stopPropagation();
 
     const newIsFavorite = !isFavorite;
 
+    // Optimistic update - update UI immediately
     setIsFavorite(newIsFavorite);
     updateQueryData(newIsFavorite);
 
+    // Trigger animation immediately for adding to favorites
+    if (newIsFavorite && onFavoriteAdd) {
+      onFavoriteAdd(position);
+    }
+
     try {
       await updateLibraryAgent({
         libraryAgentId: id,
         data: { is_favorite: newIsFavorite },
       });
-
-      toast({
-        title: newIsFavorite ? "Added to favorites" : "Removed from favorites",
-        description: `${name} has been ${newIsFavorite ? "added to" : "removed from"} your favorites.`,
-      });
     } catch {
+      // Revert on failure
       setIsFavorite(!newIsFavorite);
       updateQueryData(!newIsFavorite);
 

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentList/LibraryAgentList.tsx

@@ -1,30 +1,130 @@
 "use client";
+
 import { LibraryAgentSort } from "@/app/api/__generated__/models/libraryAgentSort";
 import { LoadingSpinner } from "@/components/atoms/LoadingSpinner/LoadingSpinner";
 import { InfiniteScroll } from "@/components/contextual/InfiniteScroll/InfiniteScroll";
 import { LibraryActionSubHeader } from "../LibraryActionSubHeader/LibraryActionSubHeader";
 import { LibraryAgentCard } from "../LibraryAgentCard/LibraryAgentCard";
+import { LibraryFolder } from "../LibraryFolder/LibraryFolder";
+import { LibrarySubSection } from "../LibrarySubSection/LibrarySubSection";
+import { Button } from "@/components/atoms/Button/Button";
+import { ArrowLeftIcon, HeartIcon } from "@phosphor-icons/react";
+import { Text } from "@/components/atoms/Text/Text";
+import { Tab } from "../LibraryTabs/LibraryTabs";
+import {
+  AnimatePresence,
+  LayoutGroup,
+  motion,
+  useReducedMotion,
+} from "framer-motion";
+import { LibraryFolderEditDialog } from "../LibraryFolderEditDialog/LibraryFolderEditDialog";
+import { LibraryFolderDeleteDialog } from "../LibraryFolderDeleteDialog/LibraryFolderDeleteDialog";
 import { useLibraryAgentList } from "./useLibraryAgentList";
 
+// Spring-based enter/exit animations (Emil Kowalski principles)
+// Springs are naturally interruptible — switching tabs mid-animation
+// cancels the current spring and starts a new one from current state.
+const containerVariants = {
+  hidden: {},
+  show: {},
+  exit: {
+    opacity: 0,
+    filter: "blur(4px)",
+    transition: { duration: 0.12 },
+  },
+};
+
+// Reduced motion fallback
+const reducedContainerVariants = {
+  hidden: {},
+  show: {},
+  exit: {
+    opacity: 0,
+    transition: { duration: 0.12 },
+  },
+};
+
+// Per-item animation values (explicit initial/animate, not variant-based).
+// This ensures items animate in on mount regardless of parent state — fixes
+// the bug where dynamically added children (e.g. folders reappearing after
+// search is cleared) stayed invisible with variant inheritance.
+const itemInitial = {
+  opacity: 0,
+  filter: "blur(4px)",
+};
+
+const itemAnimate = {
+  opacity: 1,
+  filter: "blur(0px)",
+};
+
+const itemTransition = {
+  type: "spring" as const,
+  stiffness: 300,
+  damping: 25,
+  opacity: { duration: 0.2 },
+  filter: { duration: 0.15 },
+};
+
+const reducedItemInitial = { opacity: 0 };
+const reducedItemAnimate = { opacity: 1 };
+const reducedItemTransition = { duration: 0.15 };
+
 interface Props {
   searchTerm: string;
   librarySort: LibraryAgentSort;
   setLibrarySort: (value: LibraryAgentSort) => void;
+  selectedFolderId: string | null;
+  onFolderSelect: (folderId: string | null) => void;
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
 }
 
 export function LibraryAgentList({
   searchTerm,
   librarySort,
   setLibrarySort,
+  selectedFolderId,
+  onFolderSelect,
+  tabs,
+  activeTab,
+  onTabChange,
 }: Props) {
+  const shouldReduceMotion = useReducedMotion();
+  const activeContainerVariants = shouldReduceMotion
+    ? reducedContainerVariants
+    : containerVariants;
+  const activeInitial = shouldReduceMotion ? reducedItemInitial : itemInitial;
+  const activeAnimate = shouldReduceMotion ? reducedItemAnimate : itemAnimate;
+  const activeTransition = shouldReduceMotion
+    ? reducedItemTransition
+    : itemTransition;
+
   const {
+    isFavoritesTab,
     agentLoading,
     agentCount,
-    allAgents: agents,
+    agents,
     hasNextPage,
     isFetchingNextPage,
     fetchNextPage,
-  } = useLibraryAgentList({ searchTerm, librarySort });
+    foldersData,
+    currentFolder,
+    showFolders,
+    editingFolder,
+    setEditingFolder,
+    deletingFolder,
+    setDeletingFolder,
+    handleAgentDrop,
+    handleFolderDeleted,
+  } = useLibraryAgentList({
+    searchTerm,
+    librarySort,
+    selectedFolderId,
+    onFolderSelect,
+    activeTab,
+  });
 
   return (
     <>
@@ -32,11 +132,42 @@ export function LibraryAgentList({
         agentCount={agentCount}
         setLibrarySort={setLibrarySort}
       />
-      <div className="px-2">
+      {!selectedFolderId && (
+        <LibrarySubSection
+          tabs={tabs}
+          activeTab={activeTab}
+          onTabChange={onTabChange}
+        />
+      )}
+
+      <div>
+        {selectedFolderId && (
+          <div className="mb-4 flex items-center gap-3">
+            <Button
+              variant="ghost"
+              size="small"
+              onClick={() => onFolderSelect(null)}
+              className="gap-2"
+            >
+              <ArrowLeftIcon className="h-4 w-4" />
+              Back to Library
+            </Button>
+            {currentFolder && (
+              <Text variant="h4" className="text-zinc-700">
+                {currentFolder.icon} {currentFolder.name}
+              </Text>
+            )}
+          </div>
+        )}
         {agentLoading ? (
           <div className="flex h-[200px] items-center justify-center">
             <LoadingSpinner size="large" />
           </div>
+        ) : isFavoritesTab && agents.length === 0 ? (
+          <div className="flex h-[200px] flex-col items-center justify-center gap-2 text-zinc-500">
+            <HeartIcon className="h-10 w-10" />
+            <Text variant="body">No favorite agents yet</Text>
+          </div>
         ) : (
           <InfiniteScroll
             isFetchingNextPage={isFetchingNextPage}
@@ -44,14 +175,83 @@ export function LibraryAgentList({
             hasNextPage={hasNextPage}
             loader={<LoadingSpinner size="medium" />}
           >
-            <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
-              {agents.map((agent) => (
-                <LibraryAgentCard key={agent.id} agent={agent} />
-              ))}
-            </div>
+            <LayoutGroup>
+              <AnimatePresence mode="popLayout">
+                <motion.div
+                  key={`${activeTab}-${selectedFolderId || "all"}`}
+                  className="grid grid-cols-1 gap-6 sm:grid-cols-2 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                  variants={activeContainerVariants}
+                  initial="hidden"
+                  animate="show"
+                  exit="exit"
+                >
+                  {showFolders &&
+                    foldersData?.folders.map((folder, i) => (
+                      <motion.div
+                        key={folder.id}
+                        initial={activeInitial}
+                        animate={activeAnimate}
+                        transition={{
+                          ...activeTransition,
+                          delay: i * 0.04,
+                        }}
+                      >
+                        <LibraryFolder
+                          id={folder.id}
+                          name={folder.name}
+                          agentCount={folder.agent_count ?? 0}
+                          color={folder.color ?? undefined}
+                          icon={folder.icon ?? "📁"}
+                          onAgentDrop={handleAgentDrop}
+                          onClick={() => onFolderSelect(folder.id)}
+                          onEdit={() => setEditingFolder(folder)}
+                          onDelete={() => setDeletingFolder(folder)}
+                        />
+                      </motion.div>
+                    ))}
+                  {agents.map((agent, i) => (
+                    <motion.div
+                      key={agent.id}
+                      initial={activeInitial}
+                      animate={activeAnimate}
+                      transition={{
+                        ...activeTransition,
+                        delay:
+                          ((showFolders ? foldersData?.folders.length ?? 0 : 0) +
+                            i) *
+                          0.04,
+                      }}
+                    >
+                      <LibraryAgentCard agent={agent} />
+                    </motion.div>
+                  ))}
+                </motion.div>
+              </AnimatePresence>
+            </LayoutGroup>
           </InfiniteScroll>
         )}
       </div>
+
+      {editingFolder && (
+        <LibraryFolderEditDialog
+          folder={editingFolder}
+          isOpen={!!editingFolder}
+          setIsOpen={(open) => {
+            if (!open) setEditingFolder(null);
+          }}
+        />
+      )}
+
+      {deletingFolder && (
+        <LibraryFolderDeleteDialog
+          folder={deletingFolder}
+          isOpen={!!deletingFolder}
+          setIsOpen={(open) => {
+            if (!open) setDeletingFolder(null);
+          }}
+          onDeleted={handleFolderDeleted}
+        />
+      )}
     </>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentList/useLibraryAgentList.ts

@@ -1,36 +1,69 @@
 "use client";
 
 import { useGetV2ListLibraryAgentsInfinite } from "@/app/api/__generated__/endpoints/library/library";
+import { getGetV2ListLibraryAgentsQueryKey } from "@/app/api/__generated__/endpoints/library/library";
+import {
+  useGetV2ListLibraryFolders,
+  usePostV2BulkMoveAgents,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import type { getV2ListLibraryFoldersResponseSuccess } from "@/app/api/__generated__/endpoints/folders/folders";
+import type { LibraryFolder } from "@/app/api/__generated__/models/libraryFolder";
 import { LibraryAgentSort } from "@/app/api/__generated__/models/libraryAgentSort";
 import {
+  okData,
   getPaginatedTotalCount,
   getPaginationNextPageNumber,
   unpaginate,
 } from "@/app/api/helpers";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import { useFavoriteAgents } from "../../hooks/useFavoriteAgents";
 import { getQueryClient } from "@/lib/react-query/queryClient";
-import { useEffect, useRef } from "react";
+import { keepPreviousData, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useRef, useState } from "react";
 
 interface Props {
   searchTerm: string;
   librarySort: LibraryAgentSort;
+  selectedFolderId: string | null;
+  onFolderSelect: (folderId: string | null) => void;
+  activeTab: string;
 }
 
-export function useLibraryAgentList({ searchTerm, librarySort }: Props) {
-  const queryClient = getQueryClient();
+export function useLibraryAgentList({
+  searchTerm,
+  librarySort,
+  selectedFolderId,
+  onFolderSelect,
+  activeTab,
+}: Props) {
+  const isFavoritesTab = activeTab === "favorites";
+  const { toast } = useToast();
+  const stableQueryClient = getQueryClient();
+  const queryClient = useQueryClient();
   const prevSortRef = useRef<LibraryAgentSort | null>(null);
 
+  const [editingFolder, setEditingFolder] = useState<LibraryFolder | null>(
+    null,
+  );
+  const [deletingFolder, setDeletingFolder] = useState<LibraryFolder | null>(
+    null,
+  );
+
   const {
     data: agentsQueryData,
     fetchNextPage,
     hasNextPage,
     isFetchingNextPage,
-    isLoading: agentLoading,
+    isLoading: allAgentsLoading,
   } = useGetV2ListLibraryAgentsInfinite(
     {
       page: 1,
       page_size: 20,
       search_term: searchTerm || undefined,
       sort_by: librarySort,
+      folder_id: selectedFolderId ?? undefined,
+      include_root_only: selectedFolderId === null ? true : undefined,
     },
     {
       query: {
@@ -39,28 +72,152 @@ export function useLibraryAgentList({ searchTerm, librarySort }: Props) {
     },
   );
 
-  // Reset queries when sort changes to ensure fresh data with correct sorting
   useEffect(() => {
     if (prevSortRef.current !== null && prevSortRef.current !== librarySort) {
-      // Reset all library agent queries to ensure fresh fetch with new sort
-      queryClient.resetQueries({
+      stableQueryClient.resetQueries({
         queryKey: ["/api/library/agents"],
       });
     }
     prevSortRef.current = librarySort;
-  }, [librarySort, queryClient]);
+  }, [librarySort, stableQueryClient]);
 
-  const allAgents = agentsQueryData
+  const allAgentsList = agentsQueryData
     ? unpaginate(agentsQueryData, "agents")
     : [];
-  const agentCount = getPaginatedTotalCount(agentsQueryData);
+  const allAgentsCount = getPaginatedTotalCount(agentsQueryData);
+
+  // --- Favorites ---
+
+  const favoriteAgentsData = useFavoriteAgents({ searchTerm });
+
+  const {
+    agentLoading,
+    agentCount,
+    allAgents: agents,
+    hasNextPage: agentsHasNextPage,
+    isFetchingNextPage: agentsIsFetchingNextPage,
+    fetchNextPage: agentsFetchNextPage,
+  } = isFavoritesTab
+    ? favoriteAgentsData
+    : {
+        agentLoading: allAgentsLoading,
+        agentCount: allAgentsCount,
+        allAgents: allAgentsList,
+        hasNextPage: hasNextPage,
+        isFetchingNextPage: isFetchingNextPage,
+        fetchNextPage: fetchNextPage,
+      };
+
+  // --- Folders ---
+
+  const { data: rawFoldersData } = useGetV2ListLibraryFolders(undefined, {
+    query: { select: okData },
+  });
+
+  // When searching, suppress folder data so only agent results show
+  const foldersData = searchTerm ? undefined : rawFoldersData;
+
+  const { mutate: moveAgentToFolder } = usePostV2BulkMoveAgents({
+    mutation: {
+      onMutate: async ({ data }) => {
+        await queryClient.cancelQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        await queryClient.cancelQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+
+        const previousFolders =
+          queryClient.getQueriesData<getV2ListLibraryFoldersResponseSuccess>({
+            queryKey: getGetV2ListLibraryFoldersQueryKey(),
+          });
+
+        if (data.folder_id) {
+          queryClient.setQueriesData<getV2ListLibraryFoldersResponseSuccess>(
+            { queryKey: getGetV2ListLibraryFoldersQueryKey() },
+            (old) => {
+              if (!old?.data?.folders) return old;
+              return {
+                ...old,
+                data: {
+                  ...old.data,
+                  folders: old.data.folders.map((f) =>
+                    f.id === data.folder_id
+                      ? {
+                          ...f,
+                          agent_count:
+                            (f.agent_count ?? 0) + data.agent_ids.length,
+                        }
+                      : f,
+                  ),
+                },
+              };
+            },
+          );
+        }
+
+        return { previousFolders };
+      },
+      onError: (_error, _variables, context) => {
+        if (context?.previousFolders) {
+          for (const [queryKey, data] of context.previousFolders) {
+            queryClient.setQueryData(queryKey, data);
+          }
+        }
+        toast({
+          title: "Error",
+          description: "Failed to move agent. Please try again.",
+          variant: "destructive",
+        });
+      },
+      onSettled: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+      },
+    },
+  });
+
+  function handleAgentDrop(agentId: string, folderId: string) {
+    moveAgentToFolder({
+      data: {
+        agent_ids: [agentId],
+        folder_id: folderId,
+      },
+    });
+  }
+
+  const currentFolder = selectedFolderId
+    ? foldersData?.folders.find((f) => f.id === selectedFolderId)
+    : null;
+
+  const showFolders = !isFavoritesTab && !selectedFolderId;
+
+  function handleFolderDeleted() {
+    if (selectedFolderId === deletingFolder?.id) {
+      onFolderSelect(null);
+    }
+  }
 
   return {
-    allAgents,
+    isFavoritesTab,
     agentLoading,
-    hasNextPage,
     agentCount,
-    isFetchingNextPage,
-    fetchNextPage,
+    agents,
+    hasNextPage: agentsHasNextPage,
+    isFetchingNextPage: agentsIsFetchingNextPage,
+    fetchNextPage: agentsFetchNextPage,
+    foldersData,
+    currentFolder,
+    showFolders,
+    editingFolder,
+    setEditingFolder,
+    deletingFolder,
+    setDeletingFolder,
+    handleAgentDrop,
+    handleFolderDeleted,
   };
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolder/FolderIcon.tsx

@@ -0,0 +1,381 @@
+import { useState } from "react";
+import { motion } from "framer-motion";
+import { Text } from "@/components/atoms/Text/Text";
+
+type FolderSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type FolderColorName =
+  | "neutral"
+  | "slate"
+  | "zinc"
+  | "stone"
+  | "red"
+  | "orange"
+  | "amber"
+  | "yellow"
+  | "lime"
+  | "green"
+  | "emerald"
+  | "teal"
+  | "cyan"
+  | "sky"
+  | "blue"
+  | "indigo"
+  | "violet"
+  | "purple"
+  | "fuchsia"
+  | "pink"
+  | "rose";
+
+export type FolderColor = FolderColorName | (string & {});
+
+const hexToColorName: Record<string, FolderColorName> = {
+  "#3B82F6": "blue",
+  "#3b82f6": "blue",
+  "#A855F7": "purple",
+  "#a855f7": "purple",
+  "#10B981": "emerald",
+  "#10b981": "emerald",
+  "#F97316": "orange",
+  "#f97316": "orange",
+  "#EC4899": "pink",
+  "#ec4899": "pink",
+};
+
+export function resolveColor(color: FolderColor | undefined): FolderColorName {
+  if (!color) return "blue";
+  if (color in hexToColorName) return hexToColorName[color];
+  if (color in colorMap) return color as FolderColorName;
+  return "blue";
+}
+
+interface Props {
+  className?: string;
+  size?: FolderSize | number;
+  color?: FolderColor;
+  icon?: string;
+  isOpen?: boolean;
+}
+
+const sizeMap: Record<FolderSize, number> = {
+  xs: 0.4,
+  sm: 0.75,
+  md: 1,
+  lg: 1.25,
+  xl: 1.5,
+};
+
+const colorMap: Record<
+  FolderColorName,
+  {
+    bg: string;
+    border: string;
+    borderLight: string;
+    fill: string;
+    stroke: string;
+  }
+> = {
+  neutral: {
+    bg: "bg-neutral-300",
+    border: "border-neutral-300",
+    borderLight: "border-neutral-200",
+    fill: "fill-neutral-300",
+    stroke: "stroke-neutral-400",
+  },
+  slate: {
+    bg: "bg-slate-300",
+    border: "border-slate-300",
+    borderLight: "border-slate-200",
+    fill: "fill-slate-300",
+    stroke: "stroke-slate-400",
+  },
+  zinc: {
+    bg: "bg-zinc-300",
+    border: "border-zinc-300",
+    borderLight: "border-zinc-200",
+    fill: "fill-zinc-300",
+    stroke: "stroke-zinc-400",
+  },
+  stone: {
+    bg: "bg-stone-300",
+    border: "border-stone-300",
+    borderLight: "border-stone-200",
+    fill: "fill-stone-300",
+    stroke: "stroke-stone-400",
+  },
+  red: {
+    bg: "bg-red-300",
+    border: "border-red-300",
+    borderLight: "border-red-200",
+    fill: "fill-red-300",
+    stroke: "stroke-red-400",
+  },
+  orange: {
+    bg: "bg-orange-200",
+    border: "border-orange-200",
+    borderLight: "border-orange-200",
+    fill: "fill-orange-200",
+    stroke: "stroke-orange-400",
+  },
+  amber: {
+    bg: "bg-amber-200",
+    border: "border-amber-200",
+    borderLight: "border-amber-200",
+    fill: "fill-amber-200",
+    stroke: "stroke-amber-400",
+  },
+  yellow: {
+    bg: "bg-yellow-200",
+    border: "border-yellow-200",
+    borderLight: "border-yellow-200",
+    fill: "fill-yellow-200",
+    stroke: "stroke-yellow-400",
+  },
+  lime: {
+    bg: "bg-lime-300",
+    border: "border-lime-300",
+    borderLight: "border-lime-200",
+    fill: "fill-lime-300",
+    stroke: "stroke-lime-400",
+  },
+  green: {
+    bg: "bg-green-200",
+    border: "border-green-200",
+    borderLight: "border-green-200",
+    fill: "fill-green-200",
+    stroke: "stroke-green-400",
+  },
+  emerald: {
+    bg: "bg-emerald-300",
+    border: "border-emerald-300",
+    borderLight: "border-emerald-200",
+    fill: "fill-emerald-300",
+    stroke: "stroke-emerald-400",
+  },
+  teal: {
+    bg: "bg-teal-300",
+    border: "border-teal-300",
+    borderLight: "border-teal-200",
+    fill: "fill-teal-300",
+    stroke: "stroke-teal-400",
+  },
+  cyan: {
+    bg: "bg-cyan-300",
+    border: "border-cyan-300",
+    borderLight: "border-cyan-200",
+    fill: "fill-cyan-300",
+    stroke: "stroke-cyan-400",
+  },
+  sky: {
+    bg: "bg-sky-300",
+    border: "border-sky-300",
+    borderLight: "border-sky-200",
+    fill: "fill-sky-300",
+    stroke: "stroke-sky-400",
+  },
+  blue: {
+    bg: "bg-blue-300",
+    border: "border-blue-300",
+    borderLight: "border-blue-200",
+    fill: "fill-blue-300",
+    stroke: "stroke-blue-400",
+  },
+  indigo: {
+    bg: "bg-indigo-300",
+    border: "border-indigo-300",
+    borderLight: "border-indigo-200",
+    fill: "fill-indigo-300",
+    stroke: "stroke-indigo-400",
+  },
+  violet: {
+    bg: "bg-violet-300",
+    border: "border-violet-300",
+    borderLight: "border-violet-200",
+    fill: "fill-violet-300",
+    stroke: "stroke-violet-400",
+  },
+  purple: {
+    bg: "bg-purple-200",
+    border: "border-purple-200",
+    borderLight: "border-purple-200",
+    fill: "fill-purple-200",
+    stroke: "stroke-purple-400",
+  },
+  fuchsia: {
+    bg: "bg-fuchsia-300",
+    border: "border-fuchsia-300",
+    borderLight: "border-fuchsia-200",
+    fill: "fill-fuchsia-300",
+    stroke: "stroke-fuchsia-400",
+  },
+  pink: {
+    bg: "bg-pink-300",
+    border: "border-pink-300",
+    borderLight: "border-pink-200",
+    fill: "fill-pink-300",
+    stroke: "stroke-pink-400",
+  },
+  rose: {
+    bg: "bg-rose-300",
+    border: "border-rose-300",
+    borderLight: "border-rose-200",
+    fill: "fill-rose-300",
+    stroke: "stroke-rose-400",
+  },
+};
+
+// Card-level bg (50) and border (200) classes per folder color
+export const folderCardStyles: Record<
+  FolderColorName,
+  { bg: string; border: string }
+> = {
+  neutral: { bg: "bg-neutral-50", border: "border-neutral-200" },
+  slate: { bg: "bg-slate-50", border: "border-slate-200" },
+  zinc: { bg: "bg-zinc-50", border: "border-zinc-200" },
+  stone: { bg: "bg-stone-50", border: "border-stone-200" },
+  red: { bg: "bg-red-50", border: "border-red-200" },
+  orange: { bg: "bg-orange-50", border: "border-orange-200" },
+  amber: { bg: "bg-amber-50", border: "border-amber-200" },
+  yellow: { bg: "bg-yellow-50", border: "border-yellow-200" },
+  lime: { bg: "bg-lime-50", border: "border-lime-200" },
+  green: { bg: "bg-green-50", border: "border-green-200" },
+  emerald: { bg: "bg-emerald-50", border: "border-emerald-200" },
+  teal: { bg: "bg-teal-50", border: "border-teal-200" },
+  cyan: { bg: "bg-cyan-50", border: "border-cyan-200" },
+  sky: { bg: "bg-sky-50", border: "border-sky-200" },
+  blue: { bg: "bg-blue-50", border: "border-blue-200" },
+  indigo: { bg: "bg-indigo-50", border: "border-indigo-200" },
+  violet: { bg: "bg-violet-50", border: "border-violet-200" },
+  purple: { bg: "bg-purple-50", border: "border-purple-200" },
+  fuchsia: { bg: "bg-fuchsia-50", border: "border-fuchsia-200" },
+  pink: { bg: "bg-pink-50", border: "border-pink-200" },
+  rose: { bg: "bg-rose-50", border: "border-rose-200" },
+};
+
+export function FolderIcon({
+  className = "",
+  size = "xs",
+  color = "blue",
+  icon,
+  isOpen = false,
+}: Props) {
+  const scale = typeof size === "number" ? size : sizeMap[size];
+  const resolvedColor = resolveColor(color);
+  const colors = colorMap[resolvedColor];
+
+  return (
+    <div
+      className={`group relative cursor-pointer ${className}`}
+      style={{
+        width: 320 * scale,
+        height: 208 * scale,
+      }}
+    >
+      <div
+        className="h-52 w-80 origin-top-left"
+        style={{ transform: `scale(${scale})`, perspective: "500px" }}
+      >
+        <div
+          className={`folder-back relative mx-auto flex h-full w-[87.5%] justify-center overflow-visible rounded-3xl ${colors.bg} ${colors.border}`}
+        >
+          {[
+            {
+              initial: { rotate: -3, x: -38, y: 2 },
+              open: { rotate: -8, x: -70, y: -75 },
+              transition: {
+                type: "spring" as const,
+                bounce: 0.15,
+                stiffness: 160,
+                damping: 22,
+              },
+              className: "z-10",
+            },
+            {
+              initial: { rotate: 0, x: 0, y: 0 },
+              open: { rotate: 1, x: 2, y: -95 },
+              transition: {
+                type: "spring" as const,
+                duration: 0.55,
+                bounce: 0.12,
+                stiffness: 190,
+                damping: 24,
+              },
+              className: "z-20",
+            },
+            {
+              initial: { rotate: 3.5, x: 42, y: 1 },
+              open: { rotate: 9, x: 75, y: -80 },
+              transition: {
+                type: "spring" as const,
+                duration: 0.58,
+                bounce: 0.17,
+                stiffness: 170,
+                damping: 21,
+              },
+              className: "z-10",
+            },
+          ].map((page, i) => (
+            <motion.div
+              key={i}
+              initial={page.initial}
+              animate={isOpen ? page.open : page.initial}
+              transition={page.transition}
+              className={`absolute top-2 h-fit w-32 rounded-xl shadow-lg ${page.className}`}
+            >
+              <Page color={resolvedColor} />
+            </motion.div>
+          ))}
+        </div>
+
+        <motion.div
+          animate={{
+            rotateX: isOpen ? -15 : 0,
+          }}
+          transition={{ type: "spring", duration: 0.5, bounce: 0.25 }}
+          className="absolute inset-x-0 -bottom-px z-30 mx-auto flex h-44 w-[87.5%] origin-bottom items-end justify-center overflow-visible"
+          style={{ transformStyle: "preserve-3d" }}
+        >
+          <svg
+            className="h-auto w-full"
+            viewBox="0 0 173 109"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            preserveAspectRatio="none"
+          >
+            <path
+              className={`${colors.fill} ${colors.stroke}`}
+              d="M15.0423 0.500003C0.5 0.500009 0.5 14.2547 0.5 14.2547V92.5C0.5 101.337 7.66344 108.5 16.5 108.5H156.5C165.337 108.5 172.5 101.337 172.5 92.5V34.3302C172.5 25.4936 165.355 18.3302 156.519 18.3302H108.211C98.1341 18.3302 91.2921 5.57144 82.0156 1.63525C80.3338 0.921645 78.2634 0.500002 75.7187 0.500003H15.0423Z"
+            />
+          </svg>
+          <div className="absolute inset-0 flex items-center justify-center text-7xl">
+            {icon}
+          </div>
+        </motion.div>
+      </div>
+    </div>
+  );
+}
+
+interface PageProps {
+  color: FolderColorName;
+}
+
+function Page({ color = "blue" }: PageProps) {
+  const colors = colorMap[color];
+  return (
+    <div
+      className={`h-full w-full rounded-xl border bg-white p-4 ${colors.borderLight}`}
+    >
+      <div className="flex flex-col gap-2">
+        <Text variant="h5" className="text-black">
+          agent.json
+        </Text>
+        {Array.from({ length: 8 }).map((_, i) => (
+          <div key={i} className="flex gap-2">
+            <div className="h-1.5 flex-1 rounded-full bg-neutral-100" />
+            <div className="h-1.5 flex-1 rounded-full bg-neutral-100" />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolder/LibraryFolder.tsx

@@ -0,0 +1,136 @@
+"use client";
+
+import { Text } from "@/components/atoms/Text/Text";
+import { Button } from "@/components/atoms/Button/Button";
+import {
+  FolderIcon,
+  FolderColor,
+  folderCardStyles,
+  resolveColor,
+} from "./FolderIcon";
+import { useState } from "react";
+import { PencilSimpleIcon, TrashIcon } from "@phosphor-icons/react";
+
+interface Props {
+  id: string;
+  name: string;
+  agentCount: number;
+  color?: FolderColor;
+  icon: string;
+  onEdit?: () => void;
+  onDelete?: () => void;
+  onAgentDrop?: (agentId: string, folderId: string) => void;
+  onClick?: () => void;
+}
+
+export function LibraryFolder({
+  id,
+  name,
+  agentCount,
+  color,
+  icon,
+  onEdit,
+  onDelete,
+  onAgentDrop,
+  onClick,
+}: Props) {
+  const [isHovered, setIsHovered] = useState(false);
+  const [isDragOver, setIsDragOver] = useState(false);
+  const resolvedColor = resolveColor(color);
+  const cardStyle = folderCardStyles[resolvedColor];
+
+  function handleDragOver(e: React.DragEvent<HTMLDivElement>) {
+    if (e.dataTransfer.types.includes("application/agent-id")) {
+      e.preventDefault();
+      e.dataTransfer.dropEffect = "move";
+      setIsDragOver(true);
+    }
+  }
+
+  function handleDragLeave() {
+    setIsDragOver(false);
+  }
+
+  function handleDrop(e: React.DragEvent<HTMLDivElement>) {
+    e.preventDefault();
+    setIsDragOver(false);
+    const agentId = e.dataTransfer.getData("application/agent-id");
+    if (agentId && onAgentDrop) {
+      onAgentDrop(agentId, id);
+    }
+  }
+
+  return (
+    <div
+      data-testid="library-folder"
+      data-folder-id={id}
+      className={`group relative inline-flex h-[10.625rem] w-full max-w-[25rem] cursor-pointer flex-col items-start justify-between gap-2.5 rounded-medium border p-4 transition-all duration-200 hover:shadow-md ${
+        isDragOver
+          ? "border-blue-400 bg-blue-50 ring-2 ring-blue-200"
+          : `${cardStyle.border} ${cardStyle.bg}`
+      }`}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+      onClick={onClick}
+    >
+      <div className="flex w-full items-start justify-between gap-4">
+        {/* Left side - Folder name and agent count */}
+        <div className="flex flex-1 flex-col gap-2">
+          <Text
+            variant="h5"
+            data-testid="library-folder-name"
+            className="line-clamp-2 hyphens-auto break-words"
+          >
+            {name}
+          </Text>
+          <Text
+            variant="small"
+            className="text-zinc-500"
+            data-testid="library-folder-agent-count"
+          >
+            {agentCount} {agentCount === 1 ? "agent" : "agents"}
+          </Text>
+        </div>
+
+        {/* Right side - Custom folder icon */}
+        <div className="flex-shrink-0">
+          <FolderIcon isOpen={isHovered} color={color} icon={icon} />
+        </div>
+      </div>
+
+      {/* Action buttons - visible on hover */}
+      <div
+        className="flex items-center justify-end gap-2"
+        data-testid="library-folder-actions"
+      >
+        <Button
+          variant="icon"
+          size="icon"
+          aria-label="Edit agent"
+          onClick={(e) => {
+            e.stopPropagation();
+            onEdit?.();
+          }}
+          className="h-8 w-8 p-2"
+        >
+          <PencilSimpleIcon className="h-4 w-4" />
+        </Button>
+        <Button
+          variant="icon"
+          size="icon"
+          aria-label="Delete agent"
+          onClick={(e) => {
+            e.stopPropagation();
+            onDelete?.();
+          }}
+          className="h-8 w-8 p-2 hover:border-red-300 hover:bg-red-50 hover:text-red-600"
+        >
+          <TrashIcon className="h-4 w-4" />
+        </Button>
+      </div>
+    </div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolderCreationDialog/LibraryFolderCreationDialog.tsx

@@ -0,0 +1,225 @@
+"use client";
+import { Button } from "@/components/atoms/Button/Button";
+import { Input } from "@/components/atoms/Input/Input";
+import { Select } from "@/components/atoms/Select/Select";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormMessage,
+} from "@/components/molecules/Form/Form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { FolderSimpleIcon } from "@phosphor-icons/react";
+import { useState } from "react";
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { EmojiPicker } from "@ferrucc-io/emoji-picker";
+import {
+  usePostV2CreateFolder,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import { useQueryClient } from "@tanstack/react-query";
+
+const FOLDER_COLORS = [
+  { value: "#3B82F6", label: "Blue" },
+  { value: "#A855F7", label: "Purple" },
+  { value: "#10B981", label: "Green" },
+  { value: "#F97316", label: "Orange" },
+  { value: "#EC4899", label: "Pink" },
+];
+
+export const libraryFolderCreationFormSchema = z.object({
+  folderName: z.string().min(1, "Folder name is required"),
+  folderColor: z.string().min(1, "Folder color is required"),
+  folderIcon: z.string().min(1, "Folder icon is required"),
+});
+
+export default function LibraryFolderCreationDialog() {
+  const [isOpen, setIsOpen] = useState(false);
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  const { mutate: createFolder, isPending } = usePostV2CreateFolder({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({ queryKey: getGetV2ListLibraryFoldersQueryKey() });
+        setIsOpen(false);
+        form.reset();
+        toast({
+          title: "Folder created",
+          description: "Your folder has been created successfully.",
+        });
+      },
+      onError: () => {
+        toast({
+          title: "Error",
+          description: "Failed to create folder. Please try again.",
+          variant: "destructive",
+        });
+      },
+    },
+  });
+
+  const form = useForm<z.infer<typeof libraryFolderCreationFormSchema>>({
+    resolver: zodResolver(libraryFolderCreationFormSchema),
+    defaultValues: {
+      folderName: "",
+      folderColor: "",
+      folderIcon: "",
+    },
+  });
+
+  function onSubmit(values: z.infer<typeof libraryFolderCreationFormSchema>) {
+    createFolder({
+      data: {
+        name: values.folderName.trim(),
+        color: values.folderColor,
+        icon: values.folderIcon,
+      },
+    });
+  }
+
+  return (
+    <Dialog
+      title="Create Folder"
+      styling={{ maxWidth: "30rem" }}
+      controlled={{
+        isOpen,
+        set: setIsOpen,
+      }}
+      onClose={() => {
+        setIsOpen(false);
+      }}
+    >
+      <Dialog.Trigger>
+        <Button
+          data-testid="upload-agent-button"
+          variant="secondary"
+          className="h-fit w-fit"
+          size="small"
+        >
+          <FolderSimpleIcon width={18} height={18} />
+          <span className="create-folder">Create folder</span>
+        </Button>
+      </Dialog.Trigger>
+      <Dialog.Content>
+        <Form
+          form={form}
+          onSubmit={(values) => onSubmit(values)}
+          className="flex flex-col justify-center px-1 gap-2"
+        >
+          <FormField
+            control={form.control}
+            name="folderName"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Input
+                    {...field}
+                    id={field.name}
+                    label="Folder name"
+                    placeholder="Enter folder name"
+                    className="w-full !mb-0"
+                    wrapperClassName="!mb-0"
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderColor"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Select
+                    id="folderColor"
+                    label="Folder color"
+                    placeholder="Select a color"
+                    value={field.value}
+                    onValueChange={field.onChange}
+                    options={FOLDER_COLORS.map((color) => ({
+                      value: color.value,
+                      label: color.label,
+                      icon: (
+                        <div
+                          className="h-4 w-4 rounded-full"
+                          style={{ backgroundColor: color.value }}
+                        />
+                      ),
+                    }))}
+                    wrapperClassName="!mb-0"
+                    renderItem={(option) => (
+                      <div className="flex items-center gap-2">
+                        {option.icon}
+                        <span>{option.label}</span>
+                      </div>
+                    )}
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderIcon"
+            render={({ field }) => (
+              <FormItem>
+                <div className="flex flex-col gap-2">
+                  <Text variant="large-medium" as="span" className="text-black">
+                    Folder icon
+                  </Text>
+                  <div className="flex flex-col gap-3">
+                    <div className="flex items-center gap-3">
+                      <Text variant="small" className="text-zinc-500">
+                        Selected:
+                      </Text>
+                      <div className="flex h-10 w-10 items-center justify-center rounded-lg border border-zinc-200 bg-zinc-50 text-2xl">
+                        {form.watch("folderIcon") || (
+                          <span className="text-sm text-zinc-400">—</span>
+                        )}
+                      </div>
+                    </div>
+                    <div className="h-[295px] w-full overflow-hidden">
+
+                      <EmojiPicker
+                        onEmojiSelect={(emoji) => {
+                          field.onChange(emoji);
+                        }}
+                        emojiSize={32}
+                        className="w-full rounded-2xl px-2"
+                      >
+                        <EmojiPicker.Group>
+                          <EmojiPicker.List hideStickyHeader containerHeight={295} />
+                        </EmojiPicker.Group>
+                      </EmojiPicker>
+                    </div>
+                  </div>
+                  <FormMessage />
+                </div>
+              </FormItem>
+            )}
+          />
+
+          <Button
+            type="submit"
+            variant="primary"
+            className="mt-2 min-w-[18rem]"
+            disabled={!form.formState.isValid || isPending}
+            loading={isPending}
+          >
+            Create
+          </Button>
+        </Form>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolderDeleteDialog/LibraryFolderDeleteDialog.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { Button } from "@/components/atoms/Button/Button";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import {
+  useDeleteV2DeleteFolder,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { getGetV2ListLibraryAgentsQueryKey } from "@/app/api/__generated__/endpoints/library/library";
+import { useQueryClient } from "@tanstack/react-query";
+import type { LibraryFolder } from "@/app/api/__generated__/models/libraryFolder";
+
+interface Props {
+  folder: LibraryFolder;
+  isOpen: boolean;
+  setIsOpen: (open: boolean) => void;
+  onDeleted?: () => void;
+}
+
+export function LibraryFolderDeleteDialog({
+  folder,
+  isOpen,
+  setIsOpen,
+  onDeleted,
+}: Props) {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  const { mutate: deleteFolder, isPending } = useDeleteV2DeleteFolder({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+        toast({
+          title: "Folder deleted",
+          description: `"${folder.name}" has been deleted.`,
+        });
+        setIsOpen(false);
+        onDeleted?.();
+      },
+      onError: () => {
+        toast({
+          title: "Error",
+          description: "Failed to delete folder. Please try again.",
+          variant: "destructive",
+        });
+      },
+    },
+  });
+
+  function handleDelete() {
+    deleteFolder({ folderId: folder.id });
+  }
+
+  return (
+    <Dialog
+      controlled={{
+        isOpen,
+        set: setIsOpen,
+      }}
+      styling={{ maxWidth: "32rem" }}
+      title="Delete folder"
+    >
+      <Dialog.Content>
+        <div>
+          <Text variant="large">
+            Are you sure you want to delete &ldquo;{folder.name}&rdquo;? Agents
+            inside this folder will be moved back to your library.
+          </Text>
+          <Dialog.Footer>
+            <Button
+              variant="secondary"
+              disabled={isPending}
+              onClick={() => setIsOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button
+              variant="destructive"
+              onClick={handleDelete}
+              loading={isPending}
+            >
+              Delete Folder
+            </Button>
+          </Dialog.Footer>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolderEditDialog/LibraryFolderEditDialog.tsx

@@ -0,0 +1,287 @@
+"use client";
+
+import { Button } from "@/components/atoms/Button/Button";
+import { Input } from "@/components/atoms/Input/Input";
+import { Select } from "@/components/atoms/Select/Select";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormMessage,
+} from "@/components/molecules/Form/Form";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useEffect } from "react";
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { EmojiPicker } from "@ferrucc-io/emoji-picker";
+import {
+  usePatchV2UpdateFolder,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { useQueryClient } from "@tanstack/react-query";
+import type { LibraryFolder } from "@/app/api/__generated__/models/libraryFolder";
+import type { getV2ListLibraryFoldersResponseSuccess } from "@/app/api/__generated__/endpoints/folders/folders";
+import { ApiError } from "@/lib/autogpt-server-api/helpers";
+
+const FOLDER_COLORS = [
+  { value: "#3B82F6", label: "Blue" },
+  { value: "#A855F7", label: "Purple" },
+  { value: "#10B981", label: "Green" },
+  { value: "#F97316", label: "Orange" },
+  { value: "#EC4899", label: "Pink" },
+];
+
+const editFolderSchema = z.object({
+  folderName: z.string().min(1, "Folder name is required"),
+  folderColor: z.string().min(1, "Folder color is required"),
+  folderIcon: z.string().min(1, "Folder icon is required"),
+});
+
+interface Props {
+  folder: LibraryFolder;
+  isOpen: boolean;
+  setIsOpen: (open: boolean) => void;
+}
+
+export function LibraryFolderEditDialog({ folder, isOpen, setIsOpen }: Props) {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  const form = useForm<z.infer<typeof editFolderSchema>>({
+    resolver: zodResolver(editFolderSchema),
+    defaultValues: {
+      folderName: folder.name,
+      folderColor: folder.color ?? "",
+      folderIcon: folder.icon ?? "",
+    },
+  });
+
+  useEffect(() => {
+    if (isOpen) {
+      form.reset({
+        folderName: folder.name,
+        folderColor: folder.color ?? "",
+        folderIcon: folder.icon ?? "",
+      });
+    }
+  }, [isOpen, folder, form]);
+
+  const { mutate: updateFolder, isPending } = usePatchV2UpdateFolder({
+    mutation: {
+      onMutate: async ({ folderId, data }) => {
+        await queryClient.cancelQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+
+        const previousData =
+          queryClient.getQueriesData<getV2ListLibraryFoldersResponseSuccess>({
+            queryKey: getGetV2ListLibraryFoldersQueryKey(),
+          });
+
+        queryClient.setQueriesData<getV2ListLibraryFoldersResponseSuccess>(
+          { queryKey: getGetV2ListLibraryFoldersQueryKey() },
+          (old) => {
+            if (!old?.data?.folders) return old;
+            return {
+              ...old,
+              data: {
+                ...old.data,
+                folders: old.data.folders.map((f) =>
+                  f.id === folderId
+                    ? {
+                        ...f,
+                        name: data.name ?? f.name,
+                        color: data.color ?? f.color,
+                        icon: data.icon ?? f.icon,
+                      }
+                    : f,
+                ),
+              },
+            };
+          },
+        );
+
+        return { previousData };
+      },
+      onError: (error: unknown, _variables, context) => {
+        if (context?.previousData) {
+          for (const [queryKey, data] of context.previousData) {
+            queryClient.setQueryData(queryKey, data);
+          }
+        }
+        if (error instanceof ApiError) {
+          const detail = (error.response as any)?.detail ?? "";
+          if (
+            typeof detail === "string" &&
+            detail.toLowerCase().includes("already exists")
+          ) {
+            form.setError("folderName", {
+              message: "A folder with this name already exists",
+            });
+            return;
+          }
+        }
+        toast({
+          title: "Error",
+          description: "Failed to update folder. Please try again.",
+          variant: "destructive",
+        });
+      },
+      onSuccess: () => {
+        setIsOpen(false);
+        toast({
+          title: "Folder updated",
+          description: "Your folder has been updated successfully.",
+        });
+      },
+      onSettled: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+      },
+    },
+  });
+
+  function onSubmit(values: z.infer<typeof editFolderSchema>) {
+    updateFolder({
+      folderId: folder.id,
+      data: {
+        name: values.folderName.trim(),
+        color: values.folderColor,
+        icon: values.folderIcon,
+      },
+    });
+  }
+
+  return (
+    <Dialog
+      title="Edit Folder"
+      styling={{ maxWidth: "30rem" }}
+      controlled={{
+        isOpen,
+        set: setIsOpen,
+      }}
+    >
+      <Dialog.Content>
+        <Form
+          form={form}
+          onSubmit={(values) => onSubmit(values)}
+          className="flex flex-col justify-center gap-2 px-1"
+        >
+          <FormField
+            control={form.control}
+            name="folderName"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Input
+                    {...field}
+                    id={field.name}
+                    label="Folder name"
+                    placeholder="Enter folder name"
+                    className="w-full"
+                    wrapperClassName="!mb-0"
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderColor"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Select
+                    id="folderColor"
+                    label="Folder color"
+                    placeholder="Select a color"
+                    value={field.value}
+                    onValueChange={field.onChange}
+                    wrapperClassName="!mb-0"
+                    options={FOLDER_COLORS.map((color) => ({
+                      value: color.value,
+                      label: color.label,
+                      icon: (
+                        <div
+                          className="h-4 w-4 rounded-full"
+                          style={{ backgroundColor: color.value }}
+                        />
+                      ),
+                    }))}
+                    renderItem={(option) => (
+                      <div className="flex items-center gap-2">
+                        {option.icon}
+                        <span>{option.label}</span>
+                      </div>
+                    )}
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderIcon"
+            render={({ field }) => (
+              <FormItem>
+                <div className="flex flex-col gap-2">
+                  <Text variant="large-medium" as="span" className="text-black">
+                    Folder icon
+                  </Text>
+                  <div className="flex flex-col gap-3">
+                    <div className="flex items-center gap-3">
+                      <Text variant="small" className="text-zinc-500">
+                        Selected:
+                      </Text>
+                      <div className="flex h-10 w-10 items-center justify-center rounded-lg border border-zinc-200 bg-zinc-50 text-2xl">
+                        {form.watch("folderIcon") || (
+                          <span className="text-sm text-zinc-400">—</span>
+                        )}
+                      </div>
+                    </div>
+                    <div className="h-[295px] w-full overflow-hidden">
+                      <EmojiPicker
+                        onEmojiSelect={(emoji) => {
+                          field.onChange(emoji);
+                        }}
+                        emojiSize={32}
+                        className="w-full rounded-2xl px-2"
+                      >
+                        <EmojiPicker.Group className="pt-2">
+                          <EmojiPicker.List
+                            hideStickyHeader
+                            containerHeight={295}
+                          />
+                        </EmojiPicker.Group>
+                      </EmojiPicker>
+                    </div>
+                  </div>
+                  <FormMessage />
+                </div>
+              </FormItem>
+            )}
+          />
+
+          <Button
+            type="submit"
+            variant="primary"
+            className="mt-2 min-w-[18rem]"
+            disabled={!form.formState.isValid || isPending}
+            loading={isPending}
+          >
+            Save Changes
+          </Button>
+        </Form>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibrarySubSection/LibrarySubSection.tsx

@@ -0,0 +1,17 @@
+import LibraryFolderCreationDialog from "../LibraryFolderCreationDialog/LibraryFolderCreationDialog";
+import { LibraryTabs, Tab } from "../LibraryTabs/LibraryTabs";
+
+interface Props {
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
+}
+
+export function LibrarySubSection({ tabs, activeTab, onTabChange }: Props) {
+  return (
+    <div className="flex justify-between items-center gap-4">
+      <LibraryTabs tabs={tabs} activeTab={activeTab} onTabChange={onTabChange} />
+      <LibraryFolderCreationDialog />
+    </div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryTabs/LibraryTabs.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { motion } from "framer-motion";
+import { cn } from "@/lib/utils";
+import { Icon } from "@phosphor-icons/react";
+import { useFavoriteAnimation } from "../../context/FavoriteAnimationContext";
+
+export interface Tab {
+  id: string;
+  title: string;
+  icon: Icon;
+}
+
+interface Props {
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
+  layoutId?: string;
+}
+
+export function LibraryTabs({
+  tabs,
+  activeTab,
+  onTabChange,
+  layoutId = "library-tabs",
+}: Props) {
+  const { registerFavoritesTabRef } = useFavoriteAnimation();
+
+  return (
+    <div className="flex items-center gap-2">
+      {tabs.map((tab) => (
+        <TabButton
+          key={tab.id}
+          tab={tab}
+          isActive={activeTab === tab.id}
+          onSelect={onTabChange}
+          layoutId={layoutId}
+          onRefReady={
+            tab.id === "favorites" ? registerFavoritesTabRef : undefined
+          }
+        />
+      ))}
+    </div>
+  );
+}
+
+interface TabButtonProps {
+  tab: Tab;
+  isActive: boolean;
+  onSelect: (tabId: string) => void;
+  layoutId: string;
+  onRefReady?: (element: HTMLElement | null) => void;
+}
+
+function TabButton({
+  tab,
+  isActive,
+  onSelect,
+  layoutId,
+  onRefReady,
+}: TabButtonProps) {
+  const [isLoaded, setIsLoaded] = useState(false);
+  const buttonRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isActive && !isLoaded) {
+      setIsLoaded(true);
+    }
+  }, [isActive, isLoaded]);
+
+  useEffect(() => {
+    if (onRefReady) {
+      onRefReady(buttonRef.current);
+    }
+  }, [onRefReady]);
+
+  const ButtonIcon = tab.icon;
+  const activeColor = "text-primary";
+
+  return (
+    <motion.div
+      ref={buttonRef}
+      layoutId={`${layoutId}-button-${tab.id}`}
+      transition={{
+        layout: {
+          type: "spring",
+          damping: 20,
+          stiffness: 230,
+          mass: 1.2,
+          ease: [0.215, 0.61, 0.355, 1],
+        },
+      }}
+      onClick={() => {
+        onSelect(tab.id);
+        setIsLoaded(true);
+      }}
+      className="flex h-fit w-fit"
+      style={{ willChange: "transform" }}
+    >
+      <motion.div
+        layout
+        transition={{
+          layout: {
+            type: "spring",
+            damping: 20,
+            stiffness: 230,
+            mass: 1.2,
+          },
+        }}
+        className={cn(
+          "flex h-fit cursor-pointer items-center gap-1.5 overflow-hidden border border-zinc-200 px-3 py-2 text-black transition-colors duration-75 ease-out hover:border-zinc-300 hover:bg-zinc-300",
+          isActive && activeColor,
+          isActive ? "px-4" : "px-3",
+        )}
+        style={{
+          borderRadius: "25px",
+        }}
+      >
+        <motion.div
+          layoutId={`${layoutId}-icon-${tab.id}`}
+          className="shrink-0"
+        >
+          <ButtonIcon size={18} />
+        </motion.div>
+        {isActive && (
+          <motion.div
+            className="flex items-center"
+            initial={isLoaded ? { opacity: 0, filter: "blur(4px)" } : false}
+            animate={{ opacity: 1, filter: "blur(0px)" }}
+            transition={{
+              duration: isLoaded ? 0.2 : 0,
+              ease: [0.86, 0, 0.07, 1],
+            }}
+          >
+            <motion.span
+              layoutId={`${layoutId}-text-${tab.id}`}
+              className="font-sans text-sm font-medium text-black"
+            >
+              {tab.title}
+            </motion.span>
+          </motion.div>
+        )}
+      </motion.div>
+    </motion.div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/MoveToFolderDialog/MoveToFolderDialog.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { Button } from "@/components/atoms/Button/Button";
+import { Input } from "@/components/atoms/Input/Input";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import {
+  useGetV2ListLibraryFolders,
+  usePostV2BulkMoveAgents,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { getGetV2ListLibraryAgentsQueryKey } from "@/app/api/__generated__/endpoints/library/library";
+import { okData } from "@/app/api/helpers";
+import { useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+
+interface Props {
+  agentId: string;
+  agentName: string;
+  currentFolderId?: string | null;
+  isOpen: boolean;
+  setIsOpen: (open: boolean) => void;
+}
+
+export function MoveToFolderDialog({
+  agentId,
+  agentName,
+  currentFolderId,
+  isOpen,
+  setIsOpen,
+}: Props) {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+  const [search, setSearch] = useState("");
+
+  const { data: foldersData } = useGetV2ListLibraryFolders(undefined, {
+    query: { select: okData },
+  });
+
+  const { mutate: moveAgent, isPending } = usePostV2BulkMoveAgents({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        setIsOpen(false);
+        setSearch("");
+        toast({
+          title: "Agent moved",
+          description: `"${agentName}" has been moved.`,
+        });
+      },
+      onError: () => {
+        toast({
+          title: "Error",
+          description: "Failed to move agent. Please try again.",
+          variant: "destructive",
+        });
+      },
+    },
+  });
+
+  const folders = (foldersData?.folders ?? []).filter(
+    (f) =>
+      f.id !== currentFolderId &&
+      f.name.toLowerCase().includes(search.toLowerCase()),
+  );
+
+  function handleMoveToFolder(folderId: string) {
+    moveAgent({
+      data: {
+        agent_ids: [agentId],
+        folder_id: folderId,
+      },
+    });
+  }
+
+  return (
+    <Dialog
+      controlled={{ isOpen, set: setIsOpen }}
+      styling={{ maxWidth: "28rem" }}
+      title="Move to folder"
+      onClose={() => {
+        setSearch("");
+      }}
+    >
+      <Dialog.Content>
+        <div className="flex flex-col gap-3">
+          <Input
+            id="search-folders"
+            label="Search folders"
+            placeholder="Search folders..."
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            className="w-full"
+          />
+          <div className="max-h-[280px] overflow-y-auto">
+            {folders.length === 0 ? (
+              <div className="flex h-20 items-center justify-center">
+                <Text variant="small" className="text-zinc-400">
+                  No folders found
+                </Text>
+              </div>
+            ) : (
+              <div className="flex flex-col gap-1">
+                {folders.map((folder) => (
+                  <Button
+                    key={folder.id}
+                    variant="ghost"
+                    className="w-full justify-start gap-3 px-3 py-2.5"
+                    disabled={isPending}
+                    onClick={() => handleMoveToFolder(folder.id)}
+                  >
+                    <span className="text-lg">{folder.icon ?? "📁"}</span>
+                    <div className="flex flex-col items-start">
+                      <Text variant="small-medium">{folder.name}</Text>
+                      <Text variant="small" className="text-zinc-400">
+                        {folder.agent_count ?? 0}{" "}
+                        {(folder.agent_count ?? 0) === 1 ? "agent" : "agents"}
+                      </Text>
+                    </div>
+                  </Button>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/context/FavoriteAnimationContext.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { createContext, useContext, useState, useCallback, useRef } from "react";
+import { FlyingHeart } from "../components/FlyingHeart/FlyingHeart";
+
+interface FavoriteAnimationContextType {
+  triggerFavoriteAnimation: (startPosition: { x: number; y: number }) => void;
+  registerFavoritesTabRef: (element: HTMLElement | null) => void;
+}
+
+const FavoriteAnimationContext = createContext<FavoriteAnimationContextType | null>(null);
+
+interface FavoriteAnimationProviderProps {
+  children: React.ReactNode;
+  onAnimationComplete?: () => void;
+}
+
+export function FavoriteAnimationProvider({
+  children,
+  onAnimationComplete,
+}: FavoriteAnimationProviderProps) {
+  const [animationState, setAnimationState] = useState<{
+    startPosition: { x: number; y: number } | null;
+    targetPosition: { x: number; y: number } | null;
+  }>({
+    startPosition: null,
+    targetPosition: null,
+  });
+
+  const favoritesTabRef = useRef<HTMLElement | null>(null);
+
+  const registerFavoritesTabRef = useCallback((element: HTMLElement | null) => {
+    favoritesTabRef.current = element;
+  }, []);
+
+  const triggerFavoriteAnimation = useCallback(
+    (startPosition: { x: number; y: number }) => {
+      if (favoritesTabRef.current) {
+        const rect = favoritesTabRef.current.getBoundingClientRect();
+        const targetPosition = {
+          x: rect.left + rect.width / 2 - 12,
+          y: rect.top + rect.height / 2 - 12,
+        };
+        setAnimationState({ startPosition, targetPosition });
+      }
+    },
+    []
+  );
+
+  function handleAnimationComplete() {
+    setAnimationState({ startPosition: null, targetPosition: null });
+    onAnimationComplete?.();
+  }
+
+  return (
+    <FavoriteAnimationContext.Provider
+      value={{ triggerFavoriteAnimation, registerFavoritesTabRef }}
+    >
+      {children}
+      <FlyingHeart
+        startPosition={animationState.startPosition}
+        targetPosition={animationState.targetPosition}
+        onAnimationComplete={handleAnimationComplete}
+      />
+    </FavoriteAnimationContext.Provider>
+  );
+}
+
+export function useFavoriteAnimation() {
+  const context = useContext(FavoriteAnimationContext);
+  if (!context) {
+    throw new Error(
+      "useFavoriteAnimation must be used within FavoriteAnimationProvider"
+    );
+  }
+  return context;
+}

autogpt_platform/frontend/src/app/(platform)/library/page.tsx

@@ -1,28 +1,53 @@
 "use client";
 
-import { useEffect } from "react";
-import { FavoritesSection } from "./components/FavoritesSection/FavoritesSection";
+import { useEffect, useState, useCallback } from "react";
+import { HeartIcon, ListIcon } from "@phosphor-icons/react";
 import { LibraryActionHeader } from "./components/LibraryActionHeader/LibraryActionHeader";
 import { LibraryAgentList } from "./components/LibraryAgentList/LibraryAgentList";
+import { Tab } from "./components/LibraryTabs/LibraryTabs";
 import { useLibraryListPage } from "./components/useLibraryListPage";
+import { FavoriteAnimationProvider } from "./context/FavoriteAnimationContext";
+
+const LIBRARY_TABS: Tab[] = [
+  { id: "all", title: "All", icon: ListIcon },
+  { id: "favorites", title: "Favorites", icon: HeartIcon },
+];
 
 export default function LibraryPage() {
   const { searchTerm, setSearchTerm, librarySort, setLibrarySort } =
     useLibraryListPage();
+  const [selectedFolderId, setSelectedFolderId] = useState<string | null>(null);
+  const [activeTab, setActiveTab] = useState(LIBRARY_TABS[0].id);
 
   useEffect(() => {
     document.title = "Library – AutoGPT Platform";
   }, []);
 
+  function handleTabChange(tabId: string) {
+    setActiveTab(tabId);
+    setSelectedFolderId(null);
+  }
+
+  const handleFavoriteAnimationComplete = useCallback(() => {
+    setActiveTab("favorites");
+    setSelectedFolderId(null);
+  }, []);
+
   return (
-    <main className="pt-160 container min-h-screen space-y-4 pb-20 pt-16 sm:px-8 md:px-12">
-      <LibraryActionHeader setSearchTerm={setSearchTerm} />
-      <FavoritesSection searchTerm={searchTerm} />
-      <LibraryAgentList
-        searchTerm={searchTerm}
-        librarySort={librarySort}
-        setLibrarySort={setLibrarySort}
-      />
-    </main>
+    <FavoriteAnimationProvider onAnimationComplete={handleFavoriteAnimationComplete}>
+      <main className="pt-160 container min-h-screen space-y-4 pb-20 pt-16 sm:px-8 md:px-12">
+        <LibraryActionHeader setSearchTerm={setSearchTerm} />
+        <LibraryAgentList
+          searchTerm={searchTerm}
+          librarySort={librarySort}
+          setLibrarySort={setLibrarySort}
+          selectedFolderId={selectedFolderId}
+          onFolderSelect={setSelectedFolderId}
+          tabs={LIBRARY_TABS}
+          activeTab={activeTab}
+          onTabChange={handleTabChange}
+        />
+      </main>
+    </FavoriteAnimationProvider>
   );
 }

autogpt_platform/frontend/src/app/api/openapi.json

@@ -3588,6 +3588,29 @@
               "title": "Page Size"
             },
             "description": "Number of agents per page (must be >= 1)"
+          },
+          {
+            "name": "folder_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [{ "type": "string" }, { "type": "null" }],
+              "description": "Filter by folder ID",
+              "title": "Folder Id"
+            },
+            "description": "Filter by folder ID"
+          },
+          {
+            "name": "include_root_only",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "description": "Only return agents without a folder (root-level agents)",
+              "default": false,
+              "title": "Include Root Only"
+            },
+            "description": "Only return agents without a folder (root-level agents)"
           }
         ],
         "responses": {
@@ -3955,6 +3978,340 @@
         }
       }
     },
+    "/api/library/folders": {
+      "get": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "List Library Folders",
+        "description": "List folders for the authenticated user.\n\nArgs:\n    user_id: ID of the authenticated user.\n    parent_id: Optional parent folder ID to filter by.\n    include_counts: Whether to include agent and subfolder counts.\n\nReturns:\n    A FolderListResponse containing folders.",
+        "operationId": "getV2List library folders",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "parent_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [{ "type": "string" }, { "type": "null" }],
+              "description": "Filter by parent folder ID. If not provided, returns root-level folders.",
+              "title": "Parent Id"
+            },
+            "description": "Filter by parent folder ID. If not provided, returns root-level folders."
+          },
+          {
+            "name": "include_counts",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "description": "Include agent and subfolder counts",
+              "default": true,
+              "title": "Include Counts"
+            },
+            "description": "Include agent and subfolder counts"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of folders",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/FolderListResponse" }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      },
+      "post": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Create Folder",
+        "description": "Create a new folder.\n\nArgs:\n    payload: The folder creation request.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The created LibraryFolder.",
+        "operationId": "postV2Create folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/FolderCreateRequest" }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Folder created successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "400": { "description": "Validation error" },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Parent folder not found" },
+          "409": { "description": "Folder name conflict" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      }
+    },
+    "/api/library/folders/agents/bulk-move": {
+      "post": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Bulk Move Agents",
+        "description": "Move multiple agents to a folder.\n\nArgs:\n    payload: The bulk move request with agent IDs and target folder.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The updated LibraryAgents.",
+        "operationId": "postV2Bulk move agents",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/BulkMoveAgentsRequest" }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Agents moved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": { "$ref": "#/components/schemas/LibraryAgent" },
+                  "type": "array",
+                  "title": "Response Postv2Bulk Move Agents"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        },
+        "security": [{ "HTTPBearerJWT": [] }]
+      }
+    },
+    "/api/library/folders/tree": {
+      "get": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Get Folder Tree",
+        "description": "Get the full folder tree for the authenticated user.\n\nArgs:\n    user_id: ID of the authenticated user.\n\nReturns:\n    A FolderTreeResponse containing the nested folder structure.",
+        "operationId": "getV2Get folder tree",
+        "responses": {
+          "200": {
+            "description": "Folder tree structure",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/FolderTreeResponse" }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "500": { "description": "Server error" }
+        },
+        "security": [{ "HTTPBearerJWT": [] }]
+      }
+    },
+    "/api/library/folders/{folder_id}": {
+      "delete": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Delete Folder",
+        "description": "Soft-delete a folder and all its contents.\n\nArgs:\n    folder_id: ID of the folder to delete.\n    user_id: ID of the authenticated user.\n\nReturns:\n    204 No Content if successful.",
+        "operationId": "deleteV2Delete folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "responses": {
+          "204": { "description": "Folder deleted successfully" },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      },
+      "get": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Get Folder",
+        "description": "Get a specific folder.\n\nArgs:\n    folder_id: ID of the folder to retrieve.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The requested LibraryFolder.",
+        "operationId": "getV2Get folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Folder details",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      },
+      "patch": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Update Folder",
+        "description": "Update a folder's properties.\n\nArgs:\n    folder_id: ID of the folder to update.\n    payload: The folder update request.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The updated LibraryFolder.",
+        "operationId": "patchV2Update folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/FolderUpdateRequest" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Folder updated successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "400": { "description": "Validation error" },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "409": { "description": "Folder name conflict" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      }
+    },
+    "/api/library/folders/{folder_id}/move": {
+      "post": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Move Folder",
+        "description": "Move a folder to a new parent.\n\nArgs:\n    folder_id: ID of the folder to move.\n    payload: The move request with target parent.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The moved LibraryFolder.",
+        "operationId": "postV2Move folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/FolderMoveRequest" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Folder moved successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error (circular reference, depth exceeded)"
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder or target parent not found" },
+          "409": { "description": "Folder name conflict in target location" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      }
+    },
     "/api/library/presets": {
       "get": {
         "tags": ["v2", "presets"],
@@ -7336,6 +7693,23 @@
         "required": ["file"],
         "title": "Body_postV2Upload submission media"
       },
+      "BulkMoveAgentsRequest": {
+        "properties": {
+          "agent_ids": {
+            "items": { "type": "string" },
+            "type": "array",
+            "title": "Agent Ids"
+          },
+          "folder_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Id"
+          }
+        },
+        "type": "object",
+        "required": ["agent_ids"],
+        "title": "BulkMoveAgentsRequest",
+        "description": "Request model for moving multiple agents to a folder."
+      },
       "ChangelogEntry": {
         "properties": {
           "version": { "type": "string", "title": "Version" },
@@ -8020,6 +8394,96 @@
         "title": "ExecutionStartedResponse",
         "description": "Response for run/schedule actions."
       },
+      "FolderCreateRequest": {
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 100,
+            "minLength": 1,
+            "title": "Name"
+          },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [
+              { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+              { "type": "null" }
+            ],
+            "title": "Color",
+            "description": "Hex color code (#RRGGBB)"
+          },
+          "parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Parent Id"
+          }
+        },
+        "type": "object",
+        "required": ["name"],
+        "title": "FolderCreateRequest",
+        "description": "Request model for creating a folder."
+      },
+      "FolderListResponse": {
+        "properties": {
+          "folders": {
+            "items": { "$ref": "#/components/schemas/LibraryFolder" },
+            "type": "array",
+            "title": "Folders"
+          },
+          "pagination": { "$ref": "#/components/schemas/Pagination" }
+        },
+        "type": "object",
+        "required": ["folders", "pagination"],
+        "title": "FolderListResponse",
+        "description": "Response schema for a list of folders."
+      },
+      "FolderMoveRequest": {
+        "properties": {
+          "target_parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Target Parent Id"
+          }
+        },
+        "type": "object",
+        "title": "FolderMoveRequest",
+        "description": "Request model for moving a folder to a new parent."
+      },
+      "FolderTreeResponse": {
+        "properties": {
+          "tree": {
+            "items": { "$ref": "#/components/schemas/LibraryFolderTree" },
+            "type": "array",
+            "title": "Tree"
+          }
+        },
+        "type": "object",
+        "required": ["tree"],
+        "title": "FolderTreeResponse",
+        "description": "Response schema for folder tree structure."
+      },
+      "FolderUpdateRequest": {
+        "properties": {
+          "name": {
+            "anyOf": [
+              { "type": "string", "maxLength": 100, "minLength": 1 },
+              { "type": "null" }
+            ],
+            "title": "Name"
+          },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Color"
+          }
+        },
+        "type": "object",
+        "title": "FolderUpdateRequest",
+        "description": "Request model for updating a folder."
+      },
       "Graph": {
         "properties": {
           "id": { "type": "string", "title": "Id" },
@@ -8908,6 +9372,14 @@
             "title": "Is Latest Version"
           },
           "is_favorite": { "type": "boolean", "title": "Is Favorite" },
+          "folder_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Id"
+          },
+          "folder_name": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Name"
+          },
           "recommended_schedule_cron": {
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Recommended Schedule Cron"
@@ -9175,12 +9647,109 @@
               { "type": "null" }
             ],
             "description": "User-specific settings for this library agent"
+          },
+          "folder_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Id",
+            "description": "Folder ID to move agent to (empty string for root)"
           }
         },
         "type": "object",
         "title": "LibraryAgentUpdateRequest",
         "description": "Schema for updating a library agent via PUT.\n\nIncludes flags for auto-updating version, marking as favorite,\narchiving, or deleting."
       },
+      "LibraryFolder": {
+        "properties": {
+          "id": { "type": "string", "title": "Id" },
+          "user_id": { "type": "string", "title": "User Id" },
+          "name": { "type": "string", "title": "Name" },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Color"
+          },
+          "parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Parent Id"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Updated At"
+          },
+          "agent_count": {
+            "type": "integer",
+            "title": "Agent Count",
+            "default": 0
+          },
+          "subfolder_count": {
+            "type": "integer",
+            "title": "Subfolder Count",
+            "default": 0
+          }
+        },
+        "type": "object",
+        "required": ["id", "user_id", "name", "created_at", "updated_at"],
+        "title": "LibraryFolder",
+        "description": "Represents a folder for organizing library agents."
+      },
+      "LibraryFolderTree": {
+        "properties": {
+          "id": { "type": "string", "title": "Id" },
+          "user_id": { "type": "string", "title": "User Id" },
+          "name": { "type": "string", "title": "Name" },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Color"
+          },
+          "parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Parent Id"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Updated At"
+          },
+          "agent_count": {
+            "type": "integer",
+            "title": "Agent Count",
+            "default": 0
+          },
+          "subfolder_count": {
+            "type": "integer",
+            "title": "Subfolder Count",
+            "default": 0
+          },
+          "children": {
+            "items": { "$ref": "#/components/schemas/LibraryFolderTree" },
+            "type": "array",
+            "title": "Children",
+            "default": []
+          }
+        },
+        "type": "object",
+        "required": ["id", "user_id", "name", "created_at", "updated_at"],
+        "title": "LibraryFolderTree",
+        "description": "Folder with nested children for tree view."
+      },
       "Link": {
         "properties": {
           "id": { "type": "string", "title": "Id" },

classic/.flake8

@@ -1,15 +1,12 @@
 [flake8]
 max-line-length = 88
-extend-ignore = E203
 exclude =
     .tox,
     __pycache__,
     *.pyc,
-    .env,
-    venv*,
-    .venv,
-    reports,
-    dist,
-    data,
-    .benchmark_workspaces,
-    .autogpt,
+    .env
+    venv*/*,
+    .venv/*,
+    reports/*,
+    dist/*,
+    data/*,

classic/CLAUDE.md

@@ -1,291 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-AutoGPT Classic is an experimental, **unsupported** project demonstrating autonomous GPT-4 operation. Dependencies will not be updated, and the codebase contains known vulnerabilities. This is preserved for educational/historical purposes.
-
-## Repository Structure
-
-```
-classic/
-├── pyproject.toml          # Single consolidated Poetry project
-├── poetry.lock             # Single lock file
-├── forge/
-│   └── forge/              # Core agent framework package
-├── original_autogpt/
-│   └── autogpt/            # AutoGPT agent package
-├── direct_benchmark/
-│   └── direct_benchmark/   # Benchmark harness package
-└── benchmark/              # Challenge definitions (data, not code)
-```
-
-All packages are managed by a single `pyproject.toml` at the classic/ root.
-
-## Common Commands
-
-### Setup & Install
-```bash
-# Install everything from classic/ directory
-cd classic
-poetry install
-```
-
-### Running Agents
-```bash
-# Run forge agent
-poetry run python -m forge
-
-# Run original autogpt server
-poetry run serve --debug
-
-# Run autogpt CLI
-poetry run autogpt
-```
-
-Agents run on `http://localhost:8000` by default.
-
-### Benchmarking
-```bash
-# Run benchmarks
-poetry run direct-benchmark run
-
-# Run specific strategies and models
-poetry run direct-benchmark run \
-    --strategies one_shot,rewoo \
-    --models claude \
-    --parallel 4
-
-# Run a single test
-poetry run direct-benchmark run --tests ReadFile
-
-# List available commands
-poetry run direct-benchmark --help
-```
-
-### Testing
-```bash
-poetry run pytest                              # All tests
-poetry run pytest forge/tests/                 # Forge tests only
-poetry run pytest original_autogpt/tests/      # AutoGPT tests only
-poetry run pytest -k test_name                 # Single test by name
-poetry run pytest path/to/test.py              # Specific test file
-poetry run pytest --cov                        # With coverage
-```
-
-### Linting & Formatting
-
-Run from the classic/ directory:
-
-```bash
-# Format everything (recommended to run together)
-poetry run black . && poetry run isort .
-
-# Check formatting (CI-style, no changes)
-poetry run black --check . && poetry run isort --check-only .
-
-# Lint
-poetry run flake8        # Style linting
-
-# Type check
-poetry run pyright       # Type checking (some errors are expected in infrastructure code)
-```
-
-Note: Always run linters over the entire directory, not specific files, for best results.
-
-## Architecture
-
-### Forge (Core Framework)
-The `forge` package is the foundation that other components depend on:
-- `forge/agent/` - Agent implementation and protocols
-- `forge/llm/` - Multi-provider LLM integrations (OpenAI, Anthropic, Groq, LiteLLM)
-- `forge/components/` - Reusable agent components
-- `forge/file_storage/` - File system abstraction
-- `forge/config/` - Configuration management
-
-### Original AutoGPT
-- `original_autogpt/autogpt/app/` - CLI application entry points
-- `original_autogpt/autogpt/agents/` - Agent implementations
-- `original_autogpt/autogpt/agent_factory/` - Agent creation logic
-
-### Direct Benchmark
-Benchmark harness for testing agent performance:
-- `direct_benchmark/direct_benchmark/` - CLI and harness code
-- `benchmark/agbenchmark/challenges/` - Test cases organized by category (code, retrieval, data, etc.)
-- Reports generated in `direct_benchmark/reports/`
-
-### Package Structure
-All three packages are included in a single Poetry project. Imports are fully qualified:
-- `from forge.agent.base import BaseAgent`
-- `from autogpt.agents.agent import Agent`
-- `from direct_benchmark.harness import BenchmarkHarness`
-
-## Code Style
-
-- Python 3.12 target
-- Line length: 88 characters (Black default)
-- Black for formatting, isort for imports (profile="black")
-- Type hints with Pyright checking
-
-## Testing Patterns
-
-- Async support via pytest-asyncio
-- Fixtures defined in `conftest.py` files provide: `tmp_project_root`, `storage`, `config`, `llm_provider`, `agent`
-- Tests requiring API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY) will skip if not set
-
-## Environment Setup
-
-Copy `.env.example` to `.env` in the relevant directory and add your API keys:
-```bash
-cp .env.example .env
-# Edit .env with your OPENAI_API_KEY, etc.
-```
-
-## Workspaces
-
-Agents operate within a **workspace** - a directory containing all agent data and files. The workspace root defaults to the current working directory.
-
-### Workspace Structure
-
-```
-{workspace}/
-├── .autogpt/
-│   ├── autogpt.yaml              # Workspace-level permissions
-│   ├── ap_server.db              # Agent Protocol database (server mode)
-│   └── agents/
-│       └── AutoGPT-{agent_id}/
-│           ├── state.json        # Agent profile, directives, action history
-│           ├── permissions.yaml  # Agent-specific permission overrides
-│           └── workspace/        # Agent's sandboxed working directory
-```
-
-### Key Concepts
-
-- **Multiple agents** can coexist in the same workspace (each gets its own subdirectory)
-- **File access** is sandboxed to the agent's `workspace/` directory by default
-- **State persistence** - agent state saves to `state.json` and survives across sessions
-- **Storage backends** - supports local filesystem, S3, and GCS (via `FILE_STORAGE_BACKEND` env var)
-
-### Specifying a Workspace
-
-```bash
-# Default: uses current directory
-cd /path/to/my/project && poetry run autogpt
-
-# Or specify explicitly via CLI (if supported)
-poetry run autogpt --workspace /path/to/workspace
-```
-
-## Settings Location
-
-Configuration uses a **layered system** with three levels (in order of precedence):
-
-### 1. Environment Variables (Global)
-
-Loaded from `.env` file in the working directory:
-
-```bash
-# Required
-OPENAI_API_KEY=sk-...
-
-# Optional LLM settings
-SMART_LLM=gpt-4o                    # Model for complex reasoning
-FAST_LLM=gpt-4o-mini                # Model for simple tasks
-EMBEDDING_MODEL=text-embedding-3-small
-
-# Optional search providers (for web search component)
-TAVILY_API_KEY=tvly-...
-SERPER_API_KEY=...
-GOOGLE_API_KEY=...
-GOOGLE_CUSTOM_SEARCH_ENGINE_ID=...
-
-# Optional infrastructure
-LOG_LEVEL=DEBUG                     # DEBUG, INFO, WARNING, ERROR
-DATABASE_STRING=sqlite:///agent.db  # Agent Protocol database
-PORT=8000                           # Server port
-FILE_STORAGE_BACKEND=local          # local, s3, or gcs
-```
-
-### 2. Workspace Settings (`{workspace}/.autogpt/autogpt.yaml`)
-
-Workspace-wide permissions that apply to **all agents** in this workspace:
-
-```yaml
-allow:
-  - read_file({workspace}/**)
-  - write_to_file({workspace}/**)
-  - list_folder({workspace}/**)
-  - web_search(*)
-
-deny:
-  - read_file(**.env)
-  - read_file(**.env.*)
-  - read_file(**.key)
-  - read_file(**.pem)
-  - execute_shell(rm -rf:*)
-  - execute_shell(sudo:*)
-```
-
-Auto-generated with sensible defaults if missing.
-
-### 3. Agent Settings (`{workspace}/.autogpt/agents/{id}/permissions.yaml`)
-
-Agent-specific permission overrides:
-
-```yaml
-allow:
-  - execute_python(*)
-  - web_search(*)
-
-deny:
-  - execute_shell(*)
-```
-
-## Permissions
-
-The permission system uses **pattern matching** with a **first-match-wins** evaluation order.
-
-### Permission Check Order
-
-1. Agent deny list → **Block**
-2. Workspace deny list → **Block**
-3. Agent allow list → **Allow**
-4. Workspace allow list → **Allow**
-5. Session denied list → **Block** (commands denied during this session)
-6. **Prompt user** → Interactive approval (if in interactive mode)
-
-### Pattern Syntax
-
-Format: `command_name(glob_pattern)`
-
-| Pattern | Description |
-|---------|-------------|
-| `read_file({workspace}/**)` | Read any file in workspace (recursive) |
-| `write_to_file({workspace}/*.txt)` | Write only .txt files in workspace root |
-| `execute_shell(python:**)` | Execute Python commands only |
-| `execute_shell(git:*)` | Execute any git command |
-| `web_search(*)` | Allow all web searches |
-
-Special tokens:
-- `{workspace}` - Replaced with actual workspace path
-- `**` - Matches any path including `/`
-- `*` - Matches any characters except `/`
-
-### Interactive Approval Scopes
-
-When prompted for permission, users can choose:
-
-| Scope | Effect |
-|-------|--------|
-| **Once** | Allow this one time only (not saved) |
-| **Agent** | Always allow for this agent (saves to agent `permissions.yaml`) |
-| **Workspace** | Always allow for all agents (saves to `autogpt.yaml`) |
-| **Deny** | Deny this command (saves to appropriate deny list) |
-
-### Default Security
-
-Out of the box, the following are **denied by default**:
-- Reading sensitive files (`.env`, `.key`, `.pem`)
-- Destructive shell commands (`rm -rf`, `sudo`)
-- Operations outside the workspace directory

classic/CLI-USAGE.md

@@ -0,0 +1,182 @@
+## CLI Documentation
+
+This document describes how to interact with the project's CLI (Command Line Interface). It includes the types of outputs you can expect from each command. Note that the `agents stop` command will terminate any process running on port 8000.
+
+### 1. Entry Point for the CLI
+
+Running the `./run` command without any parameters will display the help message, which provides a list of available commands and options. Additionally, you can append `--help` to any command to view help information specific to that command.
+
+```sh
+./run
+```
+
+**Output**:
+
+```
+Usage: cli.py [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  agent     Commands to create, start and stop agents
+  benchmark  Commands to start the benchmark and list tests and categories
+  setup      Installs dependencies needed for your system.
+```
+
+If you need assistance with any command, simply add the `--help` parameter to the end of your command, like so:
+
+```sh
+./run COMMAND --help
+```
+
+This will display a detailed help message regarding that specific command, including a list of any additional options and arguments it accepts.
+
+### 2. Setup Command
+
+```sh
+./run setup
+```
+
+**Output**:
+
+```
+Setup initiated
+Installation has been completed.
+```
+
+This command initializes the setup of the project.
+
+### 3. Agents Commands
+
+**a. List All Agents**
+
+```sh
+./run agent list
+```
+
+**Output**:
+
+```
+Available agents: 🤖
+        🐙 forge
+        🐙 autogpt
+```
+
+Lists all the available agents.
+
+**b. Create a New Agent**
+
+```sh
+./run agent create my_agent
+```
+
+**Output**:
+
+```
+🎉 New agent 'my_agent' created and switched to the new directory in agents folder.
+```
+
+Creates a new agent named 'my_agent'.
+
+**c. Start an Agent**
+
+```sh
+./run agent start my_agent
+```
+
+**Output**:
+
+```
+... (ASCII Art representing the agent startup)
+[Date and Time] [forge.sdk.db] [DEBUG] 🐛  Initializing AgentDB with database_string: sqlite:///agent.db
+[Date and Time] [forge.sdk.agent] [INFO] 📝  Agent server starting on http://0.0.0.0:8000
+```
+
+Starts the 'my_agent' and displays startup ASCII art and logs.
+
+**d. Stop an Agent**
+
+```sh
+./run agent stop
+```
+
+**Output**:
+
+```
+Agent stopped
+```
+
+Stops the running agent.
+
+### 4. Benchmark Commands
+
+**a. List Benchmark Categories**
+
+```sh
+./run benchmark categories list
+```
+
+**Output**:
+
+```
+Available categories: 📚
+        📖 code
+        📖 safety
+        📖 memory
+        ... (and so on)
+```
+
+Lists all available benchmark categories.
+
+**b. List Benchmark Tests**
+
+```sh
+./run benchmark tests list
+```
+
+**Output**:
+
+```
+Available tests: 📚
+        📖 interface
+                🔬 Search - TestSearch
+                🔬 Write File - TestWriteFile
+        ... (and so on)
+```
+
+Lists all available benchmark tests.
+
+**c. Show Details of a Benchmark Test**
+
+```sh
+./run benchmark tests details TestWriteFile
+```
+
+**Output**:
+
+```
+TestWriteFile
+-------------
+
+        Category:  interface
+        Task:  Write the word 'Washington' to a .txt file
+        ... (and other details)
+```
+
+Displays the details of the 'TestWriteFile' benchmark test.
+
+**d. Start Benchmark for the Agent**
+
+```sh
+./run benchmark start my_agent
+```
+
+**Output**:
+
+```
+(more details about the testing process shown whilst the test are running)
+============= 13 failed, 1 passed in 0.97s ============...
+```
+
+Displays the results of the benchmark tests on 'my_agent'.

classic/Dockerfile.autogpt

@@ -2,7 +2,7 @@
 ARG BUILD_TYPE=dev
 
 # Use an official Python base image from the Docker Hub
-FROM python:3.12-slim AS autogpt-base
+FROM python:3.10-slim AS autogpt-base
 
 # Install browsers
 RUN apt-get update && apt-get install -y \
@@ -34,6 +34,9 @@ COPY original_autogpt/pyproject.toml original_autogpt/poetry.lock ./
 # Include forge so it can be used as a path dependency
 COPY forge/ ../forge
 
+# Include frontend
+COPY frontend/ ../frontend
+
 # Set the entrypoint
 ENTRYPOINT ["poetry", "run", "autogpt"]
 CMD []

classic/FORGE-QUICKSTART.md

@@ -0,0 +1,173 @@
+# Quickstart Guide
+
+> For the complete getting started [tutorial series](https://aiedge.medium.com/autogpt-forge-e3de53cc58ec) <- click here
+
+Welcome to the Quickstart Guide! This guide will walk you through setting up, building, and running your own AutoGPT agent. Whether you're a seasoned AI developer or just starting out, this guide will provide you with the steps to jumpstart your journey in AI development with AutoGPT.
+
+## System Requirements
+
+This project supports Linux (Debian-based), Mac, and Windows Subsystem for Linux (WSL). If you use a Windows system, you must install WSL. You can find the installation instructions for WSL [here](https://learn.microsoft.com/en-us/windows/wsl/).
+
+
+## Getting Setup
+1. **Fork the Repository**
+   To fork the repository, follow these steps:
+   - Navigate to the main page of the repository.
+
+   ![Repository](../docs/content/imgs/quickstart/001_repo.png)
+   - In the top-right corner of the page, click Fork.
+
+   ![Create Fork UI](../docs/content/imgs/quickstart/002_fork.png)
+   - On the next page, select your GitHub account to create the fork.
+   - Wait for the forking process to complete. You now have a copy of the repository in your GitHub account.
+
+2. **Clone the Repository**
+   To clone the repository, you need to have Git installed on your system. If you don't have Git installed, download it from [here](https://git-scm.com/downloads). Once you have Git installed, follow these steps:
+   - Open your terminal.
+   - Navigate to the directory where you want to clone the repository.
+   - Run the git clone command for the fork you just created
+
+   ![Clone the Repository](../docs/content/imgs/quickstart/003_clone.png)
+
+   - Then open your project in your ide
+
+   ![Open the Project in your IDE](../docs/content/imgs/quickstart/004_ide.png)
+
+4. **Setup the Project**
+    Next, we need to set up the required dependencies. We have a tool to help you perform all the tasks on the repo.
+    It can be accessed by running the `run` command by typing `./run` in the terminal.
+
+    The first command you need to use is `./run setup.` This will guide you through setting up your system.
+    Initially, you will get instructions for installing Flutter and Chrome and setting up your GitHub access token like the following image:
+    
+    ![Setup the Project](../docs/content/imgs/quickstart/005_setup.png)
+
+### For Windows Users
+
+If you're a Windows user and experience issues after installing WSL, follow the steps below to resolve them. 
+
+#### Update WSL 
+Run the following command in Powershell or Command Prompt:
+1. Enable the optional WSL and Virtual Machine Platform components.
+2. Download and install the latest Linux kernel.
+3. Set WSL 2 as the default.
+4. Download and install the Ubuntu Linux distribution (a reboot may be required).
+
+```shell
+wsl --install
+```
+
+For more detailed information and additional steps, refer to [Microsoft's WSL Setup Environment Documentation](https://learn.microsoft.com/en-us/windows/wsl/setup/environment).
+
+#### Resolve FileNotFoundError or "No such file or directory" Errors
+When you run `./run setup`, if you encounter errors like `No such file or directory` or `FileNotFoundError`, it might be because Windows-style line endings (CRLF - Carriage Return Line Feed) are not compatible with Unix/Linux style line endings (LF - Line Feed).
+
+To resolve this, you can use the `dos2unix` utility to convert the line endings in your script from CRLF to LF. Here’s how to install and run `dos2unix` on the script:
+
+```shell
+sudo apt update
+sudo apt install dos2unix
+dos2unix ./run
+```
+
+After executing the above commands, running `./run setup` should work successfully. 
+
+#### Store Project Files within the WSL File System
+If you continue to experience issues, consider storing your project files within the WSL file system instead of the Windows file system. This method avoids path translations and permissions issues and provides a more consistent development environment.
+
+You can keep running the command to get feedback on where you are up to with your setup. 
+When setup has been completed, the command will return an output like this:
+
+![Setup Complete](../docs/content/imgs/quickstart/006_setup_complete.png)
+
+## Creating Your Agent
+
+After completing the setup, the next step is to create your agent template.
+Execute the command `./run agent create YOUR_AGENT_NAME`, where `YOUR_AGENT_NAME` should be replaced with your chosen name.
+
+Tips for naming your agent:
+* Give it its own unique name, or name it after yourself
+* Include an important aspect of your agent in the name, such as its purpose
+
+Examples: `SwiftyosAssistant`, `PwutsPRAgent`, `MySuperAgent`
+
+![Create an Agent](../docs/content/imgs/quickstart/007_create_agent.png)
+
+## Running your Agent
+
+Your agent can be started using the command: `./run agent start YOUR_AGENT_NAME`
+
+This starts the agent on the URL: `http://localhost:8000/`
+
+![Start the Agent](../docs/content/imgs/quickstart/009_start_agent.png)
+
+The front end can be accessed from `http://localhost:8000/`; first, you must log in using either a Google account or your GitHub account.
+
+![Login](../docs/content/imgs/quickstart/010_login.png)
+
+Upon logging in, you will get a page that looks something like this: your task history down the left-hand side of the page, and the 'chat' window to send tasks to your agent.
+
+![Login](../docs/content/imgs/quickstart/011_home.png)
+
+When you have finished with your agent or just need to restart it, use Ctl-C to end the session. Then, you can re-run the start command.
+
+If you are having issues and want to ensure the agent has been stopped, there is a `./run agent stop` command, which will kill the process using port 8000, which should be the agent. 
+
+## Benchmarking your Agent
+
+The benchmarking system can also be accessed using the CLI too:
+
+```bash
+agpt % ./run benchmark
+Usage: cli.py benchmark [OPTIONS] COMMAND [ARGS]...
+
+  Commands to start the benchmark and list tests and categories
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  categories  Benchmark categories group command
+  start       Starts the benchmark command
+  tests       Benchmark tests group command
+agpt % ./run benchmark categories     
+Usage: cli.py benchmark categories [OPTIONS] COMMAND [ARGS]...
+
+  Benchmark categories group command
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  list  List benchmark categories command
+agpt % ./run benchmark tests      
+Usage: cli.py benchmark tests [OPTIONS] COMMAND [ARGS]...
+
+  Benchmark tests group command
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  details  Benchmark test details command
+  list     List benchmark tests command
+```
+
+The benchmark has been split into different categories of skills you can test your agent on. You can see what categories are available with
+```bash
+./run benchmark categories list
+# And what tests are available with
+./run benchmark tests list
+```
+
+![Login](../docs/content/imgs/quickstart/012_tests.png)
+
+
+Finally, you can run the benchmark with
+
+```bash
+./run benchmark start YOUR_AGENT_NAME
+
+```
+
+>

classic/README.md

@@ -4,7 +4,7 @@ AutoGPT Classic was an experimental project to demonstrate autonomous GPT-4 oper
 
 ## Project Status
 
-**This project is unsupported, and dependencies will not be updated.** It was an experiment that has concluded its initial research phase. If you want to use AutoGPT, you should use the [AutoGPT Platform](/autogpt_platform).
+⚠️ **This project is unsupported, and dependencies will not be updated. It was an experiment that has concluded its initial research phase. If you want to use AutoGPT, you should use the [AutoGPT Platform](/autogpt_platform)**
 
 For those interested in autonomous AI agents, we recommend exploring more actively maintained alternatives or referring to this codebase for educational purposes only.
 
@@ -16,171 +16,37 @@ AutoGPT Classic was one of the first implementations of autonomous AI agents - A
 - Learn from the results and adjust its approach
 - Chain multiple actions together to achieve an objective
 
+## Key Features
+
+- 🔄 Autonomous task chaining
+- 🛠 Tool and API integration capabilities
+- 💾 Memory management for context retention
+- 🔍 Web browsing and information gathering
+- 📝 File operations and content creation
+- 🔄 Self-prompting and task breakdown
+
 ## Structure
 
-```
-classic/
-├── pyproject.toml          # Single consolidated Poetry project
-├── poetry.lock             # Single lock file
-├── forge/                  # Core autonomous agent framework
-├── original_autogpt/       # Original implementation
-├── direct_benchmark/       # Benchmark harness
-└── benchmark/              # Challenge definitions (data)
-```
+The project is organized into several key components:
+- `/benchmark` - Performance testing tools
+- `/forge` - Core autonomous agent framework
+- `/frontend` - User interface components
+- `/original_autogpt` - Original implementation
 
 ## Getting Started
 
-### Prerequisites
-
-- Python 3.12+
-- [Poetry](https://python-poetry.org/docs/#installation)
-
-### Installation
+While this project is no longer actively maintained, you can still explore the codebase:
 
+1. Clone the repository:
 ```bash
-# Clone the repository
 git clone https://github.com/Significant-Gravitas/AutoGPT.git
 cd classic
-
-# Install everything
-poetry install
 ```
 
-### Configuration
-
-Configuration uses a layered system:
-
-1. **Environment variables** (`.env` file)
-2. **Workspace settings** (`.autogpt/autogpt.yaml`)
-3. **Agent settings** (`.autogpt/agents/{id}/permissions.yaml`)
-
-Copy the example environment file and add your API keys:
-
-```bash
-cp .env.example .env
-```
-
-Key environment variables:
-```bash
-# Required
-OPENAI_API_KEY=sk-...
-
-# Optional LLM settings
-SMART_LLM=gpt-4o                    # Model for complex reasoning
-FAST_LLM=gpt-4o-mini                # Model for simple tasks
-
-# Optional search providers
-TAVILY_API_KEY=tvly-...
-SERPER_API_KEY=...
-
-# Optional infrastructure
-LOG_LEVEL=DEBUG
-PORT=8000
-FILE_STORAGE_BACKEND=local          # local, s3, or gcs
-```
-
-### Running
-
-All commands run from the `classic/` directory:
-
-```bash
-# Run forge agent
-poetry run python -m forge
-
-# Run original autogpt server
-poetry run serve --debug
-
-# Run autogpt CLI
-poetry run autogpt
-```
-
-Agents run on `http://localhost:8000` by default.
-
-### Benchmarking
-
-```bash
-poetry run direct-benchmark run
-```
-
-### Testing
-
-```bash
-poetry run pytest                        # All tests
-poetry run pytest forge/tests/           # Forge tests only
-poetry run pytest original_autogpt/tests/ # AutoGPT tests only
-```
-
-## Workspaces
-
-Agents operate within a **workspace** directory that contains all agent data and files:
-
-```
-{workspace}/
-├── .autogpt/
-│   ├── autogpt.yaml              # Workspace-level permissions
-│   ├── ap_server.db              # Agent Protocol database (server mode)
-│   └── agents/
-│       └── AutoGPT-{agent_id}/
-│           ├── state.json        # Agent profile, directives, history
-│           ├── permissions.yaml  # Agent-specific permissions
-│           └── workspace/        # Agent's sandboxed working directory
-```
-
-- The workspace defaults to the current working directory
-- Multiple agents can coexist in the same workspace
-- Agent file access is sandboxed to their `workspace/` subdirectory
-- State persists across sessions via `state.json`
-
-## Permissions
-
-AutoGPT uses a **layered permission system** with pattern matching:
-
-### Permission Files
-
-| File | Scope | Location |
-|------|-------|----------|
-| `autogpt.yaml` | All agents in workspace | `.autogpt/autogpt.yaml` |
-| `permissions.yaml` | Single agent | `.autogpt/agents/{id}/permissions.yaml` |
-
-### Permission Format
-
-```yaml
-allow:
-  - read_file({workspace}/**)     # Read any file in workspace
-  - write_to_file({workspace}/**) # Write any file in workspace
-  - web_search(*)                 # All web searches
-
-deny:
-  - read_file(**.env)             # Block .env files
-  - execute_shell(sudo:*)         # Block sudo commands
-```
-
-### Check Order (First Match Wins)
-
-1. Agent deny → Block
-2. Workspace deny → Block
-3. Agent allow → Allow
-4. Workspace allow → Allow
-5. Prompt user → Interactive approval
-
-### Interactive Approval
-
-When prompted, users can approve commands with different scopes:
-- **Once** - Allow this one time only
-- **Agent** - Always allow for this agent
-- **Workspace** - Always allow for all agents
-- **Deny** - Block this command
-
-### Default Security
-
-Denied by default:
-- Sensitive files (`.env`, `.key`, `.pem`)
-- Destructive commands (`rm -rf`, `sudo`)
-- Operations outside the workspace
-
-## Security Notice
-
-This codebase has **known vulnerabilities** and issues with its dependencies. It will not be updated to new dependencies. Use for educational purposes only.
+2. Review the documentation:
+- For reference, see the [documentation](https://docs.agpt.co). You can browse at the same point in time as this commit so the docs don't change.
+- Check `CLI-USAGE.md` for command-line interface details
+- Refer to `TROUBLESHOOTING.md` for common issues
 
 ## License
 
@@ -189,3 +55,27 @@ This project segment is licensed under the MIT License - see the [LICENSE](LICEN
 ## Documentation
 
 Please refer to the [documentation](https://docs.agpt.co) for more detailed information about the project's architecture and concepts.
+You can browse at the same point in time as this commit so the docs don't change.
+
+## Historical Impact
+
+AutoGPT Classic played a significant role in advancing the field of autonomous AI agents:
+- Demonstrated practical implementation of AI autonomy
+- Inspired numerous derivative projects and research
+- Contributed to the development of AI agent architectures
+- Helped identify key challenges in AI autonomy
+
+## Security Notice
+
+If you're studying this codebase, please understand this has KNOWN vulnerabilities and issues with its dependencies. It will not be updated to new dependencies.
+
+## Community & Support
+
+While active development has concluded:
+- The codebase remains available for study and reference
+- Historical discussions can be found in project issues
+- Related research and developments continue in the broader AI agent community
+
+## Acknowledgments
+
+Thanks to all contributors who participated in this experimental project and helped advance the field of autonomous AI agents.

classic/benchmark/.flake8

@@ -0,0 +1,12 @@
+[flake8]
+max-line-length = 88
+# Ignore rules that conflict with Black code style
+extend-ignore = E203, W503
+exclude =
+    __pycache__/,
+    *.pyc,
+    .pytest_cache/,
+    venv*/,
+    .venv/,
+    reports/,
+    agbenchmark/reports/,

classic/benchmark/.gitignore

@@ -0,0 +1,174 @@
+agbenchmark_config/workspace/
+backend/backend_stdout.txt
+reports/df*.pkl
+reports/raw*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+.DS_Store
+```
+secrets.json
+agbenchmark_config/challenges_already_beaten.json
+agbenchmark_config/challenges/pri_*
+agbenchmark_config/updates.json
+agbenchmark_config/reports/*
+agbenchmark_config/reports/success_rate.json
+agbenchmark_config/reports/regression_tests.json

classic/benchmark/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AutoGPT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

classic/benchmark/README.md

@@ -0,0 +1,25 @@
+# Auto-GPT Benchmarks
+
+Built for the purpose of benchmarking the performance of agents regardless of how they work.
+
+Objectively know how well your agent is performing in categories like code, retrieval, memory, and safety.
+
+Save time and money while doing it through smart dependencies. The best part? It's all automated.
+
+## Scores:
+
+<img width="733" alt="Screenshot 2023-07-25 at 10 35 01 AM" src="https://github.com/Significant-Gravitas/Auto-GPT-Benchmarks/assets/9652976/98963e0b-18b9-4b17-9a6a-4d3e4418af70">
+
+## Ranking overall:
+
+- 1- [Beebot](https://github.com/AutoPackAI/beebot)
+- 2- [mini-agi](https://github.com/muellerberndt/mini-agi)
+- 3- [Auto-GPT](https://github.com/Significant-Gravitas/AutoGPT)
+
+## Detailed results:
+
+<img width="733" alt="Screenshot 2023-07-25 at 10 42 15 AM" src="https://github.com/Significant-Gravitas/Auto-GPT-Benchmarks/assets/9652976/39be464c-c842-4437-b28a-07d878542a83">
+
+[Click here to see the results and the raw data!](https://docs.google.com/spreadsheets/d/1WXm16P2AHNbKpkOI0LYBpcsGG0O7D8HYTG5Uj0PaJjA/edit#gid=203558751)!
+
+More agents coming soon !

classic/benchmark/agbenchmark/README.md

@@ -0,0 +1,69 @@
+## As a user
+
+1. `pip install auto-gpt-benchmarks`
+2. Add boilerplate code to run and kill agent
+3. `agbenchmark`
+   - `--category challenge_category` to run tests in a specific category
+   - `--mock` to only run mock tests if they exists for each test
+   - `--noreg` to skip any tests that have passed in the past. When you run without this flag and a previous challenge that passed fails, it will now not be regression tests
+4. We call boilerplate code for your agent
+5. Show pass rate of tests, logs, and any other metrics
+
+## Contributing
+
+##### Diagrams: https://whimsical.com/agbenchmark-5n4hXBq1ZGzBwRsK4TVY7x
+
+### To run the existing mocks
+
+1. clone the repo `auto-gpt-benchmarks`
+2. `pip install poetry`
+3. `poetry shell`
+4. `poetry install`
+5. `cp .env_example .env`
+6. `git submodule update --init --remote --recursive`
+7. `uvicorn server:app --reload`
+8. `agbenchmark --mock`
+   Keep config the same and watch the logs :)
+
+### To run with mini-agi
+
+1. Navigate to `auto-gpt-benchmarks/agent/mini-agi`
+2. `pip install -r requirements.txt`
+3. `cp .env_example .env`, set `PROMPT_USER=false` and add your `OPENAI_API_KEY=`. Sset `MODEL="gpt-3.5-turbo"` if you don't have access to `gpt-4` yet. Also make sure you have Python 3.10^ installed
+4. set `AGENT_NAME=mini-agi` in `.env` file and where you want your `REPORTS_FOLDER` to be
+5. Make sure to follow the commands above, and remove mock flag `agbenchmark`
+
+- To add requirements `poetry add requirement`.
+
+Feel free to create prs to merge with `main` at will (but also feel free to ask for review) - if you can't send msg in R&D chat for access.
+
+If you push at any point and break things - it'll happen to everyone - fix it asap. Step 1 is to revert `master` to last working commit
+
+Let people know what beautiful code you write does, document everything well
+
+Share your progress :)
+
+#### Dataset
+
+Manually created, existing challenges within Auto-Gpt, https://osu-nlp-group.github.io/Mind2Web/
+
+## How do I add new agents to agbenchmark ?
+
+Example with smol developer.
+
+1- Create a github branch with your agent following the same pattern as this example:
+
+https://github.com/smol-ai/developer/pull/114/files
+
+2- Create the submodule and the github workflow by following the same pattern as this example:
+
+https://github.com/Significant-Gravitas/Auto-GPT-Benchmarks/pull/48/files
+
+## How do I run agent in different environments?
+
+**To just use as the benchmark for your agent**. `pip install` the package and run `agbenchmark`
+
+**For internal Auto-GPT ci runs**, specify the `AGENT_NAME` you want you use and set the `HOME_ENV`.
+Ex. `AGENT_NAME=mini-agi`
+
+**To develop agent alongside benchmark**, you can specify the `AGENT_NAME` you want you use and add as a submodule to the repo

classic/benchmark/agbenchmark/__main__.py

@@ -0,0 +1,352 @@
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+import click
+from click_default_group import DefaultGroup
+from dotenv import load_dotenv
+
+from agbenchmark.config import AgentBenchmarkConfig
+from agbenchmark.utils.logging import configure_logging
+
+load_dotenv()
+
+# try:
+#     if os.getenv("HELICONE_API_KEY"):
+#         import helicone  # noqa
+
+#         helicone_enabled = True
+#     else:
+#         helicone_enabled = False
+# except ImportError:
+#     helicone_enabled = False
+
+
+class InvalidInvocationError(ValueError):
+    pass
+
+
+logger = logging.getLogger(__name__)
+
+BENCHMARK_START_TIME_DT = datetime.now(timezone.utc)
+BENCHMARK_START_TIME = BENCHMARK_START_TIME_DT.strftime("%Y-%m-%dT%H:%M:%S+00:00")
+
+
+# if helicone_enabled:
+#     from helicone.lock import HeliconeLockManager
+
+#     HeliconeLockManager.write_custom_property(
+#         "benchmark_start_time", BENCHMARK_START_TIME
+#     )
+
+
+@click.group(cls=DefaultGroup, default_if_no_args=True)
+@click.option("--debug", is_flag=True, help="Enable debug output")
+def cli(
+    debug: bool,
+) -> Any:
+    configure_logging(logging.DEBUG if debug else logging.INFO)
+
+
+@cli.command(hidden=True)
+def start():
+    raise DeprecationWarning(
+        "`agbenchmark start` is deprecated. Use `agbenchmark run` instead."
+    )
+
+
+@cli.command(default=True)
+@click.option(
+    "-N", "--attempts", default=1, help="Number of times to run each challenge."
+)
+@click.option(
+    "-c",
+    "--category",
+    multiple=True,
+    help="(+) Select a category to run.",
+)
+@click.option(
+    "-s",
+    "--skip-category",
+    multiple=True,
+    help="(+) Exclude a category from running.",
+)
+@click.option("--test", multiple=True, help="(+) Select a test to run.")
+@click.option("--maintain", is_flag=True, help="Run only regression tests.")
+@click.option("--improve", is_flag=True, help="Run only non-regression tests.")
+@click.option(
+    "--explore",
+    is_flag=True,
+    help="Run only challenges that have never been beaten.",
+)
+@click.option(
+    "--no-dep",
+    is_flag=True,
+    help="Run all (selected) challenges, regardless of dependency success/failure.",
+)
+@click.option("--cutoff", type=int, help="Override the challenge time limit (seconds).")
+@click.option("--nc", is_flag=True, help="Disable the challenge time limit.")
+@click.option("--mock", is_flag=True, help="Run with mock")
+@click.option("--keep-answers", is_flag=True, help="Keep answers")
+@click.option(
+    "--backend",
+    is_flag=True,
+    help="Write log output to a file instead of the terminal.",
+)
+# @click.argument(
+#     "agent_path",
+#     type=click.Path(exists=True, file_okay=False, path_type=Path),
+#     required=False,
+# )
+def run(
+    maintain: bool,
+    improve: bool,
+    explore: bool,
+    mock: bool,
+    no_dep: bool,
+    nc: bool,
+    keep_answers: bool,
+    test: tuple[str],
+    category: tuple[str],
+    skip_category: tuple[str],
+    attempts: int,
+    cutoff: Optional[int] = None,
+    backend: Optional[bool] = False,
+    # agent_path: Optional[Path] = None,
+) -> None:
+    """
+    Run the benchmark on the agent in the current directory.
+
+    Options marked with (+) can be specified multiple times, to select multiple items.
+    """
+    from agbenchmark.main import run_benchmark, validate_args
+
+    agbenchmark_config = AgentBenchmarkConfig.load()
+    logger.debug(f"agbenchmark_config: {agbenchmark_config.agbenchmark_config_dir}")
+    try:
+        validate_args(
+            maintain=maintain,
+            improve=improve,
+            explore=explore,
+            tests=test,
+            categories=category,
+            skip_categories=skip_category,
+            no_cutoff=nc,
+            cutoff=cutoff,
+        )
+    except InvalidInvocationError as e:
+        logger.error("Error: " + "\n".join(e.args))
+        sys.exit(1)
+
+    original_stdout = sys.stdout  # Save the original standard output
+    exit_code = None
+
+    if backend:
+        with open("backend/backend_stdout.txt", "w") as f:
+            sys.stdout = f
+            exit_code = run_benchmark(
+                config=agbenchmark_config,
+                maintain=maintain,
+                improve=improve,
+                explore=explore,
+                mock=mock,
+                no_dep=no_dep,
+                no_cutoff=nc,
+                keep_answers=keep_answers,
+                tests=test,
+                categories=category,
+                skip_categories=skip_category,
+                attempts_per_challenge=attempts,
+                cutoff=cutoff,
+            )
+
+        sys.stdout = original_stdout
+
+    else:
+        exit_code = run_benchmark(
+            config=agbenchmark_config,
+            maintain=maintain,
+            improve=improve,
+            explore=explore,
+            mock=mock,
+            no_dep=no_dep,
+            no_cutoff=nc,
+            keep_answers=keep_answers,
+            tests=test,
+            categories=category,
+            skip_categories=skip_category,
+            attempts_per_challenge=attempts,
+            cutoff=cutoff,
+        )
+
+        sys.exit(exit_code)
+
+
+@cli.command()
+@click.option("--port", type=int, help="Port to run the API on.")
+def serve(port: Optional[int] = None):
+    """Serve the benchmark frontend and API on port 8080."""
+    import uvicorn
+
+    from agbenchmark.app import setup_fastapi_app
+
+    config = AgentBenchmarkConfig.load()
+    app = setup_fastapi_app(config)
+
+    # Run the FastAPI application using uvicorn
+    port = port or int(os.getenv("PORT", 8080))
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+@cli.command()
+def config():
+    """Displays info regarding the present AGBenchmark config."""
+    from .utils.utils import pretty_print_model
+
+    try:
+        config = AgentBenchmarkConfig.load()
+    except FileNotFoundError as e:
+        click.echo(e, err=True)
+        return 1
+
+    pretty_print_model(config, include_header=False)
+
+
+@cli.group()
+def challenge():
+    logging.getLogger().setLevel(logging.WARNING)
+
+
+@challenge.command("list")
+@click.option(
+    "--all", "include_unavailable", is_flag=True, help="Include unavailable challenges."
+)
+@click.option(
+    "--names", "only_names", is_flag=True, help="List only the challenge names."
+)
+@click.option("--json", "output_json", is_flag=True)
+def list_challenges(include_unavailable: bool, only_names: bool, output_json: bool):
+    """Lists [available|all] challenges."""
+    import json
+
+    from tabulate import tabulate
+
+    from .challenges.builtin import load_builtin_challenges
+    from .challenges.webarena import load_webarena_challenges
+    from .utils.data_types import Category, DifficultyLevel
+    from .utils.utils import sorted_by_enum_index
+
+    DIFFICULTY_COLORS = {
+        difficulty: color
+        for difficulty, color in zip(
+            DifficultyLevel,
+            ["black", "blue", "cyan", "green", "yellow", "red", "magenta", "white"],
+        )
+    }
+    CATEGORY_COLORS = {
+        category: f"bright_{color}"
+        for category, color in zip(
+            Category,
+            ["blue", "cyan", "green", "yellow", "magenta", "red", "white", "black"],
+        )
+    }
+
+    # Load challenges
+    challenges = filter(
+        lambda c: c.info.available or include_unavailable,
+        [
+            *load_builtin_challenges(),
+            *load_webarena_challenges(skip_unavailable=False),
+        ],
+    )
+    challenges = sorted_by_enum_index(
+        challenges, DifficultyLevel, key=lambda c: c.info.difficulty
+    )
+
+    if only_names:
+        if output_json:
+            click.echo(json.dumps([c.info.name for c in challenges]))
+            return
+
+        for c in challenges:
+            click.echo(
+                click.style(c.info.name, fg=None if c.info.available else "black")
+            )
+        return
+
+    if output_json:
+        click.echo(
+            json.dumps([json.loads(c.info.model_dump_json()) for c in challenges])
+        )
+        return
+
+    headers = tuple(
+        click.style(h, bold=True) for h in ("Name", "Difficulty", "Categories")
+    )
+    table = [
+        tuple(
+            v if challenge.info.available else click.style(v, fg="black")
+            for v in (
+                challenge.info.name,
+                (
+                    click.style(
+                        challenge.info.difficulty.value,
+                        fg=DIFFICULTY_COLORS[challenge.info.difficulty],
+                    )
+                    if challenge.info.difficulty
+                    else click.style("-", fg="black")
+                ),
+                " ".join(
+                    click.style(cat.value, fg=CATEGORY_COLORS[cat])
+                    for cat in sorted_by_enum_index(challenge.info.category, Category)
+                ),
+            )
+        )
+        for challenge in challenges
+    ]
+    click.echo(tabulate(table, headers=headers))
+
+
+@challenge.command()
+@click.option("--json", is_flag=True)
+@click.argument("name")
+def info(name: str, json: bool):
+    from itertools import chain
+
+    from .challenges.builtin import load_builtin_challenges
+    from .challenges.webarena import load_webarena_challenges
+    from .utils.utils import pretty_print_model
+
+    for challenge in chain(
+        load_builtin_challenges(),
+        load_webarena_challenges(skip_unavailable=False),
+    ):
+        if challenge.info.name != name:
+            continue
+
+        if json:
+            click.echo(challenge.info.model_dump_json())
+            break
+
+        pretty_print_model(challenge.info)
+        break
+    else:
+        click.echo(click.style(f"Unknown challenge '{name}'", fg="red"), err=True)
+
+
+@cli.command()
+def version():
+    """Print version info for the AGBenchmark application."""
+    import toml
+
+    package_root = Path(__file__).resolve().parent.parent
+    pyproject = toml.load(package_root / "pyproject.toml")
+    version = pyproject["tool"]["poetry"]["version"]
+    click.echo(f"AGBenchmark version {version}")
+
+
+if __name__ == "__main__":
+    cli()

classic/benchmark/agbenchmark/agent_api_interface.py

@@ -0,0 +1,111 @@
+import logging
+import time
+from pathlib import Path
+from typing import AsyncIterator, Optional
+
+from agent_protocol_client import (
+    AgentApi,
+    ApiClient,
+    Configuration,
+    Step,
+    TaskRequestBody,
+)
+
+from agbenchmark.agent_interface import get_list_of_file_paths
+from agbenchmark.config import AgentBenchmarkConfig
+
+logger = logging.getLogger(__name__)
+
+
+async def run_api_agent(
+    task: str,
+    config: AgentBenchmarkConfig,
+    timeout: int,
+    artifacts_location: Optional[Path] = None,
+    *,
+    mock: bool = False,
+) -> AsyncIterator[Step]:
+    configuration = Configuration(host=config.host)
+    async with ApiClient(configuration) as api_client:
+        api_instance = AgentApi(api_client)
+        task_request_body = TaskRequestBody(input=task, additional_input=None)
+
+        start_time = time.time()
+        response = await api_instance.create_agent_task(
+            task_request_body=task_request_body
+        )
+        task_id = response.task_id
+
+        if artifacts_location:
+            logger.debug("Uploading task input artifacts to agent...")
+            await upload_artifacts(
+                api_instance, artifacts_location, task_id, "artifacts_in"
+            )
+
+        logger.debug("Running agent until finished or timeout...")
+        while True:
+            step = await api_instance.execute_agent_task_step(task_id=task_id)
+            yield step
+
+            if time.time() - start_time > timeout:
+                raise TimeoutError("Time limit exceeded")
+            if step and mock:
+                step.is_last = True
+            if not step or step.is_last:
+                break
+
+        if artifacts_location:
+            # In "mock" mode, we cheat by giving the correct artifacts to pass the test
+            if mock:
+                logger.debug("Uploading mock artifacts to agent...")
+                await upload_artifacts(
+                    api_instance, artifacts_location, task_id, "artifacts_out"
+                )
+
+            logger.debug("Downloading agent artifacts...")
+            await download_agent_artifacts_into_folder(
+                api_instance, task_id, config.temp_folder
+            )
+
+
+async def download_agent_artifacts_into_folder(
+    api_instance: AgentApi, task_id: str, folder: Path
+):
+    artifacts = await api_instance.list_agent_task_artifacts(task_id=task_id)
+
+    for artifact in artifacts.artifacts:
+        # current absolute path of the directory of the file
+        if artifact.relative_path:
+            path: str = (
+                artifact.relative_path
+                if not artifact.relative_path.startswith("/")
+                else artifact.relative_path[1:]
+            )
+            folder = (folder / path).parent
+
+        if not folder.exists():
+            folder.mkdir(parents=True)
+
+        file_path = folder / artifact.file_name
+        logger.debug(f"Downloading agent artifact {artifact.file_name} to {folder}")
+        with open(file_path, "wb") as f:
+            content = await api_instance.download_agent_task_artifact(
+                task_id=task_id, artifact_id=artifact.artifact_id
+            )
+
+            f.write(content)
+
+
+async def upload_artifacts(
+    api_instance: AgentApi, artifacts_location: Path, task_id: str, type: str
+) -> None:
+    for file_path in get_list_of_file_paths(artifacts_location, type):
+        relative_path: Optional[str] = "/".join(
+            str(file_path).split(f"{type}/", 1)[-1].split("/")[:-1]
+        )
+        if not relative_path:
+            relative_path = None
+
+        await api_instance.upload_agent_task_artifacts(
+            task_id=task_id, file=str(file_path), relative_path=relative_path
+        )

classic/benchmark/agbenchmark/agent_interface.py

@@ -0,0 +1,27 @@
+import os
+import shutil
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+HELICONE_GRAPHQL_LOGS = os.getenv("HELICONE_GRAPHQL_LOGS", "").lower() == "true"
+
+
+def get_list_of_file_paths(
+    challenge_dir_path: str | Path, artifact_folder_name: str
+) -> list[Path]:
+    source_dir = Path(challenge_dir_path) / artifact_folder_name
+    if not source_dir.exists():
+        return []
+    return list(source_dir.iterdir())
+
+
+def copy_challenge_artifacts_into_workspace(
+    challenge_dir_path: str | Path, artifact_folder_name: str, workspace: str | Path
+) -> None:
+    file_paths = get_list_of_file_paths(challenge_dir_path, artifact_folder_name)
+    for file_path in file_paths:
+        if file_path.is_file():
+            shutil.copy(file_path, workspace)

classic/benchmark/agbenchmark/app.py

@@ -0,0 +1,339 @@
+import datetime
+import glob
+import json
+import logging
+import sys
+import time
+import uuid
+from collections import deque
+from multiprocessing import Process
+from pathlib import Path
+from typing import Optional
+
+import httpx
+import psutil
+from agent_protocol_client import AgentApi, ApiClient, ApiException, Configuration
+from agent_protocol_client.models import Task, TaskRequestBody
+from fastapi import APIRouter, FastAPI, HTTPException, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from agbenchmark.challenges import ChallengeInfo
+from agbenchmark.config import AgentBenchmarkConfig
+from agbenchmark.reports.processing.report_types_v2 import (
+    BenchmarkRun,
+    Metrics,
+    RepositoryInfo,
+    RunDetails,
+    TaskInfo,
+)
+from agbenchmark.schema import TaskEvalRequestBody
+from agbenchmark.utils.utils import write_pretty_json
+
+sys.path.append(str(Path(__file__).parent.parent))
+
+logger = logging.getLogger(__name__)
+
+CHALLENGES: dict[str, ChallengeInfo] = {}
+challenges_path = Path(__file__).parent / "challenges"
+challenge_spec_files = deque(
+    glob.glob(
+        f"{challenges_path}/**/data.json",
+        recursive=True,
+    )
+)
+
+logger.debug("Loading challenges...")
+while challenge_spec_files:
+    challenge_spec_file = Path(challenge_spec_files.popleft())
+    challenge_relpath = challenge_spec_file.relative_to(challenges_path.parent)
+    if challenge_relpath.is_relative_to("challenges/deprecated"):
+        continue
+
+    logger.debug(f"Loading {challenge_relpath}...")
+    try:
+        challenge_info = ChallengeInfo.model_validate_json(
+            challenge_spec_file.read_text()
+        )
+    except ValidationError as e:
+        if logging.getLogger().level == logging.DEBUG:
+            logger.warning(f"Spec file {challenge_relpath} failed to load:\n{e}")
+        logger.debug(f"Invalid challenge spec: {challenge_spec_file.read_text()}")
+        continue
+
+    if not challenge_info.eval_id:
+        challenge_info.eval_id = str(uuid.uuid4())
+        # this will sort all the keys of the JSON systematically
+        # so that the order is always the same
+        write_pretty_json(challenge_info.model_dump(), challenge_spec_file)
+
+    CHALLENGES[challenge_info.eval_id] = challenge_info
+
+
+class BenchmarkTaskInfo(BaseModel):
+    task_id: str
+    start_time: datetime.datetime
+    challenge_info: ChallengeInfo
+
+
+task_informations: dict[str, BenchmarkTaskInfo] = {}
+
+
+def find_agbenchmark_without_uvicorn():
+    pids = []
+    for process in psutil.process_iter(
+        attrs=[
+            "pid",
+            "cmdline",
+            "name",
+            "username",
+            "status",
+            "cpu_percent",
+            "memory_info",
+            "create_time",
+            "cwd",
+            "connections",
+        ]
+    ):
+        try:
+            # Convert the process.info dictionary values to strings and concatenate them
+            full_info = " ".join([str(v) for k, v in process.as_dict().items()])
+
+            if "agbenchmark" in full_info and "uvicorn" not in full_info:
+                pids.append(process.pid)
+        except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+            pass
+    return pids
+
+
+class CreateReportRequest(BaseModel):
+    test: str
+    test_run_id: str
+    # category: Optional[str] = []
+    mock: Optional[bool] = False
+
+    model_config = ConfigDict(extra="forbid")
+
+
+updates_list = []
+
+origins = [
+    "http://localhost:8000",
+    "http://localhost:8080",
+    "http://127.0.0.1:5000",
+    "http://localhost:5000",
+]
+
+
+def stream_output(pipe):
+    for line in pipe:
+        print(line, end="")
+
+
+def setup_fastapi_app(agbenchmark_config: AgentBenchmarkConfig) -> FastAPI:
+    from agbenchmark.agent_api_interface import upload_artifacts
+    from agbenchmark.challenges import get_challenge_from_source_uri
+    from agbenchmark.main import run_benchmark
+
+    configuration = Configuration(
+        host=agbenchmark_config.host or "http://localhost:8000"
+    )
+    app = FastAPI()
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    router = APIRouter()
+
+    @router.post("/reports")
+    def run_single_test(body: CreateReportRequest) -> dict:
+        pids = find_agbenchmark_without_uvicorn()
+        logger.info(f"pids already running with agbenchmark: {pids}")
+
+        logger.debug(f"Request to /reports: {body.model_dump()}")
+
+        # Start the benchmark in a separate thread
+        benchmark_process = Process(
+            target=lambda: run_benchmark(
+                config=agbenchmark_config,
+                tests=(body.test,),
+                mock=body.mock or False,
+            )
+        )
+        benchmark_process.start()
+
+        # Wait for the benchmark to finish, with a timeout of 200 seconds
+        timeout = 200
+        start_time = time.time()
+        while benchmark_process.is_alive():
+            if time.time() - start_time > timeout:
+                logger.warning(f"Benchmark run timed out after {timeout} seconds")
+                benchmark_process.terminate()
+                break
+            time.sleep(1)
+        else:
+            logger.debug(f"Benchmark finished running in {time.time() - start_time} s")
+
+        # List all folders in the current working directory
+        reports_folder = agbenchmark_config.reports_folder
+        folders = [folder for folder in reports_folder.iterdir() if folder.is_dir()]
+
+        # Sort the folders based on their names
+        sorted_folders = sorted(folders, key=lambda x: x.name)
+
+        # Get the last folder
+        latest_folder = sorted_folders[-1] if sorted_folders else None
+
+        # Read report.json from this folder
+        if latest_folder:
+            report_path = latest_folder / "report.json"
+            logger.debug(f"Getting latest report from {report_path}")
+            if report_path.exists():
+                with report_path.open() as file:
+                    data = json.load(file)
+                logger.debug(f"Report data: {data}")
+            else:
+                raise HTTPException(
+                    502,
+                    "Could not get result after running benchmark: "
+                    f"'report.json' does not exist in '{latest_folder}'",
+                )
+        else:
+            raise HTTPException(
+                504, "Could not get result after running benchmark: no reports found"
+            )
+
+        return data
+
+    @router.post("/agent/tasks", tags=["agent"])
+    async def create_agent_task(task_eval_request: TaskEvalRequestBody) -> Task:
+        """
+        Creates a new task using the provided TaskEvalRequestBody and returns a Task.
+
+        Args:
+            task_eval_request: `TaskRequestBody` including an eval_id.
+
+        Returns:
+            Task: A new task with task_id, input, additional_input,
+                and empty lists for artifacts and steps.
+
+        Example:
+            Request (TaskEvalRequestBody defined in schema.py):
+                {
+                    ...,
+                    "eval_id": "50da533e-3904-4401-8a07-c49adf88b5eb"
+                }
+
+            Response (Task defined in `agent_protocol_client.models`):
+                {
+                    "task_id": "50da533e-3904-4401-8a07-c49adf88b5eb",
+                    "input": "Write the word 'Washington' to a .txt file",
+                    "artifacts": []
+                }
+        """
+        try:
+            challenge_info = CHALLENGES[task_eval_request.eval_id]
+            async with ApiClient(configuration) as api_client:
+                api_instance = AgentApi(api_client)
+                task_input = challenge_info.task
+
+                task_request_body = TaskRequestBody(
+                    input=task_input, additional_input=None
+                )
+                task_response = await api_instance.create_agent_task(
+                    task_request_body=task_request_body
+                )
+                task_info = BenchmarkTaskInfo(
+                    task_id=task_response.task_id,
+                    start_time=datetime.datetime.now(datetime.timezone.utc),
+                    challenge_info=challenge_info,
+                )
+                task_informations[task_info.task_id] = task_info
+
+                if input_artifacts_dir := challenge_info.task_artifacts_dir:
+                    await upload_artifacts(
+                        api_instance,
+                        input_artifacts_dir,
+                        task_response.task_id,
+                        "artifacts_in",
+                    )
+                return task_response
+        except ApiException as e:
+            logger.error(f"Error whilst trying to create a task:\n{e}")
+            logger.error(
+                "The above error was caused while processing request: "
+                f"{task_eval_request}"
+            )
+            raise HTTPException(500)
+
+    @router.post("/agent/tasks/{task_id}/steps")
+    async def proxy(request: Request, task_id: str):
+        timeout = httpx.Timeout(300.0, read=300.0)  # 5 minutes
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            # Construct the new URL
+            new_url = f"{configuration.host}/ap/v1/agent/tasks/{task_id}/steps"
+
+            # Forward the request
+            response = await client.post(
+                new_url,
+                content=await request.body(),
+                headers=dict(request.headers),
+            )
+
+            # Return the response from the forwarded request
+            return Response(content=response.content, status_code=response.status_code)
+
+    @router.post("/agent/tasks/{task_id}/evaluations")
+    async def create_evaluation(task_id: str) -> BenchmarkRun:
+        task_info = task_informations[task_id]
+        challenge = get_challenge_from_source_uri(task_info.challenge_info.source_uri)
+        try:
+            async with ApiClient(configuration) as api_client:
+                api_instance = AgentApi(api_client)
+                eval_results = await challenge.evaluate_task_state(
+                    api_instance, task_id
+                )
+
+            eval_info = BenchmarkRun(
+                repository_info=RepositoryInfo(),
+                run_details=RunDetails(
+                    command=f"agbenchmark --test={challenge.info.name}",
+                    benchmark_start_time=(
+                        task_info.start_time.strftime("%Y-%m-%dT%H:%M:%S+00:00")
+                    ),
+                    test_name=challenge.info.name,
+                ),
+                task_info=TaskInfo(
+                    data_path=challenge.info.source_uri,
+                    is_regression=None,
+                    category=[c.value for c in challenge.info.category],
+                    task=challenge.info.task,
+                    answer=challenge.info.reference_answer or "",
+                    description=challenge.info.description or "",
+                ),
+                metrics=Metrics(
+                    success=all(e.passed for e in eval_results),
+                    success_percentage=(
+                        100 * sum(e.score for e in eval_results) / len(eval_results)
+                        if eval_results  # avoid division by 0
+                        else 0
+                    ),
+                    attempted=True,
+                ),
+                config={},
+            )
+
+            logger.debug(
+                f"Returning evaluation data:\n{eval_info.model_dump_json(indent=4)}"
+            )
+            return eval_info
+        except ApiException as e:
+            logger.error(f"Error {e} whilst trying to evaluate task: {task_id}")
+            raise HTTPException(500)
+
+    app.include_router(router, prefix="/ap/v1")
+
+    return app

classic/benchmark/agbenchmark/challenges/base.py

@@ -1,98 +1,19 @@
 import logging
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Any, AsyncIterator, Awaitable, ClassVar, Optional
+from typing import AsyncIterator, Awaitable, ClassVar, Optional
 
 import pytest
-from agbenchmark.config import AgentBenchmarkConfig
-from agbenchmark.utils.data_types import Category, DifficultyLevel, EvalResult
 from agent_protocol_client import AgentApi, Step
 from colorama import Fore, Style
 from pydantic import BaseModel, Field
 
+from agbenchmark.config import AgentBenchmarkConfig
+from agbenchmark.utils.data_types import Category, DifficultyLevel, EvalResult
+
 logger = logging.getLogger(__name__)
 
 
-def format_step_output(step: Step, step_num: int, challenge_name: str) -> str:
-    """Format a step for concise, informative console output.
-
-    Format: [Challenge] step N: tool_name(args) → result [$cost]
-    """
-    parts = [f"[{challenge_name}]", f"step {step_num}:"]
-
-    # Get additional_output data
-    ao: dict[str, Any] = step.additional_output or {}
-
-    # Get the tool being used in this step
-    use_tool = ao.get("use_tool", {})
-    tool_name = use_tool.get("name", "")
-    tool_args = use_tool.get("arguments", {})
-
-    if tool_name:
-        # Format tool call with abbreviated arguments
-        args_str = _format_tool_args(tool_name, tool_args)
-        parts.append(f"{Fore.CYAN}{tool_name}{Fore.RESET}({args_str})")
-    else:
-        parts.append(f"{Fore.YELLOW}(no tool){Fore.RESET}")
-
-    # Get result from last action (this step's tool will be executed next iteration)
-    last_action = ao.get("last_action", {})
-    if last_action:
-        result = last_action.get("result", {})
-        if isinstance(result, dict):
-            if result.get("error"):
-                parts.append(f"→ {Fore.RED}error{Fore.RESET}")
-            elif result.get("status") == "success":
-                parts.append(f"→ {Fore.GREEN}✓{Fore.RESET}")
-
-    # Add cost if available
-    cost = ao.get("task_cumulative_cost", 0)
-    if cost > 0:
-        parts.append(f"{Fore.BLUE}${cost:.3f}{Fore.RESET}")
-
-    return " ".join(parts)
-
-
-def _format_tool_args(tool_name: str, args: dict) -> str:
-    """Format tool arguments for display, keeping it concise."""
-    if not args:
-        return ""
-
-    # For common tools, show the most relevant argument
-    key_args = {
-        "read_file": ["filename"],
-        "write_file": ["filename"],
-        "open_file": ["filename", "file_path"],
-        "execute_python": ["filename"],
-        "execute_shell": ["command_line"],
-        "web_search": ["query"],
-        "read_webpage": ["url"],
-        "finish": ["reason"],
-        "ask_user": ["question"],
-        "todo_write": [],  # Skip args for todo_write (too verbose)
-    }
-
-    if tool_name in key_args:
-        keys = key_args[tool_name]
-        if not keys:
-            return "..."
-        values = [str(args.get(k, ""))[:40] for k in keys if k in args]
-        if values:
-            return ", ".join(
-                f'"{v}"' if " " not in v else f'"{v[:20]}..."' for v in values
-            )
-
-    # Default: show first arg value, abbreviated
-    if args:
-        first_key = next(iter(args))
-        first_val = str(args[first_key])[:30]
-        return f'{first_key}="{first_val}"' + (
-            "..." if len(str(args[first_key])) > 30 else ""
-        )
-
-    return ""
-
-
 class ChallengeInfo(BaseModel):
     eval_id: str = ""
     name: str
@@ -174,7 +95,7 @@ class BaseChallenge(ABC):
             cls.info.task, config, timeout, cls.info.task_artifacts_dir, mock=mock
         ):
             i += 1
-            print(format_step_output(step, i, cls.info.name))
+            print(f"[{cls.info.name}] - step {step.name} ({i}. request)")
             yield step
         logger.debug(f"Finished {cls.info.name} challenge run")
 
@@ -182,4 +103,5 @@ class BaseChallenge(ABC):
     @abstractmethod
     async def evaluate_task_state(
         cls, agent: AgentApi, task_id: str
-    ) -> list[EvalResult]: ...
+    ) -> list[EvalResult]:
+        ...

classic/benchmark/agbenchmark/challenges/builtin.py

@@ -10,16 +10,6 @@ from pathlib import Path
 from typing import Annotated, Any, ClassVar, Iterator, Literal, Optional
 
 import pytest
-from agbenchmark.agent_api_interface import download_agent_artifacts_into_folder
-from agbenchmark.agent_interface import copy_challenge_artifacts_into_workspace
-from agbenchmark.config import AgentBenchmarkConfig
-from agbenchmark.utils.data_types import Category, DifficultyLevel, EvalResult
-from agbenchmark.utils.prompts import (
-    END_PROMPT,
-    FEW_SHOT_EXAMPLES,
-    PROMPT_MAP,
-    SCORING_MAP,
-)
 from agent_protocol_client import AgentApi, ApiClient
 from agent_protocol_client import Configuration as ClientConfig
 from agent_protocol_client import Step
@@ -33,6 +23,17 @@ from pydantic import (
     field_validator,
 )
 
+from agbenchmark.agent_api_interface import download_agent_artifacts_into_folder
+from agbenchmark.agent_interface import copy_challenge_artifacts_into_workspace
+from agbenchmark.config import AgentBenchmarkConfig
+from agbenchmark.utils.data_types import Category, DifficultyLevel, EvalResult
+from agbenchmark.utils.prompts import (
+    END_PROMPT,
+    FEW_SHOT_EXAMPLES,
+    PROMPT_MAP,
+    SCORING_MAP,
+)
+
 from .base import BaseChallenge, ChallengeInfo
 
 logger = logging.getLogger(__name__)
@@ -68,9 +69,9 @@ class BuiltinChallengeSpec(BaseModel):
         class Eval(BaseModel):
             type: str
             scoring: Optional[Literal["percentage", "scale", "binary"]] = None
-            template: Optional[Literal["rubric", "reference", "question", "custom"]] = (
-                None
-            )
+            template: Optional[
+                Literal["rubric", "reference", "question", "custom"]
+            ] = None
             examples: Optional[str] = None
 
             @field_validator("scoring", "template")
@@ -227,11 +228,9 @@ class BuiltinChallenge(BaseChallenge):
         request.node.user_properties.append(
             (
                 "answers",
-                (
-                    [r.result for r in eval_results]
-                    if request.config.getoption("--keep-answers")
-                    else None
-                ),
+                [r.result for r in eval_results]
+                if request.config.getoption("--keep-answers")
+                else None,
             )
         )
         request.node.user_properties.append(("scores", [r.score for r in eval_results]))