ניהול שינויים ותנועה

ב-Gemini Enterprise Agent Platform, אפשר ליצור גרסאות קבועות, או עדכונים, של סוכן. לאחר מכן, תוכלו לפצל את תנועת הגולשים בין הגרסאות הפעילות השונות. פיצול התנועה מאפשר לכם לבדוק ולהגדיל בהדרגה את התנועה לגרסאות חדשות, ולפצל את התנועה בין גרסאות למטרות אחרות.

היכולת ליצור גרסאות תמיד מופעלת. אין צורך להפעיל את התכונה. מידע על יצירת עדכונים זמין במאמר עדכונים ומצבים.

אם עדיין לא יצרתם גרסאות, תצטרכו ליצור גרסאות לפני שתוכלו להציג אותן ולהגדיר את התנועה ביניהן, כמו שמתואר בדף הזה.

בשלב הזה, גרסאות קודמות ופיצול תנועה זמינים דרך v1beta1 API.

בדף הזה מוסבר איך לנהל גרסאות של סוכנים ופיצול תנועה.

גרסאות וסטטוסים

גרסה היא תמונת מצב של סוכן. כשיוצרים סוכן או מעדכנים את השדות עם הגרסאות שלו, נוצרת גרסה קבועה של הסוכן. סטטוס הגרסה הוא פעיל כשהיא זמינה לשאילתות. שימו לב: יכול להיות שהשירות לא יקבל שאילתות, בהתאם להגדרת התנועה. כשמעבירים גרסה לארכיון, היא יוצאת משימוש באופן סופי ולא ניתן לשחזר אותה. גרסאות שנשמרו בארכיון נשמרות רק למטרות היסטוריות.

אפשר לזהות את הגרסה באמצעות שם המשאב שלה, שאפשר למצוא אותו על ידי הצגת רשימת הגרסאות של הסוכן.

מגבלות על גרסאות קודמות

גרסאות שנשמרו בארכיון לא תופסות יותר משבצת של גרסה. שינוי של שיוך של Agent Gateway מעביר לארכיון כל גרסה קודמת (ראו Agent Gateway וגרסאות), כך ששינוי של שיוך מפנה מכסה במקום לצרוך אותה. אפשר למחוק גרסאות שהועברו לארכיון.

שדות עם גרסאות ושדות ללא גרסאות

בקטע הזה מפורטים השדות בהגדרת ReasoningEngineSpec של סוכן שפרסתם, שאפשר לעדכן כדי ליצור גרסה חדשה של הסוכן.

כשמעדכנים שדות עם גרסאות, נוצרת גרסה חדשה.

כשמעדכנים שדות ללא ניהול גרסאות או שדות בהגדרה של סוכן שאינם שדות עם ניהול גרסאות, הסוכן מתעדכן בכל הגרסאות שלו.

אלה השדות עם הגרסאות:

• PackageSpec
  • pickleObjectGcsUri
  • dependencyFilesGcsUri
  • requirementsGcsUri
  • pythonVersion
• DeploymentSpec
  • env[]
  • secretEnv[]
  • firstPartyImageOverride
  • agentServerMode
  • pscInterfaceConfig
  • minInstances
  • maxInstances
  • resourceLimits
  • containerConcurrency
• classMethods[]
• agentFramework
• SourceCodeSpec
  • source
  • languageSpec
• identityType
• agentCard[]

הצגת רשימה של עדכונים לסוכנים

אפשר לראות רשימה של כל הגרסאות של סוכן שפרסתם.

כדי למצוא את מזהה המשאב של הסוכן, אפשר להיעזר במאמר איך מקבלים את מזהה המשאב של הסוכן.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revisions = client.runtimes.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

for revision in revisions:
    print(revision)

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions" | Select-Object -Expand Content

{
  "reasoningEngineRuntimeRevisions": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
        "spec": {
          // Revision-specific config attributes (e.g., package specs, requirements)
        },
        "createTime": "2026-05-01T13:26:01Z",
        "state": "ACTIVE"
      }...
    ]
}

קבלת פרטים על שינוי

אפשר לאחזר את הפרטים של גרסה ספציפית.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

print(revision)

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
  "spec": {
    // Revision-specific config attributes (e.g., package specs, requirements)
  },
  "createTime": "2026-05-06T13:05:24Z",
  "state": "ACTIVE"
}

הגדרת חלוקת התנועה בין גרסאות

אתם יכולים לקבוע איך התנועה תתחלק בין הגרסאות הפעילות. הערה: פיצול התנועה מתבצע רק בשאילתות שמכוונות למשאב הבסיסי reasoningEngine. הפניית שאילתה לנתיב ספציפי של משאב גרסה עוקפת באופן מפורש את כללי התנועה.

התנועה מחולקת באחת משתי שיטות:

• לפי אחוזים: כשמגדירים לפי אחוזים, אחוז מסוים של תנועה מופנה לכל גרסה של הסוכן. כל אחוז שצוין חייב להיות מספר שלם. סכום האחוזים חייב להיות 100%. גם אם יש רק גרסה פעילה אחת, עדיין אפשר להגדיר פיצול תנועה (שבו 100% מההפניות מועברות אליה).
• לגרסה העדכנית ביותר: כל התנועה מופנית לגרסה העדכנית ביותר. כשיוצרים גרסה חדשה של סוכן, התנועה מופנית אוטומטית לגרסה החדשה.

פיצול ידני יכול להתבצע רק בגרסאות פעילות. מתן שם לגרסה קודמת שהועברה לארכיון מחזיר FAILED_PRECONDITION:

Traffic target revision {revision} is not an active revision of this Agent Engine. Update traffic_config to reference only active revisions.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "traffic_config": {
            "trafficSplitManual": {
                "targets": [
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
                        "percent": 50,
                    },
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
                        "percent": 50,
                    },
                ]
            }
        }
    },
)

{
  "trafficConfig": {
    "trafficSplitAlwaysLatest": {}
  }
}

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config

{
  "trafficConfig": {
    "trafficSplitManual": {
      "targets": [
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
            "percent": TRAFFIC_PERCENTAGE_1
          },
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
            "percent": TRAFFIC_PERCENTAGE_2
          }
        ]
      }
    }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

שאילתה לגבי שינוי ספציפי

אפשר לשלוח שאילתה לגבי עדכון ספציפי דרך ה-SDK או ממשקי ה-API. כדי להריץ שאילתה על עדכון, הוא צריך להיות פעיל. שאילתות שמופנות לגרסה ספציפית עוקפות את כללי חלוקת התנועה.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

response = revision.query(
    input={"your_input_key": "your_input_value"},
    config={"class_method": "your_class_method"},
)

print(response)

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query" | Select-Object -Expand Content

‫Agent Gateway ושינויים

צירוף של קישור Agent Gateway לסוכן, שינוי שלו או ניתוק שלו מהסוכן יוצרים גרסה חדשה ומעבירים לארכיון כל גרסה שהייתה קיימת לפני השינוי. רק הגרסה החדשה נשארת פעילה. הפעולה הזו בלתי הפיכה, ואי אפשר לשחזר גרסאות שהועברו לארכיון.

שינוי מחייב מארכב כל גרסה קיימת, ולכן הוא מותר רק אם כל התנועה כבר נמצאת בגרסה האחרונה. ה-API דוחה את השינוי אם מוגדר פיצול ידני כלשהו, גם אם הוא מפצל 100% מהתנועה לגרסה האחרונה. הדחייה מחזירה את הערך FAILED_PRECONDITION:

Changing spec.deployment_spec.agent_gateway_config archives every existing runtime revision, so it is only allowed while all traffic is on the latest revision. Set traffic_config.traffic_split_always_latest, or clear traffic_config, before changing the Agent Gateway configuration.

כדי לשנות את שער הכניסה בסוכן שמשתמש בפיצול תנועה ידני:

1. כדי לעבור לניתוב תמיד לגרסה העדכנית ביותר, מגדירים את traffic_config.traffic_split_always_latest (או מוחקים את traffic_config). מידע נוסף זמין במאמר הגדרת חלוקת התנועה בין גרסאות.
2. שינוי של spec.deployment_spec.agent_gateway_config. כך נוצרת הגרסה החדשה וכל הגרסאות הקודמות עוברות לארכיון.
3. אם תצטרכו שוב פיצול ידני, תצטרכו ליצור אותו מהעדכונים שנוצרו אחרי שינוי הקישור.

עדיין אפשר לגשת לגרסאות שנשמרו בארכיון דרך ה-API, וכל ה-ReasoningEngineSpec שלהן נשמר. כדי ליצור גרסה חדשה ששווה לגרסה שהועברה לארכיון, מאחזרים את הפרטים של הגרסה שהועברה לארכיון ומפעילים גרסה חדשה עם אותם שדות עם ניהול גרסאות. שימוש חוזר באותו URI של קובץ אימג' של קונטיינר יוצר את אותה סביבת זמן ריצה, ושימוש חוזר באותו מיקום של קוד המקור ובאותן שיטות של מחלקות יוצר את אותו אופן פעולה.

מעקב אחרי גרסאות

כדי לעקוב אחרי פעילות ובעיות בגרסאות, אפשר לעקוב אחרי מספר הגרסה כמטא-נתונים ביומנים. מידע על הגדרת רישום ביומן זמין במאמר הגדרת רישום ביומן.

יצירת גרסה חדשה של סוכן

כדי ליצור גרסה חדשה, מעדכנים את השדות עם מספור הגרסאות של סוכן פעיל. הוראות מפורטות זמינות במאמר בנושא עדכון של סוכן פעיל.

אם מעדכנים שדות עם גרסאות, נוצרת אוטומטית גרסה חדשה. אם מעדכנים שדות שלא מנוהלים באמצעות בקרת גרסאות, הסוכן מתעדכן בכל הגרסאות הקיימות שלו בלי ליצור גרסה חדשה.

ניהול ניקוי הגרסאות

‫Gemini Enterprise Agent Platform מסירה באופן אוטומטי גרסאות ישנות כדי לעזור לכם לא לחרוג ממגבלות הגרסאות. אפשר גם למחוק גרסאות באופן ידני.

איסוף אשפה אוטומטי

כברירת מחדל, Gemini Enterprise Agent Platform מאפשרת מנגנון איסוף אוטומטי לכל הסוכנים. אי אפשר להשבית אותו. איסוף האשפה פועל רק כחלק מפעולת עדכון של סוכן; הוא אינו פועל כמשימת רקע.

• מתי היא פועלת: אם פעולת עדכון מנסה לחרוג ממגבלת הגרסאות שהוגדרה, Gemini Enterprise Agent Platform מוחקת את הגרסאות הכי ישנות שעומדות בדרישות באותה פעולה לפני שהיא יוצרת את הגרסה החדשה. אם מקטינים את המגבלה, Gemini Enterprise Agent Platform מוחקת באופן מיידי מספיק מהגרסאות הכי ישנות שעומדות בדרישות כדי לעמוד במגבלה החדשה.
• גרסאות שעומדות בדרישות: גרסה עומדת בדרישות למחיקה רק אם מתקיימים כל התנאים הבאים:
  • הוא במצב ACTIVE.
  • הוא לא נכלל בהגדרת התנועה (מקבל 0% מהתנועה).
• כשלים: אם אין מספיק גרסאות שעומדות בדרישות כדי לפנות מקום, Gemini Enterprise Agent Platform דוחה את פעולת העדכון עם שגיאה FAILED_PRECONDITION. הפעולה הזו לא מוחקת גרסאות מתוקנות ולא יוצרת גרסה מתוקנת חדשה. כדי לנסות שוב, צריך להסיר את הגרסאות מהגדרת התנועה או להגדיל את המגבלה.

הגדרת המגבלה

המגבלה מוגדרת בשדה revision_garbage_collection_strategy.keep_n_latest.max_revisions בסוכן. אפשר להגדיר את השדה הזה כשיוצרים את הסוכן או לשנות אותו בהמשך באמצעות בקשת עדכון.

• ברירת המחדל לסוכנים חדשים: 100 גרסאות.
• ברירת מחדל לסוכנים קיימים: 950 גרסאות.
• הטווח המותר: 1 עד 950. המערכת דוחה ערך של 0 או פחות. ערך שגדול מ-950 נדחה כי 950 היא מכסה קשיחה שלא ניתן להגדיל.

מחיקה ידנית

אפשר להסיר באופן ידני גרסה של סוכן על ידי מחיקתה. אפשר למחוק רק גרסאות שלא פעילות לניהול תעבורה, כי הן לא מוגדרות לקבל תעבורה. הוראות להגדרה של קבלת תנועה בגרסה מפורטות במאמר הגדרת חלוקת התנועה בין גרסאות.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.revisions.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content