Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

エージェント型 AI のシステム指示とプロンプトエンジニアリング

Google Cloudで本番環境で確実かつ安全に動作する自律型 AI エージェントを構築するには、構造化されたシステム指示、明示的なツールスキーマ、推論境界、人間参加型（HITL）安全管理、コンテキストハイジーンを組み合わせます。基本的な入出力プロンプトに依存するインタラクティブな chatbot とは異なり、Gemini を使用するエージェントシステムは、マルチステップの計画、外部 API の呼び出し、実行フィードバックのモニタリング、マルチターンワークフロー全体でのワーキングメモリの維持を行います。

このドキュメントでは、自律型エージェントを設計するためのアーキテクチャパターンとプロンプトエンジニアリングの実践について説明します。Gemini Cloud Assist または IDE チャットのインタラクティブなプロンプトの作成に関するヒントについては、Gemini in Google Cloudにより適したプロンプトを作成するをご覧ください。

システム指示

エージェントアーキテクチャでは、システム指示を使用して、エージェントのベースライン ID、ルール、権限を定義します。ターンごとに変化する標準のユーザープロンプトとは異なり、システム指示は 1 回定義して、実行ターン全体で一貫して渡します。

システム指示では、次の内容を定義します。

ベースラインの ID とロール: エージェントのペルソナと主な機能を定義します（例: 「あなたはデータベース管理者エージェントです」）。
行動ルール: 運用上の制約、安全境界、出力形式の要件を確立します。たとえば、「人間の承認なしに書き込みオペレーションを実行しない」や「結果を 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 の指示ガイドでは、このドキュメントで <rules> に配置されているガイダンスの種類に <constraints> を使用しています。

タグ	説明
`<role>`	エージェントの核となるアイデンティティ、ペルソナ、主な機能を定義します。
`<rules>`	制約、形式ルール、安全境界をリストします。
`<tool_usage>`	ツールの選択と呼び出しに関するポリシーの概要。
`<example>`	想定される入力と出力を示す少数ショットの例が含まれています。1 つの例につき 1 つのタグを使用します。

詳細とプロンプトパターンについては、次のリソースをご覧ください。

ツールと関数の定義に関するベストプラクティス

エージェントシステムでは、ツールと関数呼び出しを使用して、エージェントに 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"]
  }
}

推論と思考予算の管理

複雑なワークフローで実践する前に内部推論を行うために、エージェントは thinking_config パラメータで Gemini の思考機能を使用します。この構成により、エージェントは計画、検証、実行のループを実行して、ツールを呼び出す前にアクションを検証できます。

計画、検証、実行のループを実装する

計画、検証、実行のループは、次のステージで構成されます。

計画: プロンプトを分析し、依存関係を特定して、一連のツール呼び出しを策定します。
検証: 提案されたツール呼び出しを、システム制約、安全ポリシー、必要なパラメータに照らして確認します。
実行: ツール呼び出しを発行し、実行フィードバックをモニタリングします。

組み込みの思考は、レスポンステキストで <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 万トークンのコンテキストウィンドウをサポートしていますが、長いコンテキストシーケンスではノイズ、レイテンシ、コンテキストの劣化が発生する可能性があります。ワーキングメモリの衛生状態を維持することで、長時間実行されるエージェントの精度を維持できます。

コンテキストハイジーンの戦略

長時間実行されるエージェントでコンテキストを管理するには、次の戦略を使用します。

サブエージェントの委任: コード分析やログ検索などの分離されたサブタスクを、有効期間の短いサブエージェントに委任し、合成された要約のみをメインコンテキストに返します。
状態の要約: マルチターンの履歴を定期的に要約し、一時的なデバッグログを破棄して、重要な事実を保持します。
メモリファイル: 会話履歴全体をコンテキストに保持するのではなく、構造化された状態、プロジェクトの制約、運用コンテキストを 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"
}

自動化されたエラー回復と再試行ループ

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.

次のステップ

Google Cloud コンソールまたは IDE チャットでインタラクティブなプロンプトを作成するには、Gemini in Google Cloudにより適したプロンプトを作成するをご覧ください。
Gemini の責任ある AI に関する原則の詳細については、Gemini と責任ある AI を使用したGoogle Cloud をご覧ください。
データプライバシーとガバナンスの詳細については、 Google Cloud の Gemini プロダクトがデータを使用する方法をご覧ください。

エージェント型 AI のシステム指示とプロンプト エンジニアリング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。