Systemanweisungen und Prompt Engineering für agentische KI

Wenn Sie autonome KI-Agenten erstellen möchten, die in der Produktion aufGoogle Cloudzuverlässig und sicher funktionieren, können Sie strukturierte Systemanweisungen, explizite Toolschemas, Grenzen für die Argumentation, Human-in-the-Loop-Sicherheitskontrollen (HITL) und Kontext-Hygiene kombinieren. Im Gegensatz zu interaktiven Chatbots, die auf einfachen Eingabe-Ausgabe-Prompts basieren, führen agentische Systeme mit Gemini mehrstufige Planungen durch, rufen externe APIs auf, überwachen das Ausführungsfeedback und behalten den Arbeitsspeicher über Multi-Turn-Workflows hinweg bei.

In diesem Dokument werden Architekturmuster und Prompt-Engineering-Verfahren für die Entwicklung autonomer Agenten beschrieben. Tipps zum Schreiben interaktiver Prompts für Gemini Cloud Assist oder den IDE-Chat finden Sie unter Bessere Prompts für Gemini in Google Cloudschreiben.

Systemanweisungen

In agentischen Architekturen verwenden Sie Systemanweisungen, um die grundlegende Identität, Regeln und Berechtigungen des KI-Agenten zu definieren. Im Gegensatz zu Standard-Nutzeraufforderungen, die sich bei jeder Runde ändern, definieren Sie Systemanweisungen einmal und übergeben sie konsistent über alle Ausführungsrunden hinweg.

Systemanweisungen definieren Folgendes:

  • Grundlegende Identität und Rolle: Definieren Sie die Persona und die Hauptfunktion des KI-Agenten, z. B. „Sie sind ein Datenbankadministrator-Agent“.
  • Verhaltensregeln: Legen Sie betriebliche Einschränkungen, Sicherheitsgrenzen und Anforderungen an das Ausgabeformat fest, z. B. „Führe niemals einen Schreibvorgang ohne menschliche Genehmigung aus“ oder „Gib Ergebnisse als JSON zurück“.
  • Richtlinien für Toolaufrufe: Definieren Sie Regeln für die Toolauswahl, die Reihenfolge und Wiederholungsversuche.

Im Beispiel im nächsten Abschnitt werden diese jeweils in einem eigenen XML-Tag gruppiert: <role>, <rules> und <tool_usage>.

Systemanweisungen dürfen keine dynamischen Laufzeiteingaben wie Nutzerfragen, Dateiinhalte oder Protokolle zur Toolausführung enthalten. Behalten Sie diese dynamischen Werte in den Inhaltsnutzlasten bei, die während der Ausführungsturns gesendet werden.

Systemanweisungen mit XML-Tags strukturieren

Wenn Sie Systemanweisungen mit einer XML-Struktur formatieren, kann das Modell die verschiedenen Arten von Anleitungen genau segmentieren.

XML-Tags sind keine fest codierte Funktion der Gemini API. Stattdessen sind sie eine Prompt-Engineering-Konvention. Da Gemini-Modelle mit strukturiertem Code und Webseiten trainiert werden, parsen sie XML-Tags, um Anweisungstypen zu trennen und eine Abweichung von Anweisungen über mehrere Sitzungen hinweg zu verhindern.

Wenn Sie Ihre Systemanweisung an das SDK oder die API übergeben, sollten Sie den gesamten Anweisungsblock nicht in ein äußeres Tag wie <system_instruction> einschließen. Die API verarbeitet den gesamten String bereits als Systemanweisung. Verwenden Sie stattdessen einzelne Tags innerhalb des Blocks, um Anweisungen zu gruppieren:

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

Wenn Sie Anweisungen mit XML-Tags wie <role>, <rules> und <tool_usage> trennen, behandelt das Modell jeden Block als separate Kategorie von Anleitungen.

Gängige XML-Tags für Systemanweisungen

Gemini kann zwar alle benutzerdefinierten XML-Tags parsen, die zu Ihrer Domain passen, aber die Verwendung einer Reihe gängiger Tags sorgt für konsistente Anweisungen und erleichtert die Verwaltung über mehrere Agenten hinweg.

In der folgenden Tabelle sind Beispiel-Tags aufgeführt, mit denen Sie Systemanweisungen strukturieren können. Tag-Namen sind Konventionen, sodass Sie sie entsprechend Ihrem Agent umbenennen können. In der Anleitung für CX Agent Studio wird beispielsweise <constraints> für die Art von Anleitung verwendet, die in diesem Dokument in <rules> platziert wird.

Tag Beschreibung
<role> Definiert die Kernidentität, die Persona und die Hauptfunktion des KI-Agenten.
<rules> Listet Einschränkungen, Formatierungsregeln und Sicherheitsgrenzen auf.
<tool_usage> Beschreibt Richtlinien für die Auswahl und den Aufruf von Tools.
<example> Enthält ein Few-Shot-Beispiel, das eine erwartete Eingabe und Ausgabe zeigt. Verwenden Sie ein Tag pro Beispiel.

Weitere Informationen und Prompt-Muster finden Sie in den folgenden Ressourcen:

Best Practices für die Definition von Tools und Funktionen

In agentischen Systemen verwenden Sie Tools und Funktionsaufrufe, um KI-Agenten die Möglichkeit zu geben, mit APIs, Datenbanken und Mikrodiensten von Google Cloud zu interagieren. Da das Modell die Ausführung von clientseitigem Code anfordert, indem es von Ihnen definierte Schemas abgleicht, ist es wichtig, klare, eindeutige Tooldeklarationen bereitzustellen, um Aufruffehler zu vermeiden.

Prinzipien des Schemadesigns

Beachten Sie beim Definieren von Toolschemas die folgenden Grundsätze:

  • Explizite Typisierung verwenden: Geben Sie für jeden Parameter in OpenAPI- oder JSON-Schemas genaue Datentypen wie string, integer, boolean, array oder object an.
  • Aussagekräftige Beschreibungen bereitstellen: Erläutern Sie Formatanforderungen, Einschränkungen und gültige Bereiche für jeden Parameter, anstatt sich nur auf Feldnamen zu verlassen.
  • Erforderliche Felder deklarieren: Füllen Sie das Array required in JSON-Schemas aus, damit das Modell keine null-Werte übergibt oder Argumente für Pflichtfelder weglässt.
  • Werte mit Enums einschränken: Verwenden Sie enum-Werte für Felder mit festen gültigen Eingaben, z. B. Umgebungsnamen oder Log-Schweregrade.

Beispiel für ein Schema für eine Funktionsdeklaration

Im folgenden Beispiel wird eine Funktionsdeklaration mit einem JSON-Schema für ein Tool definiert, das ein Google Kubernetes Engine-Deployment (GKE) neu startet:

{
  "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"]
  }
}

Budgetbegrenzung für Reasoning und Thinking

Um interne Schlussfolgerungen zu ziehen, bevor sie in komplexen Workflows aktiv werden, verwenden Agenten die Thinking-Funktionen von Gemini mit dem Parameter thinking_config. Mit dieser Konfiguration können Agenten Plan-Verify-Execute-Schleifen ausführen, um Aktionen zu validieren, bevor Tools aufgerufen werden.

Plan-Verify-Execute-Schleifen implementieren

Eine Plan-Verify-Execute-Schleife besteht aus den folgenden Phasen:

  1. Planen: Den Prompt analysieren, Abhängigkeiten identifizieren und eine Abfolge von Toolaufrufen formulieren.
  2. Prüfen: Vorgeschlagene Toolaufrufe werden mit Systembeschränkungen, Sicherheitsrichtlinien und erforderlichen Parametern abgeglichen.
  3. Ausführen: Toolaufrufe ausgeben und Ausführungsfeedback beobachten.

Das integrierte Thinking wird in einem internen Kanal ausgeführt, anstatt <thinking>-XML-Tags im Antworttext auszugeben. Wenn Sie include_thoughts=True in thinking_config festlegen, können Sie die Zusammenfassungen der Gedankengänge (part.thought) vor einem Toolaufruf prüfen:

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.

Wenn Sie thinking_config im SDK konfigurieren, legen Sie thinking_level (für Gemini 3-Modelle) oder thinking_budget (für Gemini 2.5-Modelle) fest, um die Tiefe der Argumentation und die Latenz auszugleichen.

Kontextfenster-Hygiene und Arbeitsspeicher

Die Flaggschiff-Gemini-Modelle unterstützen zwar ein Kontextfenster mit 1 Million Tokens, aber lange Kontextsequenzen können zu Rauschen, Latenz und Kontextverschlechterung führen. Durch die Pflege des Arbeitsspeichers wird sichergestellt, dass langlebige KI-Agenten genau bleiben.

Strategien für die Kontexthygiene

Verwenden Sie die folgenden Strategien, um den Kontext in langlebigen Agenten zu verwalten:

  • Delegierung an Sub-Agenten: Isolierte Unteraufgaben wie Codeanalyse oder Logsuche werden an kurzlebige Sub-Agenten delegiert, die nur zusammengefasste Ergebnisse an den Hauptkontext zurückgeben.
  • Zustandszusammenfassung: Der Verlauf von Multi-Turn-Unterhaltungen wird regelmäßig zusammengefasst. Dabei werden temporäre Debugging-Logs verworfen und wichtige Fakten beibehalten.
  • Memory-Dateien: Speichern Sie strukturierten Status, Projektbeschränkungen und operativen Kontext in externen Markdown-Dateien wie GOALS.md und MEMORY.md, anstatt den gesamten Rohverlauf von Unterhaltungen im Kontext zu behalten.

Human-in-the-Loop-Prüfpunkte (HITL)

Autonome Agenten, die in Live- Google Cloud -Umgebungen arbeiten, sollten Genehmigungsprüfpunkte für Vorgänge mit hohem Risiko erzwingen.

Vorgänge mit hohem Risiko, die HITL erfordern

Menschliche Genehmigung erforderlich, bevor ein Agent einen der folgenden Vorgänge ausführt:

  • Zugriff und Berechtigungen: Ändern von IAM-Rollen (Identity and Access Management), Gewähren von Dienstkontozugriff oder öffentliches Zugänglichmachen von Ressourcen, z. B. durch Zulassen des nicht authentifizierten Zugriffs auf einen Dienst oder Öffnen von Firewallregeln für alle IP-Adressen.
  • Löschen von Ressourcen: Löschen von Ressourcen wie Cloud SQL-Datenbanken, Cloud Storage-Buckets, Pub/Sub-Themen oder GKE-Knotenpools.
  • Abrechnung und Kontingent: Bereitstellung von kostenintensiven Maschinentypen wie Cloud TPU-Pods oder Multi-GPU-Instanzen oder Erhöhung von Kontingentlimits.

Pausen für die Genehmigung von Designs

Verlassen Sie sich nicht nur auf Prompt-Anweisungen, um destruktive Aktionen zu verhindern. Da Ihr Anwendungscode Tools ausführt, sollten Sie Genehmigungsprüfungen deterministisch in Ihrem Orchestrator erzwingen, indem Sie risikoreiche function_call-Anfragen abfangen, bevor sie ausgeführt werden, und einem menschlichen Prüfer eine Bestätigungsnutzlast präsentieren:

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

Automatisierte Fehlerbehebung und Wiederholungsschleifen

Fehler bei der Toolausführung sind in verteilten Cloud-Umgebungen unvermeidlich. Agenten sollten vorübergehende Fehler, PERMISSION_DENIED-Statuscodes und Fehler bei der Schemavalidierung selbstständig verarbeiten.

Architektur für Fehlerfeedback

Wenn ein Toolaufruf einen Fehler zurückgibt, geben Sie die Rohfehlerausgabe zusammen mit einer Anleitung für einen erneuten Versuch an den Kontext des Agenten zurück, anstatt sofort abzubrechen:

  • Schemaabweichungen: Wenn ein Parameterformat ungültig ist, geben Sie den Schemafehler an das Modell zurück, damit es die Tool-Argumente korrigieren kann.
  • Fehler „Berechtigung verweigert“: Weisen Sie den Agenten an, die erforderlichen IAM-Berechtigungen zu prüfen oder auf schreibgeschützte Diagnosetools zurückzugreifen.
  • Ratenbegrenzungen und Drosselung: Behandeln Sie vorübergehende 429-Fehler mit exponentiellem Backoff in Ihrem Clientcode und geben Sie dauerhafte Kontingentfehler an das Modell zurück, damit es seinen Plan anpassen kann.

Wenn Sie Funktionsaufrufe verwenden, geben Sie strukturierte Fehlerdetails in einem FunctionResponse-Teil zurück (wobei der Inhalt und die Thought-Signaturen des vorherigen Modell-Turns beibehalten werden) und nicht als Rohtext:

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

Beispiel für ein Codeschema vor und nach der Änderung

Der folgende Vergleich zeigt den Wechsel von einem herkömmlichen, unstrukturierten Text-Prompt zu einer agentischen Systemanweisung mit strukturierten JSON-Tool-Schemas unter Verwendung des Google Gen AI SDK.

Veralteter unstrukturierter Text-Prompt

Im folgenden Beispiel wird ein Shell-Befehl in einen unstrukturierten Text-Prompt eingebettet, was zu halluzinierten Toolaufrufen oder fehlenden Parametern führen kann:

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

Systemanweisung und Tool-Definitionsschema für agentische Systeme

Im folgenden Beispiel wird die Systemanweisung vom Nutzer-Prompt getrennt und ein explizites Funktionsschema deklariert:

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.

Nächste Schritte