代理式 AI 的系統指令和提示工程

如要在Google Cloud上建構可靠且安全的自主 AI 代理，您可以結合結構化系統指令、明確的工具結構定義、推論界限、人工介入迴路 (HITL) 安全控管機制，以及脈絡衛生。與依賴基本輸入輸出提示的互動式聊天機器人不同，採用 Gemini 的代理系統會執行多步驟規劃、叫用外部 API、監控執行回饋，並在多輪工作流程中維持工作記憶。

本文說明設計自主代理的架構模式和提示工程做法。如需 Gemini Cloud Assist 或 IDE 對話互動式提示的撰寫訣竅，請參閱「撰寫更有效的 Gemini in Google Cloud提示」。

系統指示

在代理架構中，您可以使用系統指令定義代理的基本身分、規則和權限。與每次對話都會變更的標準使用者提示不同，系統指令只需定義一次，即可在各個執行回合中一致傳遞。

系統指令定義下列項目：

  • 基準身分和角色：定義代理的角色和主要功能，例如「你是資料庫管理員代理」。
  • 行為規則：建立作業限制、安全界線和輸出格式規定，例如「未經人工核准，不得執行寫入作業」或「以 JSON 格式傳回結果」。
  • 工具呼叫指南：定義工具選取、排序和重試規則。

下一節的範例會將這些項目分別歸入各自的 XML 標記：<role>、<rules> 和 <tool_usage>。

系統指令不應包含動態執行階段輸入內容，例如使用者問題、檔案內容或工具執行記錄。在執行回合期間傳送的內容酬載中，請保留這些動態價值。

使用 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>

使用 <role>、<rules> 和 <tool_usage> 等 XML 標記分隔指令時，模型會將每個區塊視為不同類別的指引。

系統指令常用的 XML 標記

雖然 Gemini 可以剖析任何符合您領域的自訂 XML 標記，但使用一組通用標記有助於保持指令一致，並更容易在代理之間維護。

下表列出可用來建構系統指令的範例標記。標記名稱是慣例，因此您可以重新命名，以符合代理程式的需求。舉例來說，CX Agent Studio 指令指南會使用 <constraints>，代表本文件在 <rules> 中提供的指引類型。

標記 說明
<role> 定義代理的核心身分、角色和主要功能。
<rules> 列出限制、格式規則和安全界限。
<tool_usage> 概述選擇和呼叫工具的政策。
<example> 包含少量樣本，顯示預期的輸入和輸出內容。每個範例使用一個標記。

如需更多詳細資料和提示模式，請參閱下列資源：

工具和函式定義的最佳做法

在代理系統中，您可以使用工具和呼叫函式，讓代理與 Google Cloud API、資料庫和微服務互動。模型會比對您定義的結構定義，要求執行用戶端程式碼，因此請務必提供清楚明確的工具宣告，以免發生叫用錯誤。

結構定義設計原則

定義工具結構定義時，請遵循下列原則：

  • 使用明確類型：在 OpenAPI 或 JSON 結構定義中，為每個參數指定精確的資料類型，例如 string、integer、boolean、array 或 object。
  • 提供有意義的說明：請說明每個參數的格式規定、限制和有效範圍，不要只依賴欄位名稱。
  • 宣告必要欄位：在 JSON 結構定義中填入 required 陣列，確保模型不會傳遞 null 或省略必要欄位的引數。
  • 使用列舉限制值：針對具有固定有效輸入內容的欄位 (例如環境名稱或記錄嚴重性等級)，使用 enum 值。

函式宣告結構定義範例

以下範例定義了函式宣告，其中包含用於重新啟動 Google Kubernetes Engine (GKE) 部署作業的工具 JSON 結構定義：

{
  "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. 規劃：分析提示、找出依附元件，並制定一系列工具呼叫。
  2. 驗證：根據系統限制、安全政策和必要參數，檢查建議的工具呼叫。
  3. 執行：發出工具呼叫，並觀察執行結果。

內建思考功能會在內部管道執行，而非在回覆文字中發出 <thinking> XML 標記。如果在 thinking_config 中設定 include_thoughts=True，就能在工具呼叫前檢查思考摘要 (part.thought)：

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.

在 SDK 中設定 thinking_config 時，請設定 thinking_level (適用於 Gemini 3 模型) 或 thinking_budget (適用於 Gemini 2.5 模型)，在推論深度和延遲時間之間取得平衡。

維護脈絡窗口和工作記憶

雖然旗艦級 Gemini 模型支援 100 萬個詞元的脈絡窗口，但長脈絡序列可能會導致雜訊、延遲和脈絡降級。維護工作記憶體衛生，有助於確保長時間執行的代理保持準確。

情境整理策略

請使用下列策略，管理長時間執行的代理中的情境：

  • 委派子代理：將程式碼分析或記錄搜尋等獨立子任務委派給短期子代理，只將彙整摘要傳回主要情境。
  • 狀態摘要：定期總結多輪對話記錄，捨棄暫時性偵錯記錄檔，並保留重要事實。
  • 記憶檔案：將結構化狀態、專案限制和作業脈絡，保存在外部 Markdown 檔案 (例如 GOALS.md 和 MEMORY.md)，而非在脈絡中保留完整的原始對話記錄。

人工介入迴路 (HITL) 查核點

在實際運作 Google Cloud 環境中運作的自主代理，應對高風險作業強制執行核准檢查點。

需要 HITL 的高風險作業

代理執行下列任一作業前，必須先經過人工核准：

  • 存取權和權限：修改 Identity and Access Management (IAM) 角色、授予服務帳戶存取權，或將資源設為可公開存取，例如允許未經驗證的服務存取，或向所有 IP 位址開放防火牆規則。
  • 刪除資源：刪除 Cloud SQL 資料庫、Cloud Storage bucket、Pub/Sub 主題或 GKE 節點集區等資源。
  • 計費和配額：佈建高成本機型 (例如 Cloud TPU Pod 或多 GPU 執行個體)，或提高配額上限。

設計核准暫停

請勿單靠提示指令來限制破壞性動作。由於應用程式程式碼會執行工具，因此請在自動化調度管理工具中強制執行核准檢查，在執行高風險 function_call 要求前攔截這些要求，並向人工審查員顯示確認酬載：

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

自動錯誤復原和重試迴圈

在 Distributed Cloud 環境中，工具執行失敗是不可避免的。代理應能自行處理暫時性錯誤、PERMISSION_DENIED 狀態碼和結構定義驗證失敗。

錯誤意見回饋架構

工具呼叫傳回錯誤時，請將原始錯誤輸出內容和重試指引一併傳回代理的脈絡，而不是立即失敗：

  • 結構定義不符：如果參數格式無效，請將結構定義錯誤傳回模型，以便修正工具引數。
  • 權限遭拒錯誤：指示代理檢查必要的 IAM 權限，或改用唯讀診斷工具。
  • 頻率限制和節流：在用戶端程式碼中，使用指數輪詢處理暫時性 429 錯誤，並將永久配額錯誤傳回模型，以便調整計畫。

使用呼叫函式時，請在 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."
        ),
    },
)

程式碼結構定義範例 (前後對照)

以下比較說明如何使用 Google Gen AI SDK，從舊版非結構化文字提示詞，轉換為具有結構化 JSON 工具結構定義的代理系統指令。

舊版非結構化文字提示詞

以下範例將殼層指令嵌入非結構化文字提示詞，可能導致幻覺工具呼叫或缺少參數：

# 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.

後續步驟