הוראות מערכת והנדסת פרומפטים ל-AI אקטיבי

כדי לפתח סוכני AI אוטונומיים שפועלים באופן אמין ובטוח בסביבת הייצור ב-Google Cloud, אתם יכולים לשלב הוראות מערכת מובְנות, סכימות מפורשות של כלים, גבולות חשיבה, אמצעי בטיחות של האדם שבתהליך (HITL) וניקוי הקשר. בניגוד לצ'אט בוטים אינטראקטיביים שמסתמכים על הנחיות קלט-פלט בסיסיות, מערכות מבוססות-סוכנים עם Gemini מבצעות תכנון בכמה שלבים, מפעילות ממשקי API חיצוניים, עוקבות אחרי משוב על הביצוע ושומרות זיכרון עבודה בתהליכי עבודה עם כמה שלבים.

במאמר הזה מתוארים דפוסי ארכיטקטורה ושיטות להנדסת פרומפטים, שנועדו לעזור לכם לתכנן סוכנים אוטונומיים. אם אתם מחפשים טיפים לכתיבת הנחיות אינטראקטיביות ל-Gemini Cloud Assist או לצ'אט ב-IDE, קראו את המאמר איך כותבים הנחיות טובות יותר ל-Gemini ב- Google Cloud.

הוראות מערכת

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

ההוראות למערכת מגדירות את הדברים הבאים:

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

בדוגמה שבקטע הבא, כל אחד מהם מקובץ בתג XML משלו: <role>,‏ <rules> ו-<tool_usage>.

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

מבנה של הוראות מערכת עם תגי XML

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

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

כשאתם מעבירים את הוראת המערכת ל-SDK או ל-API, אל תעטפו את כל בלוק ההוראות בתג חיצוני, כמו <system_instruction>. ה-API כבר מעבד את כל המחרוזת כהוראת מערכת. במקום זאת, השתמשו בתגים נפרדים בתוך הבלוק כדי לקבץ הוראות:

<role>
  You are an autonomous Cloud Infrastructure Management Agent responsible
  for diagnosing and remediating GKE cluster issues.
</role>

<rules>
  - Always run diagnostic tools before proposing or applying remediation.
  - Never delete storage volumes, IAM bindings, or database
    instances without explicit human authorization.
  - Verify target cluster and namespace names from diagnostic output before
    proposing changes.
</rules>

<tool_usage>
  - Call `gke_get_cluster_status` to fetch node pool health.
  - Call `gke_inspect_logs` to retrieve pod error logs.
  - Use strict JSON schemas when supplying tool parameters.
</tool_usage>

כשמפרידים בין ההוראות באמצעות תגי XML כמו <role>,‏ <rules> ו-<tool_usage>, המודל מתייחס לכל בלוק כקטגוריה נפרדת של הנחיות.

תגי XML נפוצים להוראות מערכת

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

בטבלה הבאה מפורטים תגים לדוגמה שאפשר להשתמש בהם כדי ליצור מבנה להוראות המערכת. שמות התגים הם מוסכמות, כך שאפשר לשנות את השמות שלהם כך שיתאימו לנציג. לדוגמה, במדריך ההוראות של CX Agent Studio משתמשים ב-<constraints> לסוג ההנחיות שבמסמך הזה מופיעות ב-<rules>.

תג תיאור
<role> מגדירה את הזהות, התפקיד והפונקציה העיקרית של הסוכן.
<rules> מפרט מגבלות, כללי עיצוב וגבולות בטיחות.
<tool_usage> מדיניות לבחירת כלים ולהפעלתם.
<example> מכיל דוגמה של פרומפט עם כמה דוגמאות (few-shot) שמראה קלט ופלט מצופים. צריך להשתמש בתג אחד לכל דוגמה.

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

שיטות מומלצות להגדרת כלים ופונקציות

במערכות מבוססות-סוכנים, משתמשים בכלים ובקריאה להפעלת פונקציות כדי לתת לסוכנים את היכולת לתקשר עם ממשקי API, מסדי נתונים ומיקרו-שירותים (microservices) של Google Cloud . המודל מבקש להריץ קוד בצד הלקוח על ידי התאמת סכימות שאתם מגדירים, ולכן חשוב לספק הצהרות ברורות וחד-משמעיות לגבי הכלים כדי למנוע שגיאות בהפעלה.

עקרונות לעיצוב סכימה

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

  • השתמשו בהקלדה מפורשת: ציינו סוגי נתונים מדויקים, כמו string, integer, boolean, array או object, לכל פרמטר בסכימות OpenAPI או JSON.
  • לספק תיאורים משמעותיים: הסבירו את דרישות הפורמט, המגבלות והטווחים החוקיים של כל פרמטר, במקום להסתמך רק על שמות השדות.
  • הצהרה על שדות חובה: מאכלסים את המערך required בסכימות JSON כדי שהמודל לא יעביר את הערך null או ישמיט ארגומנטים של שדות חובה.
  • הגבלת ערכים באמצעות טיפוסי enum: השתמשו בערכי enum בשדות עם קלט תקין קבוע, כמו שמות של סביבות או רמות חומרה של יומנים.

סכימה לדוגמה של הצהרת פונקציה

בדוגמה הבאה מוגדרת הצהרת פונקציה עם סכימת JSON לכלי שמפעיל מחדש פריסה של Google Kubernetes Engine‏ (GKE):

{
  "name": "restart_gke_deployment",
  "description": "Performs a rolling restart of a GKE deployment.",
  "parameters": {
    "type": "object",
    "properties": {
      "cluster_id": {
        "type": "string",
        "description": "Fully qualified GKE cluster resource ID."
      },
      "namespace": {
        "type": "string",
        "description": "Kubernetes namespace containing the deployment."
      },
      "deployment_name": {
        "type": "string",
        "description": "The exact metadata name of the deployment."
      },
      "environment": {
        "type": "string",
        "description": "Target environment for the restart.",
        "enum": ["dev", "staging", "prod"]
      },
      "reason": {
        "type": "string",
        "description": "Brief operational rationale for the restart."
      }
    },
    "required": ["cluster_id", "namespace", "deployment_name", "reason"]
  }
}

אמצעי בקרה להגבלת השימוש בטוקנים להסקת מסקנות וחשיבה

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

הטמעת לולאות של תכנון-אימות-ביצוע

לולאת תכנון-אימות-ביצוע מורכבת מהשלבים הבאים:

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

החשיבה המובנית פועלת בערוץ פנימי במקום להפיק תגי XML של <thinking> בטקסט התשובה. אם מגדירים את include_thoughts=True ב-thinking_config, אפשר לבדוק את סיכומי תהליך החשיבה (part.thought) לפני קריאת API לכלי:

1. User requests scaling down node pool 'pool-1' in cluster
   'prod-us-central1'.
2. Verification: Scaling down production node pools requires checking
   current CPU utilization first.
3. Plan: Call `get_node_pool_metrics` first. If utilization < 30%, request
   human approval before scaling down.

כשמגדירים את thinking_config ב-SDK, מגדירים את thinking_level (למודלים של Gemini 3) או את thinking_budget (למודלים של Gemini 2.5) כדי לאזן בין עומק החשיבה לזמן האחזור.

שמירה על חלון ההקשר וזיכרון העבודה

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

אסטרטגיות לשמירה על תקינות ההקשר

כדי לנהל את ההקשר בסוכנים למשימות מתמשכות, אתם יכולים להשתמש באסטרטגיות הבאות:

  • האצלת סמכויות לסוכני משנה: האצלת משימות משנה מבודדות, כמו ניתוח קוד או חיפוש ביומנים, לסוכני משנה לטווח קצר, והחזרת סיכומים מסונתזים בלבד להקשר הראשי.
  • סיכום מצב: סיכום תקופתי של היסטוריית השיחה, תוך התעלמות מיומני ניפוי באגים זמניים ושמירה על עובדות חשובות.
  • קובצי זיכרון: שומרים מצב מובנה, אילוצי פרויקט והקשר תפעולי בקובצי Markdown חיצוניים, כמו GOALS.md ו-MEMORY.md, במקום לשמור את כל היסטוריית השיחות הגולמית בהקשר.

נקודות בקרה של "האדם שבתהליך" (HITL)

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

פעולות בסיכון גבוה שדורשות HITL

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

  • גישה והרשאות: שינוי תפקידים בניהול זהויות והרשאות גישה (IAM), מתן גישה לחשבון שירות או הפיכת משאבים לנגישים באופן ציבורי, למשל על ידי מתן גישה לא מאומתת לשירות או פתיחת כללי חומת אש לכל כתובות ה-IP.
  • מחיקת משאבים: מחיקת משאבים כמו מסדי נתונים של Cloud SQL, קטגוריות של Cloud Storage, נושאי Pub/Sub או מאגרי צמתים של GKE.
  • חיוב ומכסות: הקצאת סוגי מכונות בעלות גבוהה, כמו מכונות עם Cloud TPU Pods או עם כמה יחידות GPU, או הגדלת מגבלות המכסות.

השהיות לצורך אישור העיצוב

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

{
  "action": "delete_cloud_sql_instance",
  "target_resource": "projects/my-prod/instances/user-db-primary",
  "risk_level": "CRITICAL",
  "status": "WAITING_FOR_HUMAN_APPROVAL"
}

התאוששות אוטומטית משגיאות ולולאות של ניסיונות חוזרים

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

ארכיטקטורת משוב על שגיאות

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

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

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

from google.genai import types

error_part = types.Part.from_function_response(
    name="gke_get_cluster_status",
    response={
        "status": "ERROR",
        "error_code": "PERMISSION_DENIED",
        "message": (
            "Caller lacks permission 'container.clusters.get' on"
            " 'projects/demo/locations/us-central1/clusters/dev'."
        ),
        "remediation_hint": (
            "Verify service account permissions or check another project."
        ),
    },
)

דוגמה לסכימת קוד לפני ואחרי

ההשוואה הבאה ממחישה את המעבר מהנחיית טקסט מדור קודם, לא מובנית, להוראות מערכת מבוססות-סוכנים עם סכימות מובנות של כלי JSON באמצעות Google Gen AI SDK.

פרומפט טקסטואלי לא מובנה מהדור הקודם

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

# Legacy unstructured approach (prone to hallucinated tool calls and missing
# parameters)
prompt = """
You are a Cloud helper. Restart the app deployment in namespace 'prod' for
cluster 'prod-cluster'.
Run command: kubectl rollout restart deployment/web-app -n prod
"""
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
)

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

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

from google import genai
from google.genai import types

# 1. Define explicit function schema with required parameters
restart_deployment_tool = types.FunctionDeclaration(
    name="restart_gke_deployment",
    description=(
        "Executes a rolling restart for a Kubernetes deployment in Google"
        " Kubernetes Engine."
    ),
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "cluster_id": types.Schema(
                type=types.Type.STRING,
                description=(
                    "Fully qualified GKE cluster ID (e.g."
                    " projects/my-project/locations/us-central1/"
                    "clusters/prod-cluster)."
                ),
            ),
            "namespace": types.Schema(
                type=types.Type.STRING,
                description=(
                    "Kubernetes namespace (e.g. default, production)."
                ),
            ),
            "deployment_name": types.Schema(
                type=types.Type.STRING,
                description="Metadata name of the target deployment.",
            ),
        },
        required=["cluster_id", "namespace", "deployment_name"],
    ),
)

# 2. Configure System Instruction with identity, safety rules, and tools
system_instruction = """
<role>You are an autonomous Cloud Infrastructure Remediation Agent.</role>
<rules>
- Always validate parameter schemas before invoking tool calls.
- Require human approval before performing destructive actions.
- Verify cluster and namespace identifiers before invoking remediation tools.
</rules>
"""

config = types.GenerateContentConfig(
    system_instruction=system_instruction,
    tools=[types.Tool(function_declarations=[restart_deployment_tool])],
    thinking_config=types.ThinkingConfig(thinking_budget=1024),
)

client = genai.Client(vertexai=True, project="my-project", location="global")
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=(
        "Restart the deployment 'web-app' in namespace 'prod' under"
        " cluster"
        " 'projects/my-proj/locations/us-central1/clusters/prod-cluster'."
    ),
    config=config,
)

# Inspect response.function_calls, validate arguments, and require human
# approval in your orchestrator before executing restart_gke_deployment.

המאמרים הבאים