Instructions système et prompt engineering pour l'IA agentive

Pour créer des agents IA autonomes qui fonctionnent de manière fiable et sécurisée en production surGoogle Cloud, vous pouvez combiner des instructions système structurées, des schémas d'outils explicites, des limites de raisonnement, des contrôles de sécurité human-in-the-loop (avec intervention humaine, HITL) et une hygiène du contexte. Contrairement aux chatbots interactifs qui s'appuient sur des requêtes d'entrée-sortie de base, les systèmes agentiques avec Gemini effectuent une planification en plusieurs étapes, appellent des API externes, surveillent les commentaires d'exécution et conservent une mémoire de travail dans les workflows multitours.

Ce document décrit les modèles d'architecture et les pratiques de prompt engineering pour concevoir des agents autonomes. Si vous cherchez des conseils pour rédiger des prompts interactifs pour Gemini Cloud Assist ou le chat de l'IDE, consultez Rédiger de meilleurs prompts pour Gemini dans Google Cloud.

Instructions système

Dans les architectures agentiques, vous utilisez des instructions système pour définir l'identité, les règles et les autorisations de base de l'agent. Contrairement aux requêtes utilisateur standards qui changent à chaque tour, vous définissez les instructions système une seule fois et les transmettez de manière cohérente à chaque tour d'exécution.

Les instructions système définissent les éléments suivants :

  • Identité et rôle de base : définissez le persona et la fonction principale de l'agent (par exemple, "Vous êtes un agent administrateur de base de données").
  • Règles de comportement : établissez des contraintes opérationnelles, des limites de sécurité et des exigences de format de sortie (par exemple, "N'effectuez jamais d'opération d'écriture sans approbation humaine" ou "Renvoyez les résultats au format JSON").
  • Consignes pour les appels d'outils : définissez des règles de sélection, d'ordre et de nouvelle tentative pour les outils.

L'exemple de la section suivante regroupe chacun de ces éléments dans sa propre balise XML : <role>, <rules> et <tool_usage>.

Les instructions système ne doivent pas contenir d'entrées d'exécution dynamiques, telles que des questions d'utilisateurs, du contenu de fichiers ou des journaux d'exécution d'outils. Conservez ces valeurs dynamiques dans les charges utiles de contenu envoyées lors des tours d'exécution.

Structurer les instructions système avec des balises XML

La mise en forme des instructions système à l'aide d'une structure XML aide le modèle à segmenter avec précision les différents types de conseils.

Les balises XML ne sont pas une fonctionnalité codée en dur de l'API Gemini. Il s'agit plutôt d'une convention de prompt engineering. Comme les modèles Gemini sont entraînés sur du code structuré et des pages Web, ils analysent les balises XML pour séparer les types d'instructions et éviter la dérive des instructions lors des sessions multitours.

Lorsque vous transmettez votre instruction système au SDK ou à l'API, n'encapsulez pas l'intégralité du bloc d'instructions dans une balise externe, telle que <system_instruction>. L'API traite déjà l'intégralité de la chaîne en tant qu'instruction système. Utilisez plutôt des balises individuelles dans le bloc pour regrouper les instructions :

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

Lorsque vous séparez les instructions avec des balises XML telles que <role>, <rules> et <tool_usage>, le modèle traite chaque bloc comme une catégorie distincte d'instructions.

Balises XML courantes pour les instructions système

Bien que Gemini puisse analyser toutes les balises XML personnalisées adaptées à votre domaine, l'utilisation d'un ensemble de balises courantes permet de maintenir la cohérence des instructions et de faciliter leur maintenance entre les agents.

Le tableau suivant présente des exemples de balises que vous pouvez utiliser pour structurer les instructions système. Les noms de tags sont des conventions. Vous pouvez donc les renommer en fonction de votre agent. Par exemple, le guide des instructions de CX Agent Studio utilise <constraints> pour le type de conseils que ce document place dans <rules>.

Tag Description
<role> Définit l'identité, le persona et la fonction principale de l'agent.
<rules> Répertorie les contraintes, les règles de mise en forme et les limites de sécurité.
<tool_usage> Décrit les règles de choix et d'appel des outils.
<example> Contient un exemple few-shot qui montre une entrée et une sortie attendues. Utilisez un tag par exemple.

Pour en savoir plus et découvrir des modèles de prompting, consultez les ressources suivantes :

Bonnes pratiques pour la définition des outils et des fonctions

Dans les systèmes agentiques, vous utilisez des outils et des appels de fonction pour permettre aux agents d'interagir avec les API, les bases de données et les microservices Google Cloud . Étant donné que le modèle demande l'exécution du code côté client en faisant correspondre les schémas que vous définissez, il est essentiel de fournir des déclarations d'outils claires et sans ambiguïté pour éviter les erreurs d'appel.

Principes de conception de schémas

Suivez ces principes lorsque vous définissez des schémas d'outils :

  • Utilisez un typage explicite : spécifiez des types de données précis, tels que string, integer, boolean, array ou object, pour chaque paramètre dans les schémas OpenAPI ou JSON.
  • Fournissez des descriptions pertinentes : expliquez les exigences de format, les contraintes et les plages valides pour chaque paramètre, plutôt que de vous fier uniquement aux noms des champs.
  • Déclarez les champs obligatoires : renseignez le tableau required dans les schémas JSON afin que le modèle ne transmette pas null ni n'omette d'arguments pour les champs obligatoires.
  • Limiter les valeurs avec des énumérations : utilisez des valeurs enum pour les champs avec des entrées valides fixes, comme les noms d'environnement ou les niveaux de gravité des journaux.

Exemple de schéma de déclaration de fonction

L'exemple suivant définit une déclaration de fonction avec un schéma JSON pour un outil qui redémarre un déploiement 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"]
  }
}

Contrôle du budget de raisonnement et de réflexion

Pour effectuer un raisonnement interne avant d'agir dans des workflows complexes, les agents utilisent les capacités de réflexion de Gemini avec le paramètre thinking_config. Cette configuration permet aux agents d'effectuer des boucles de planification, de vérification et d'exécution pour valider les actions avant d'appeler des outils.

Implémenter des boucles de planification, de vérification et d'exécution

Une boucle planifier-vérifier-exécuter se compose des étapes suivantes :

  1. Plan : analyser la requête, identifier les dépendances et formuler une séquence d'appels d'outils.
  2. Vérifier : vérifiez les appels d'outils proposés par rapport aux contraintes du système, aux règles de sécurité et aux paramètres requis.
  3. Exécuter : émettez des appels d'outils et observez les commentaires sur l'exécution.

La réflexion intégrée s'exécute dans un canal interne plutôt que d'émettre des balises XML <thinking> dans le texte de la réponse. Si vous définissez include_thoughts=True dans thinking_config, vous pouvez inspecter les résumés de réflexion (part.thought) avant un appel d'outil :

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.

Lorsque vous configurez thinking_config dans le SDK, définissez thinking_level (pour les modèles Gemini 3) ou thinking_budget (pour les modèles Gemini 2.5) afin d'équilibrer la profondeur de raisonnement et la latence.

Hygiène de la fenêtre de contexte et mémoire de travail

Bien que les modèles Gemini phares soient compatibles avec une fenêtre de contexte d'un million de jetons, les séquences de contexte longues peuvent introduire du bruit, de la latence et une dégradation du contexte. Maintenir l'hygiène de la mémoire de travail permet de s'assurer que les agents de longue durée restent précis.

Stratégies pour l'hygiène du contexte

Utilisez les stratégies suivantes pour gérer le contexte dans les agents de longue durée :

  • Délégation à des sous-agents : déléguez des sous-tâches isolées, telles que l'analyse de code ou la recherche dans les journaux, à des sous-agents éphémères, en ne renvoyant que des résumés synthétisés au contexte principal.
  • Résumé de l'état : résumez régulièrement l'historique multitour, en supprimant les journaux de débogage temporaires et en conservant les faits clés.
  • Fichiers de mémoire : conservez l'état structuré, les contraintes du projet et le contexte opérationnel dans des fichiers Markdown externes, tels que GOALS.md et MEMORY.md, plutôt que de conserver l'intégralité de l'historique des conversations brutes dans le contexte.

Points de contrôle human-in-the-loop ou HITL (avec intervention humaine)

Les agents autonomes opérant dans des environnements de production Google Cloud doivent appliquer des points de contrôle d'approbation pour les opérations à haut risque.

Opérations à haut risque nécessitant une intervention humaine

Exiger une approbation humaine avant qu'un agent n'effectue l'une des opérations suivantes :

  • Accès et autorisations : modification des rôles IAM (Identity and Access Management), octroi de l'accès au compte de service ou mise à disposition publique des ressources, par exemple en autorisant l'accès non authentifié à un service ou en ouvrant des règles de pare-feu à toutes les adresses IP.
  • Suppression de ressources : suppression de ressources telles que des bases de données Cloud SQL, des buckets Cloud Storage, des sujets Pub/Sub ou des pools de nœuds GKE.
  • Facturation et quota : provisionnement de types de machines coûteux, tels que des pods Cloud TPU ou des instances multi-GPU, ou augmentation des limites de quota.

Pauses d'approbation de conception

Ne vous fiez pas uniquement aux instructions de la requête pour bloquer les actions destructrices. Étant donné que le code de votre application exécute des outils, appliquez des vérifications d'approbation de manière déterministe dans votre orchestrateur en interceptant les requêtes function_call à haut risque avant de les exécuter et en présentant une charge utile de confirmation à un réviseur humain :

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

Correction d'erreur automatisée et boucles de nouvelles tentatives

Les échecs d'exécution des outils sont inévitables dans les environnements cloud distribués. Les agents doivent gérer de manière autonome les erreurs temporaires, les codes d'état PERMISSION_DENIED et les échecs de validation de schéma.

Architecture de feedback sur les erreurs

Lorsqu'un appel d'outil renvoie une erreur, renvoyez la sortie d'erreur brute dans le contexte de l'agent, ainsi que des conseils pour réessayer, plutôt que d'échouer immédiatement :

  • Incompatibilités de schéma : si le format d'un paramètre n'est pas valide, renvoyez l'erreur de schéma au modèle afin qu'il puisse corriger les arguments de l'outil.
  • Erreurs d'autorisation refusée : demandez à l'agent de vérifier les autorisations IAM requises ou de revenir aux outils de diagnostic en lecture seule.
  • Limites de débit et limitation : gérez les erreurs 429 temporaires avec un intervalle exponentiel entre les tentatives dans votre code client, et renvoyez les erreurs de quota persistantes au modèle afin qu'il puisse ajuster son plan.

Lorsque vous utilisez l'appel de fonction, renvoyez les détails de l'erreur structurée dans une partie FunctionResponse (en conservant le contenu et les signatures de pensée du tour de modèle précédent) plutôt que du texte brut :

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

Exemple de schéma de code avant et après

La comparaison suivante illustre le passage d'un ancien prompt textuel non structuré à une instruction système agentique avec des schémas d'outils JSON structurés à l'aide du SDK Google Gen AI.

Ancien prompt textuel non structuré

L'exemple suivant intègre une commande shell dans un prompt textuel non structuré, ce qui peut entraîner des appels d'outils hallucinés ou des paramètres manquants :

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

Schéma de définition des instructions système et des outils de l'agent

L'exemple suivant sépare l'instruction système de la requête utilisateur et déclare un schéma de fonction explicite :

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.

Étapes suivantes