Istruzioni di sistema e prompt engineering per l'AI agentica

Per creare agenti AI autonomi che operano in modo affidabile e sicuro in produzione suGoogle Cloud, puoi combinare istruzioni di sistema strutturate, schemi di strumenti espliciti, limiti di ragionamento, controlli di sicurezza human-in-the-loop (HITL) e igiene del contesto. A differenza dei chatbot interattivi che si basano su prompt di input-output di base, i sistemi agentici con Gemini eseguono una pianificazione in più passaggi, richiamano API esterne, monitorano il feedback di esecuzione e mantengono la memoria di lavoro in flussi di lavoro a più turni.

Questo documento descrive i pattern architetturali e le pratiche di prompt engineering per la progettazione di agenti autonomi. Se cerchi suggerimenti su come scrivere prompt interattivi per Gemini Cloud Assist o la chat dell'IDE, consulta Scrivi prompt migliori per Gemini in Google Cloud.

Istruzioni di sistema

Nelle architetture agentiche, utilizzi le istruzioni di sistema per definire l'identità, le regole e le autorizzazioni di base dell'agente. A differenza dei prompt utente standard che cambiano a ogni turno, le istruzioni di sistema vengono definite una sola volta e trasmesse in modo coerente tra i turni di esecuzione.

Le istruzioni di sistema definiscono quanto segue:

  • Identità e ruolo di base: definisci il ruolo e la funzione principale dell'agente, ad esempio "Sei un agente amministratore di database".
  • Regole comportamentali: stabilisci vincoli operativi, limiti di sicurezza e requisiti per il formato di output, ad esempio "Non eseguire mai un'operazione di scrittura senza l'approvazione umana" o "Restituisci i risultati in formato JSON".
  • Linee guida per le chiamate agli strumenti: definisci le regole di selezione, ordinamento e ripetizione degli strumenti.

L'esempio nella sezione successiva raggruppa ciascuno di questi elementi nel proprio tag XML: <role>, <rules> e <tool_usage>.

Le istruzioni di sistema non devono contenere input di runtime dinamici, come domande degli utenti, contenuti dei file o log di esecuzione degli strumenti. Mantieni questi valori dinamici nei payload dei contenuti inviati durante i turni di esecuzione.

Struttura le istruzioni di sistema con i tag XML

La formattazione delle istruzioni di sistema utilizzando una struttura XML aiuta il modello a segmentare con precisione i diversi tipi di indicazioni.

I tag XML non sono una funzionalità impostata come hardcoded dell'API Gemini. Si tratta invece di una convenzione di prompt engineering. Poiché i modelli Gemini sono addestrati su codice strutturato e pagine web, analizzano i tag XML per separare i tipi di istruzioni e impedire la deviazione delle istruzioni nelle sessioni multi-turn.

Quando passi l'istruzione di sistema all'SDK o all'API, non racchiudere l'intero blocco di istruzioni in un tag esterno, come <system_instruction>. L'API elabora già l'intera stringa come istruzione di sistema. Utilizza invece singoli tag all'interno del blocco per raggruppare le istruzioni:

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

Quando separi le istruzioni con tag XML come <role>, <rules> e <tool_usage>, il modello tratta ogni blocco come una categoria distinta di indicazioni.

Tag XML comuni per le istruzioni di sistema

Sebbene Gemini possa analizzare qualsiasi tag XML personalizzato adatto al tuo dominio, l'utilizzo di un insieme di tag comuni aiuta a mantenere le istruzioni coerenti e più facili da gestire tra gli agenti.

La tabella seguente elenca i tag di esempio che puoi utilizzare per strutturare le istruzioni di sistema. I nomi dei tag sono convenzioni, quindi puoi rinominarli in base al tuo agente. Ad esempio, la guida alle istruzioni di CX Agent Studio utilizza <constraints> per il tipo di indicazioni che questo documento inserisce in <rules>.

Tag Descrizione
<role> Definisce l'identità, il ruolo e la funzione principale dell'agente.
<rules> Elenca i vincoli, le regole di formattazione e i limiti di sicurezza.
<tool_usage> Descrive le policy per la scelta e la chiamata degli strumenti.
<example> Contiene un esempio few-shot che mostra un input e un output previsti. Utilizza un tag per esempio.

Per maggiori dettagli e pattern di prompting, consulta le seguenti risorse:

Best practice per la definizione di strumenti e funzioni

Nei sistemi basati su agenti, utilizzi strumenti e chiamate di funzione per concedere agli agenti la possibilità di interagire con API, database e microservizi Google Cloud . Poiché il modello richiede l'esecuzione del codice lato client tramite la corrispondenza degli schemi definiti, è fondamentale fornire dichiarazioni degli strumenti chiare e non ambigue per evitare errori di chiamata.

Principi di progettazione dello schema

Segui questi principi quando definisci gli schemi degli strumenti:

  • Utilizza la digitazione esplicita: specifica tipi di dati precisi, come string, integer, boolean, array o object, per ogni parametro negli schemi OpenAPI o JSON.
  • Fornisci descrizioni significative: spiega i requisiti di formato, i vincoli e gli intervalli validi per ogni parametro, anziché fare affidamento solo sui nomi dei campi.
  • Dichiara i campi obbligatori: compila l'array required negli schemi JSON in modo che il modello non passi null o ometta argomenti per i campi obbligatori.
  • Limita i valori con gli enum: utilizza i valori enum per i campi con input validi fissi, come i nomi degli ambienti o i livelli di gravità dei log.

Esempio di schema di dichiarazione di funzione

L'esempio seguente definisce una dichiarazione di funzione con uno schema JSON per uno strumento che riavvia un deployment di 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"]
  }
}

Controllo del budget di ragionamento e pensiero

Per eseguire un ragionamento interno prima di agire in workflow complessi, gli agenti utilizzano le funzionalità di ragionamento di Gemini con il parametro thinking_config. Questa configurazione consente agli agenti di eseguire cicli di pianificazione, verifica ed esecuzione per convalidare le azioni prima di richiamare gli strumenti.

Implementa i loop di pianificazione, verifica ed esecuzione

Un ciclo di pianificazione, verifica ed esecuzione è costituito dalle seguenti fasi:

  1. Pianificazione: analizza il prompt, identifica le dipendenze e formula una sequenza di chiamate allo strumento.
  2. Verifica: controlla le chiamate agli strumenti proposte rispetto ai vincoli di sistema, alle policy di sicurezza e ai parametri richiesti.
  3. Esecuzione: esegui le chiamate allo strumento e osserva il feedback sull'esecuzione.

Il ragionamento integrato viene eseguito in un canale interno anziché emettere tag XML <thinking> nel testo della risposta. Se imposti include_thoughts=True in thinking_config, puoi esaminare i riepiloghi dei pensieri (part.thought) prima di una chiamata allo strumento:

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.

Quando configuri thinking_config nell'SDK, imposta thinking_level (per i modelli Gemini 3) o thinking_budget (per i modelli Gemini 2.5) per bilanciare la profondità di ragionamento e la latenza.

Igiene della finestra di contesto e memoria di lavoro

Sebbene i modelli Gemini di punta supportino una finestra contestuale di 1 milione di token, le sequenze di contesto lunghe possono introdurre rumore, latenza e degrado del contesto. Mantenere l'igiene della memoria di lavoro aiuta a garantire che gli agenti a esecuzione prolungata rimangano accurati.

Strategie per l'ottimizzazione del contesto

Utilizza le seguenti strategie per gestire il contesto negli agenti con esecuzione prolungata:

  • Delega ai subagenti: delega attività secondarie isolate, come l'analisi del codice o la ricerca nei log, a subagenti di breve durata, restituendo solo riepiloghi sintetizzati al contesto principale.
  • Riassunto dello stato: riassumi periodicamente la cronologia multi-turn, scartando i log di debug temporanei e conservando i fatti chiave.
  • File di memoria: rendi persistente lo stato strutturato, i vincoli del progetto e il contesto operativo in file Markdown esterni, come GOALS.md e MEMORY.md, anziché conservare intere cronologie delle conversazioni non elaborate nel contesto.

Checkpoint human-in-the-loop (HITL)

Gli agenti autonomi che operano in ambienti Google Cloud live devono applicare checkpoint di approvazione per le operazioni ad alto rischio.

Operazioni ad alto rischio che richiedono l'intervento umano (HITL)

Richiedi l'approvazione umana prima che un agente esegua una delle seguenti operazioni:

  • Accesso e autorizzazioni: modifica dei ruoli di Identity and Access Management (IAM), concessione dell'accesso ai account di servizio o accesso pubblico alle risorse, ad esempio consentendo l'accesso non autenticato a un servizio o aprendo le regole del firewall a tutti gli indirizzi IP.
  • Eliminazione di risorse: eliminazione di risorse come database Cloud SQL, bucket Cloud Storage, argomenti Pub/Sub o pool di nodi GKE.
  • Fatturazione e quota: provisioning di tipi di macchine ad alto costo, come pod di Cloud TPU o istanze multi-GPU, o aumento dei limiti di quota.

Progetta le pause di approvazione

Non fare affidamento solo sulle istruzioni del prompt per bloccare le azioni distruttive. Poiché il codice dell'applicazione esegue gli strumenti, applica i controlli di approvazione in modo deterministico nell'orchestratore intercettando le richieste function_call ad alto rischio prima di eseguirle e presentando un payload di conferma a un revisore umano:

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

Correzione degli errori automatizzata e cicli di ripetizione

Gli errori di esecuzione degli strumenti sono inevitabili negli ambienti Distributed Cloud. Gli agenti devono gestire autonomamente gli errori temporanei, i codici di stato PERMISSION_DENIED e gli errori di convalida dello schema.

Architettura del feedback sugli errori

Quando una chiamata allo strumento restituisce un errore, inserisci l'output dell'errore non elaborato nel contesto dell'agente insieme alle indicazioni per i nuovi tentativi, anziché generare un errore immediato:

  • Mancate corrispondenze dello schema: se il formato di un parametro non è valido, restituisci l'errore dello schema al modello in modo che possa correggere gli argomenti dello strumento.
  • Errori di autorizzazione negata: chiedi all'agente di controllare le autorizzazioni IAM richieste o di utilizzare strumenti di diagnostica di sola lettura.
  • Limiti di frequenza e throttling: gestisci gli errori 429 temporanei con il backoff esponenziale nel codice client e restituisci gli errori di quota persistenti al modello in modo che possa modificare il suo piano.

Quando utilizzi la chiamata di funzione, restituisci i dettagli dell'errore strutturati in una parte FunctionResponse (conservando il contenuto e le firme di pensiero del turno precedente del modello) anziché il testo non elaborato:

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

Esempio di schema di codice prima e dopo

Il seguente confronto illustra il passaggio da un prompt testuale non strutturato legacy a un'istruzione di sistema agentica con schemi di strumenti JSON strutturati utilizzando l'SDK Google Gen AI.

Prompt testuale non strutturato legacy

L'esempio seguente incorpora un comando della shell all'interno di un prompt di testo non strutturato, che può causare chiamate allo strumento allucinate o parametri mancanti:

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

Istruzioni di sistema dell'agente e schema di definizione degli strumenti

L'esempio seguente separa l'istruzione di sistema dal prompt dell'utente e dichiara uno schema di funzione esplicito:

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.

Passaggi successivi