Petunjuk sistem dan rekayasa perintah untuk AI agentic

Untuk membangun agen AI otonom yang beroperasi dengan andal dan aman dalam produksi di Google Cloud, Anda dapat menggabungkan petunjuk sistem terstruktur, skema alat eksplisit, batasan penalaran, kontrol keamanan human-in-the-loop (HITL), dan kebersihan konteks. Tidak seperti chatbot interaktif yang mengandalkan perintah input-output dasar, sistem agentic dengan Gemini melakukan perencanaan multilangkah, memanggil API eksternal, memantau masukan eksekusi, dan mempertahankan memori kerja di seluruh alur kerja multi-giliran.

Dokumen ini menjelaskan pola arsitektur dan praktik rekayasa perintah untuk mendesain agen otonom. Jika Anda mencari tips menulis perintah interaktif untuk Gemini Cloud Assist atau chat IDE, lihat Menulis perintah yang lebih baik untuk Gemini di Google Cloud.

Petunjuk sistem

Dalam arsitektur agentic, Anda menggunakan petunjuk sistem untuk menentukan identitas, aturan, dan izin dasar agen. Tidak seperti perintah pengguna standar yang berubah di setiap giliran, Anda menentukan petunjuk sistem sekali dan meneruskannya secara konsisten di seluruh giliran eksekusi.

System instructions menentukan hal berikut:

  • Identitas dan peran dasar: Tentukan persona dan fungsi utama agen—misalnya, "Anda adalah agen administrator database".
  • Aturan perilaku: Tetapkan batasan operasional, batasan keamanan, dan persyaratan format output—misalnya, "Jangan pernah melakukan operasi tulis tanpa persetujuan manusia" atau "Tampilkan hasil sebagai JSON".
  • Panduan panggilan alat: Tentukan aturan pemilihan, pengurutan, dan percobaan ulang alat.

Contoh di bagian berikutnya mengelompokkan masing-masing ke dalam tag XML-nya sendiri: <role>, <rules>, dan <tool_usage>.

Petunjuk sistem tidak boleh berisi input runtime dinamis, seperti pertanyaan pengguna, konten file, atau log eksekusi alat. Pertahankan nilai dinamis ini dalam payload konten yang dikirim selama giliran eksekusi.

Menyusun petunjuk sistem dengan tag XML

Memformat petunjuk sistem menggunakan struktur XML membantu model mengelompokkan berbagai jenis panduan secara akurat.

Tag XML bukanlah fitur hardcode Gemini API. Namun, peran tersebut adalah konvensi rekayasa perintah. Karena dilatih dengan kode dan halaman web terstruktur, model Gemini mengurai tag XML untuk memisahkan jenis petunjuk dan mencegah pergeseran petunjuk di seluruh sesi multi-turn.

Saat Anda meneruskan petunjuk sistem ke SDK atau API, jangan gabungkan seluruh blok petunjuk dalam tag luar, seperti <system_instruction>. API sudah memproses seluruh string sebagai petunjuk sistem. Sebagai gantinya, gunakan tag individual di dalam blok untuk mengelompokkan petunjuk:

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

Saat Anda memisahkan petunjuk dengan tag XML seperti <role>, <rules>, dan <tool_usage>, model akan memperlakukan setiap blok sebagai kategori panduan yang berbeda.

Tag XML umum untuk petunjuk sistem

Meskipun Gemini dapat mengurai tag XML kustom apa pun yang sesuai dengan domain Anda, penggunaan serangkaian tag umum membantu menjaga petunjuk tetap konsisten dan lebih mudah dikelola di seluruh agen.

Tabel berikut mencantumkan contoh tag yang dapat Anda gunakan untuk menyusun petunjuk sistem. Nama tag adalah konvensi, jadi Anda dapat mengganti namanya agar sesuai dengan agen Anda. Misalnya, panduan petunjuk CX Agent Studio menggunakan <constraints> untuk jenis panduan yang ditempatkan dokumen ini di <rules>.

Tag Deskripsi
<role> Menentukan identitas inti, persona, dan fungsi utama agen.
<rules> Mencantumkan batasan, aturan pemformatan, dan batasan keamanan.
<tool_usage> Menguraikan kebijakan untuk memilih dan memanggil alat.
<example> Berisi contoh few-shot yang menunjukkan input dan output yang diharapkan. Gunakan satu tag per contoh.

Untuk mengetahui detail dan pola perintah selengkapnya, lihat referensi berikut:

Praktik terbaik definisi alat dan fungsi

Dalam sistem agen, Anda menggunakan alat dan panggilan fungsi untuk memberi agen kemampuan berinteraksi dengan API, database, dan microservice Google Cloud . Karena model meminta eksekusi kode sisi klien dengan mencocokkan skema yang Anda tentukan, memberikan deklarasi alat yang jelas dan tidak ambigu sangat penting untuk mencegah error pemanggilan.

Prinsip desain skema

Ikuti prinsip-prinsip berikut saat Anda menentukan skema alat:

  • Gunakan pengetikan eksplisit: Tentukan jenis data yang tepat, seperti string, integer, boolean, array, atau object, untuk setiap parameter dalam skema OpenAPI atau JSON.
  • Berikan deskripsi yang bermakna: Jelaskan persyaratan format, batasan, dan rentang yang valid untuk setiap parameter, bukan hanya mengandalkan nama kolom.
  • Deklarasikan kolom yang diperlukan: Isi array required dalam skema JSON agar model tidak meneruskan null atau menghilangkan argumen untuk kolom wajib.
  • Batasi nilai dengan enum: Gunakan nilai enum untuk kolom dengan input valid yang tetap, seperti nama lingkungan atau tingkat keparahan log.

Contoh skema deklarasi fungsi

Contoh berikut menentukan deklarasi fungsi dengan skema JSON untuk alat yang memulai ulang deployment 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"]
  }
}

Kontrol anggaran penalaran dan pemikiran

Untuk melakukan penalaran internal sebelum mengambil tindakan dalam alur kerja yang kompleks, agen menggunakan kemampuan penalaran Gemini dengan parameter thinking_config. Konfigurasi ini memungkinkan agen melakukan loop rencana-verifikasi-eksekusi untuk memvalidasi tindakan sebelum memanggil alat.

Menerapkan loop rencana-verifikasi-eksekusi

Loop rencana-verifikasi-eksekusi terdiri dari tahap-tahap berikut:

  1. Merencanakan: Menganalisis perintah, mengidentifikasi dependensi, dan merumuskan urutan panggilan alat.
  2. Verifikasi: Periksa panggilan alat yang diusulkan terhadap batasan sistem, kebijakan keamanan, dan parameter yang diperlukan.
  3. Execute: Mengeluarkan panggilan alat dan mengamati masukan eksekusi.

Penalaran bawaan berjalan di saluran internal, bukan memunculkan tag XML <thinking> dalam teks respons. Jika Anda menetapkan include_thoughts=True di thinking_config, Anda dapat memeriksa ringkasan pemikiran (part.thought) sebelum panggilan alat:

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.

Saat Anda mengonfigurasi thinking_config di SDK, tetapkan thinking_level (untuk model Gemini 3) atau thinking_budget (untuk model Gemini 2.5) guna menyeimbangkan kedalaman penalaran dan latensi.

Kebersihan jendela konteks dan memori kerja

Meskipun model Gemini unggulan mendukung jendela konteks 1 juta token, urutan konteks yang panjang dapat menimbulkan derau, latensi, dan penurunan kualitas konteks. Menjaga kebersihan memori kerja membantu memastikan bahwa agen yang berjalan lama tetap akurat.

Strategi untuk menjaga kebersihan konteks

Gunakan strategi berikut untuk mengelola konteks dalam agen yang berjalan lama:

  • Delegasi sub-agen: Delegasikan subtugas yang terisolasi, seperti analisis kode atau penelusuran log, ke sub-agen berumur pendek, yang hanya menampilkan ringkasan yang disintesis ke konteks utama.
  • Ringkasan status: Meringkas histori multi-giliran secara berkala, membuang log debug sementara, dan mempertahankan fakta penting.
  • File memori: Pertahankan status terstruktur, batasan project, dan konteks operasional dalam file Markdown eksternal, seperti GOALS.md dan MEMORY.md, daripada menyimpan seluruh histori percakapan mentah dalam konteks.

Checkpoint human-in-the-loop (HITL)

Agen otonom yang beroperasi di lingkungan Google Cloud live harus menerapkan checkpoint persetujuan untuk operasi berisiko tinggi.

Operasi berisiko tinggi yang memerlukan HITL

Wajibkan persetujuan manusia sebelum agen melakukan salah satu operasi berikut:

  • Akses dan izin: Mengubah peran Identity and Access Management (IAM), memberikan akses akun layanan, atau membuat resource dapat diakses secara publik, seperti dengan mengizinkan akses yang tidak diautentikasi ke layanan atau membuka aturan firewall ke semua alamat IP.
  • Penghapusan resource: Menghapus resource seperti database Cloud SQL, bucket Cloud Storage, topik Pub/Sub, atau node pool GKE.
  • Penagihan dan kuota: Menyediakan jenis mesin berbiaya tinggi, seperti pod Cloud TPU atau instance multi-GPU, atau menaikkan batas kuota.

Jeda persetujuan desain

Jangan hanya mengandalkan petunjuk perintah untuk membatasi tindakan yang merusak. Karena kode aplikasi Anda mengeksekusi alat, terapkan pemeriksaan persetujuan secara deterministik di orchestrator Anda dengan mencegat permintaan function_call berisiko tinggi sebelum menjalankannya dan menampilkan payload konfirmasi kepada peninjau manual:

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

Pemulihan error otomatis dan loop percobaan ulang

Kegagalan eksekusi alat tidak dapat dihindari di lingkungan cloud terdistribusi. Agen harus menangani error sementara, kode status PERMISSION_DENIED, dan kegagalan validasi skema secara otonom.

Arsitektur masukan error

Jika panggilan alat menampilkan error, masukkan output error mentah kembali ke konteks agen bersama dengan panduan percobaan ulang, bukan langsung gagal:

  • Ketidakcocokan skema: Jika format parameter tidak valid, tampilkan error skema ke model agar model dapat memperbaiki argumen alat.
  • Error izin ditolak: Instruksikan agen untuk memeriksa izin IAM yang diperlukan atau beralih ke alat diagnostik hanya baca.
  • Pembatasan kapasitas dan throttling: Tangani error 429 sementara dengan backoff eksponensial dalam kode klien Anda, dan tampilkan error kuota persisten ke model agar dapat menyesuaikan rencananya.

Saat menggunakan pemanggilan fungsi, tampilkan detail error terstruktur di bagian FunctionResponse (mempertahankan konten dan tanda tangan pemikiran giliran model sebelumnya), bukan teks mentah:

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."
        ),
    },
)

Contoh skema kode sebelum versus sesudah

Perbandingan berikut mengilustrasikan peralihan dari perintah teks lama yang tidak terstruktur ke petunjuk sistem agentic dengan skema alat JSON terstruktur menggunakan Google Gen AI SDK.

Perintah teks tidak terstruktur lama

Contoh berikut menyematkan perintah shell di dalam perintah teks tidak terstruktur, yang dapat menyebabkan panggilan alat yang berhalusinasi atau parameter yang tidak ada:

# 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,
)

Skema definisi alat dan petunjuk sistem agentic

Contoh berikut memisahkan petunjuk sistem dari perintah pengguna dan mendeklarasikan skema fungsi eksplisit:

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.

Langkah berikutnya