/agent-platform-tuning

name: agent-platform-tuning
metadata:
  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

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. **Model Category Identification**: Has the user explicitly stated whether they want to tune an **Open Model** or a **Gemini Model**?

• **No** → **STOP**. Ask the user if they want to tune an Open Model or a

Gemini Model. **CRITICAL EXCEPTION for Environment Setup Requests:** If the user is specifically asking for environment setup instructions (e.g. "What environment setup is needed?"), you **MUST** provide the full [Phase 0 environment setup](#phase-0) instructions in your initial response, *simultaneously* with asking clarifying questions about the model category.

• 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. Do not recommend unsupported models like Mistral. 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.

• **Yes** → Proceed.

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

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

3. **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.

4. **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.

5. **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.

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

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

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

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

8. **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:

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

• Verify `gcloud auth list`. If not authenticated, run `gcloud auth login`.
• Ensure `project` is known. Use `gcloud config get project` to retrieve the

current project.

• **CRITICAL: Ask for Confirmation.** You must prompt the user to confirm the

retrieved project before proceeding, in case they want to switch to a different one. The location must also be confirmed — see section 0.2 for which location to propose, which depends on the model category.

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