智能体 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 万个 token 的上下文窗口，但长上下文序列可能会引入噪声、延迟和上下文降级。保持工作记忆的整洁有助于确保长时间运行的智能体保持准确。

上下文清理策略

请使用以下策略来管理长时间运行的智能体中的上下文：

  • 子智能体委托：将孤立的子任务（例如代码分析或日志搜索）委托给短期子智能体，仅将合成摘要返回到主上下文。
  • 状态总结：定期总结多轮对话历史记录，舍弃临时调试日志并保留关键事实。
  • 记忆文件：在外部 Markdown 文件（例如 GOALS.md 和 MEMORY.md）中持久保存结构化状态、项目限制和操作上下文，而不是在上下文中保留整个原始对话历史记录。

人机协同 (HITL) 检查点

在实时 Google Cloud 环境中运行的自主智能体应针对高风险操作强制执行审批检查点。

需要 HITL 的高风险操作

在智能体执行以下任何操作之前，需要获得人工批准：

  • 访问权限和权限：修改 Identity and Access Management (IAM) 角色、授予服务账号访问权限或使资源可公开访问，例如允许对服务进行未经身份验证的访问或向所有 IP 地址开放防火墙规则。
  • 资源删除：删除 Cloud SQL 数据库、Cloud Storage 存储桶、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"
}

自动错误恢复和重试循环

在分布式云环境中，工具执行失败是不可避免的。 智能体应自主处理暂时性错误、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 工具架构的智能体系统指令。

旧版非结构化文本提示词

以下示例将 shell 命令嵌入到非结构化文本提示中，这可能会导致幻觉工具调用或缺少参数：

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

后续步骤