---
name: agent-platform-tuning
metadata:
  version: "1.0.2"
  category: AiAndMachineLearning
description: >-
  Agent Platform Model Tuning. Use when you need to fine-tune open models
  or Gemini models using Agent Platform infrastructure. Don't use for model
  training outside Agent Platform, model deployment to endpoints (use
  `agent-platform-deploy`), or managing serving endpoints (use
  `agent-platform-endpoint-management`).
---

# Agent Platform Model Tuning

## Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST
read [Usage Attribution](references/attribution.md). For commands executed
directly in the terminal (never in generated scripts, Terraform, or user code),
prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the
attribution suffix to `User-Agent` headers:

```text
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-tuning)"
User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-tuning)
```

## Overview

This skill provides procedural knowledge for fine-tuning Large Language Models
(both Open Models and Gemini Models) using Agent Platform's tuning service. It
covers the entire lifecycle from environment setup and data preparation to job
configuration, monitoring, and deployment.

## Workflow Decision Tree

1.  **Project & Region Verification Check**: Has the user provided the Google
    Cloud project and region?

    -   **No** → **STOP tool execution immediately**. Do NOT run verification
        commands (`gcloud services list`, `gcloud projects get-iam-policy`), do
        NOT create resources, and do NOT begin dataset preparation. Prompt the
        user to specify or confirm the project and region (e.g. "Could you
        please specify which Google Cloud project and region you would like to
        use?").
        -   If the user's inquiry is solely to check or verify environment
            readiness (APIs, IAM, service agents), ask ONLY for the project and
            region. Do NOT ask for the model category.
        -   If the user is requesting a tuning workflow and also omitted whether
            they want to tune an Open Model or a Gemini Model, you may ask both
            questions together.
    -   **Yes** → Proceed.

2.  **Model Category Identification**: Has the user explicitly stated whether
    they want to tune an **Open Model** or a **Gemini Model**?

    -   **No** →
        -   **EXCEPTION for Environment Verification Inquiries:** If the user is
            only asking to check or verify that the environment, APIs, IAM
            permissions, or service agents are ready for tuning, do NOT ask for
            the model category. Verify the environment once the project and
            region are known and confirm readiness.
        -   Otherwise, **STOP tool execution**. Ask the user if they want to
            tune an Open Model or a Gemini Model. **General Setup and
            Prerequisite Inquiries (e.g., "What environment setup is
            needed?"):** If the user asks what environment setup, prerequisites,
            APIs, or permissions are needed to start fine-tuning, and has not
            yet chosen a model category:
        *   Describe the setup requirements (APIs, IAM permissions/service
            agents, and Python SDKs).
        *   Regarding Cloud Storage: state that an existing Cloud Storage bucket
            is needed for datasets and artifacts (e.g.,
            `gs://<existing-bucket>`). **CRITICAL:** Do NOT instruct the user to
            create a bucket, do NOT output a `gcloud storage buckets create`
            command in setup instructions, and do NOT assume a non-existent
            bucket exists (users may not have bucket creation permissions and
            will provide their own existing bucket).
        *   You MUST explicitly conclude your prose response with the direct
            question: **"Would you like to tune an Open Model or a Gemini
            Model?"** (do NOT bury this choice inside a bulleted "Suggested Next
            Steps" list). Never provide setup instructions without explicitly
            asking this question in prose. (Note: if they ask to actively check
            or verify a project whose ID or region is missing, ask for the
            project and region first without running tool calls).
    -   If the user provides a specific tuning purpose, you should recommend
        three models: one Open Model, one Gemini Model, and a third generally
        recommended choice. Briefly list the pros and cons of each (e.g., Gemini
        models might be more expensive, etc.). **CRITICAL:** You must read
        `references/models.md` during this step and only recommend models
        explicitly listed in that catalog. Never recommend uncataloged or
        unsupported models like `google/gemma-2-9b-it`, `gemma-2`, or `Mistral`
        — only recommend supported models such as Gemma 3
        (`google/gemma3@gemma-3-12b-it`), Qwen 3 (`qwen/qwen3@qwen3-8b`), or
        Llama 3.1 (`meta/llama3_1@llama-3.1-8b`). For Gemini models, ONLY
        recommend `gemini-2.5-flash` (recommended for general/coding/chat) or
        `gemini-2.5-pro`. Never recommend `gemini-1.5-flash-002`,
        `gemini-1.5-pro-002`, or `gemini-1.5-flash`, which are deprecated and
        unsupported by the tuning service. If the user names a model that is not
        in the catalog, follow the fallback rule in that catalog. Do not proceed
        with model configuration until the category is confirmed.
    -   **Distillation requests**: If the user asks to distill a model, names a
        teacher model, or wants a smaller model to learn from a larger one, this
        is an Open Model workflow using distillation. Read "Distillation" in
        `references/models.md` and use only the teacher and student models
        listed there.
    -   **Yes** → Proceed.

3.  **Environment Check**: Has the environment (Auth, APIs, IAM, Venv) been
    initialized?

    -   **No** → Go to [Phase 0: Environment & IAM Setup](#phase-0).
    -   **Yes** → Proceed.

4.  **Dataset Status**: Is the dataset ready in JSONL format, **is its structure
    valid for tuning**, and is it uploaded to Google Cloud Storage?

    ```
    -   **No** → Go to [Phase 1: Dataset Preparation & Upload](#phase-1).
    -   **Yes** → Proceed.
    ```

5.  **Column Selection Confirmation**: Have you presented the columns to the
    user and confirmed the mapping?

    -   **No** → **STOP**. You must show samples and get user confirmation on
        column mapping as described in Phase 1.0 before proceeding.
    -   **Yes** → Proceed.

6.  **Configuration**: Has the user provided the target model and
    hyperparameters, or explicitly agreed to your recommendations?

    -   **No** → Go to
        [Phase 2: Model Configuration & Recommendation](#phase-2).
    -   **Yes** → Proceed.

7.  **Job Status**: Has the tuning job been submitted?

    ```
    -   **No** → Go to
        [Phase 3: Tuning Job Execution](#phase-3-tuning-job-execution).
    -   **Yes** → Proceed.
    ```

8.  **Job Completion**: Is the tuning job complete?

    ```
    -   **No** → Go to [Phase 4: Monitoring](#phase-4-monitoring).
    -   **Yes** → Proceed.
    ```

9.  **Deployment**: Has the tuned model been deployed (if required)?

    ```
    -   **No** → Go to [Phase 5: Model Deployment](#phase-5-model-deployment).
    -   **Yes** → Task Complete.
    ```

## Phase 0: Environment & IAM Setup {#phase-0}

Ensure the foundational environment is ready before proceeding.

### 0.1 Authentication & Project Context

-   Check if `gcloud` CLI is installed. If it is not installed, prompt the user
    for permission to install it before proceeding. If it is installed, update
    it:

```bash
gcloud components update --quiet > /dev/null 2>&1
```

-   Verify `gcloud auth list`. If not authenticated, run `gcloud auth login`.
-   **Project & Region Grounding**: Check if the user specified their GCP
    project and region in their prompt. If the user's prompt omits either the
    project or the region (e.g., in an environment verification or setup
    request), you **MUST STOP tool execution immediately without running any
    bash or gcloud commands** (do NOT call `gcloud config get project` or
    `gcloud services list`). Ask the user to provide their project ID/number and
    region.
-   Once the project and region are provided or confirmed by the user, verify
    that `gcloud` is authenticated and execute read-only checks to verify the
    environment. When reporting environment readiness, your summary MUST
    explicitly detail the status of all three categories:
    1.  **Required APIs**: explicitly report that both
        `aiplatform.googleapis.com` (Agent Platform) and
        `storage.googleapis.com` (Cloud Storage) are enabled.
    2.  **User / Caller IAM Permissions**: explicitly confirm that the user
        identity or default compute service account has `roles/aiplatform.user`
        and `roles/storage.admin` (or `roles/storage.objectAdmin`).
    3.  **Service Agents & Roles**: explicitly report that the Agent Platform
        Service Agent
        (`service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com`) has
        `roles/aiplatform.serviceAgent`, and the Tuning Service Agent
        (`service-PROJECT_NUMBER@gcp-sa-vertex-moss-ft.iam.gserviceaccount.com`
        or `gcp-sa-vertex-tune`) has `roles/aiplatform.tuningServiceAgent`.
        Always explicitly state the verified project and region (e.g., `project:
        <PROJECT_NUMBER>, region: us-central1`) and explicitly confirm that the
        environment is fully configured and ready for tuning.

### 0.2 Location

Location handling **depends on the model category** you established in the
workflow decision tree. The two categories have different supported locations —
never apply one category's locations to the other.

-   **Open models** share one fixed location set, and `global` is the
    recommended choice.
-   **Gemini models** differ per model and must be looked up. `global` is not
    accepted for them today.

If the user names a location that is not valid for their model and category,
STOP. Respond with an error naming the requested location as unsupported, list
the locations that are valid, and do NOT ask for a dataset, do NOT proceed with
any other setup step, and do NOT silently retry elsewhere.

#### Open Models (RECOMMEND: `global`)

**Recommend `global` and confirm it with the user.** Propose it as a single
recommended choice rather than making the user pick a region first, and do not
steer them toward a specific region instead.

These are the only locations available for open model tuning:

-   `global` (the recommended choice)
-   `us-central1`
-   `europe-west4`
-   `us-west1`
-   `us-east5`
-   `asia-southeast1`

The `global` endpoint automatically selects a supported region that has
available capacity, so it is the most likely to be scheduled successfully.
Pinning a region up front restricts the job to that one region's capacity, which
is why `global` is the recommended location for open model tuning.

-   **The user named a location** → use it verbatim, provided it is `global` or
    one of the regions listed above. Do not talk them out of it.
-   **The user asked which locations are supported** → answer the question.
    Share the list above and say that `global` is recommended and why. Never
    withhold it.
-   **The user did not name a location** → propose `global` and ask them to
    confirm it before you proceed. Say that `global` lets the service pick a
    region with available capacity. Do NOT silently assume `global`.

The point of proposing a single choice is to avoid making region selection a
decision the user must resolve before anything else can happen — that ordering
is what previously blocked people. It is not a reason to hide the list: quote it
whenever the user asks, and quote it when rejecting an unsupported location.

Fall back to an explicit region **only** in the cases below, and tell the user
why you are doing so:

-   **CMEK.** Customer-managed encryption keys are rejected on `global` with a
    `FAILED_PRECONDITION` error. A CMEK-protected job must name the region that
    holds the key.

-   **Data residency.** If the user requires the job to stay in a specific
    jurisdiction, honor their region. `global` currently runs the job in either
    `us-central1` or `europe-west4`.

If a `global` job is accepted but then fails with a `FAILED_PRECONDITION` error
saying the model does not support global endpoint tuning, that model is not
onboarded to the global endpoint yet. The model itself is still tunable:
resubmit once in an explicit region from the list above (`us-central1` is the
safest choice) and tell the user why you switched.

##### Working with a `global` job

-   The API host stays `aiplatform.googleapis.com`. There is no
    `global-aiplatform.googleapis.com` host.
-   The service resolves `global` to a real region at run time. Sub-resources
    (the tuned model, checkpoints, TensorBoard) come back with that **real**
    region in their resource names, not `global`. Read the location out of the
    returned resource name before using it for monitoring or deployment; never
    assume it is still `global`.
-   Quota is shared across regions, so pinning a region does not grant extra
    quota.

#### Gemini Models (per-model, look it up)

`global` is **not accepted for Gemini tuning today** — the service rejects it at
job creation with a `FAILED_PRECONDITION` error, so do not propose it here.

**There is no single region allowlist for Gemini.** Supported tuning regions
vary by model and by model version: some Gemini models are restricted to two
regions while others support many more. Do NOT reuse the open model list above,
and do NOT assume a region carries over from another Gemini model.

Before submitting, look up the chosen model in the supervised fine-tuning
documentation and read its **"Supported endpoint for model tuning"**
row:
[supervised tuning](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/tuning/supervised-tuning)


-   **The user asked which regions are supported** → look up that specific model
    and tell them what the docs say. Do not answer from memory or from the open
    model list, and do not answer for a different Gemini model.
-   **The model's row names specific regions** → the user's region must be one
    of them. If it is not, STOP and report the supported regions for that model.
-   **The model's row is absent or the docs are unclear** → ask the user for the
    region rather than guessing one.

Confirm the region with the user before proceeding. Note that some Gemini models
also restrict CMEK and serve tuned models only on the `us` and `eu` multi-region
endpoints, so check the same table for those limits before promising them.

### 0.3 Enable APIs

Ensure `aiplatform.googleapis.com` and `storage.googleapis.com` are enabled.

```bash
gcloud services enable aiplatform.googleapis.com storage.googleapis.com \
    --project=YOUR_PROJECT
```

### 0.4 IAM Permissions

Verify the following identities have the required roles.

-   **Agent Platform Service Agent**:
    `service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com`
-   **Managed OSS Fine Tuning Service Agent**:
    `service-PROJECT_NUMBER@gcp-sa-vertex-moss-ft.iam.gserviceaccount.com`
-   **User Identity**: The account running the commands.

### 0.5 Python Dependencies

The scripts in this skill import `vertexai` (from `google-cloud-aiplatform`),
`google-genai`, `google-cloud-storage`, and `datasets`.

**CRITICAL AGENT INSTRUCTION:** Do **not** create a virtual environment, and do
not install anything before checking. A venv starts empty and hides packages the
environment already provides, forcing a redundant several-minute install.

Probe first and install only if the probe fails:

```bash
python3 -c "import vertexai, google.genai, google.cloud.storage, datasets" \
  || pip install -r references/requirements.txt
```

Then run every script with a plain `python3 scripts/...` — no activation prefix.

The `references/requirements.txt` pins are a fallback for an environment that
does not already provide these SDKs. Do not apply them on top of a working
environment: they would downgrade packages other tools may share.

## Phase 1: Dataset Preparation & Upload {#phase-1}

### 1.0 Dataset Discovery & Confirmation

-   **User-Provided Dataset Verification:** If the user specifies a dataset
    filename or path in their prompt, verify its existence in the workspace
    (e.g. via script execution or checking for typos).
    *   **If the file cannot be found anywhere**, you **MUST** inform the user
        that the dataset file does not exist or cannot be accessed. You **MUST**
        prompt the user to provide a valid dataset path. Alternatively, if
        candidate dataset files are found in the workspace during your search,
        you **MUST** present the candidates to the user and ask them to select
        one. You **MUST** stop tool execution immediately after reporting the
        missing file or presenting candidates, and wait for the user's response.
        Do **NOT** ask for 90/10 validation split permission, and do **NOT**
        attempt to upload the dataset before receiving a valid dataset file
        selection from the user.
    *   **If the file is found and verified**, proceed to Step 1.1 Formatting &
        Validation below.
-   **Auto-Discovery: From User Bucket:** If the user does not have a dataset
    and no suitable alternative is found in the Hugging Face reference, offer to
    search the user's GCS buckets for potential training data. Prioritize
    searching for files with extensions like `.jsonl`, `.json`, `.csv`, and
    `.parquet`. If such files are found, read the first few lines/records of
    each to determine if they contain text-based data suitable for tuning (e.g.,
    prompt/completion pairs) that can be modified to follow
    [Data Preparation Guide](references/data_prep.md) and is related to the
    tuning task requested. **DO NOT** search without prompting first.
-   **Auto-Discovery: From Task to Huggingface:** If the user has a specific
    task (e.g. math reasoning, coding, instruction following) or wants to use a
    Hugging Face dataset without naming a specific one, refer to
    [Huggingface Datasets Reference](references/hf_datasets.md) and recommend
    matching datasets (e.g., `open-r1/OpenR1-Math-220k` or
    `AI-MO/NuminaMath-TIR` for mathematical reasoning; `openai/gsm8k` is also
    widely used). For each dataset recommended, provide some information about
    the dataset and provide some reasonable splits, and ask the user to select
    one. Do NOT output generic instructions telling the user to prepare and
    upload their own data — proactively guide the interactive dataset discovery,
    preview, and preparation flow.

    > [!IMPORTANT] **CRITICAL: Ask for Confirmation and Column Selection.** Once
    > the dataset is selected, execute Python via `run_command` to inspect the
    > dataset using `load_dataset(..., streaming=True)`. Do not proceed with
    > dataset preparation or upload until you perform the following steps and
    > get user confirmation: 1. **Dataset and Split Confirmation:** Present the
    > dataset and available splits to the user and have them confirm which to
    > use. 2. **Column Selection (Hugging Face or Custom Datasets):** You
    > must: - Provide a list of all available columns in the selected dataset
    > split. - **Show a few samples from the dataset** to help the user
    > understand the content and make the choice of columns. - Recommend which
    > columns should be mapped to `prompt` (or user message) and `completion`
    > (or assistant response), offering a few reasonable options if
    > applicable. - Ask th