Hooks

Mit Hooks können Sie benutzerdefinierte Skripts oder externe HTTP-Anfragen ausführen, kurz bevor oder nachdem der Agent Code ausführt oder Dateien in seiner Remote-Sandbox ändert. Verwenden Sie Hooks, um den Agent-Loop mit automatisierten Schutzmaßnahmen und Hintergrund-Workflows zu erweitern, z. B.:

  • Sicherheits- und Zugriffsschutzmaßnahmen erzwingen , bevor Shell-Befehle mit hohem Risiko oder eingeschränkte Dateilesevorgänge ausgeführt werden.
  • Datentransformationen in der Datenpipeline automatisieren , direkt nachdem ein Agent Dateien erstellt oder geändert hat.

  • Telemetriedaten für die Unternehmensprüfung streamen , nach der Ausführung des Tools an externe Überwachungssysteme.

Python

import json
from google import genai

client = genai.Client()

hooks_config = {
    "security-gate": {
        "pre_tool_execution": [
            {
                "matcher": "code_execution",
                "hooks": [
                    {
                        "type": "command",
                        "command": "python3 /.agents/hooks-scripts/gate.py",
                        "timeout": 10,
                    }
                ],
            }
        ]
    }
}

gate_script = """#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
cmd = str(data.get("tool_call", {}).get("args", {}))
if "rm -rf" in cmd:
    print(json.dumps({"decision": "deny", "reason": "Destructive command blocked by security gate."}))
else:
    print(json.dumps({"decision": "allow"}))
"""

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Run `rm -rf /tmp/forbidden` using code_execution.",
    tools=[{"type": "code_execution"}],
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/hooks.json",
                "content": json.dumps(hooks_config, indent=2),
            },
            {
                "type": "inline",
                "target": ".agents/hooks-scripts/gate.py",
                "content": gate_script,
            },
        ],
    },
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const hooksConfig = {
    "security-gate": {
        pre_tool_execution: [
            {
                matcher: "code_execution",
                hooks: [
                    {
                        type: "command",
                        command: "python3 /.agents/hooks-scripts/gate.py",
                        timeout: 10,
                    },
                ],
            },
        ],
    },
};

const gateScript = `#!/usr/bin/env python3
import sys, json
data = json.load(sys.stdin)
cmd = str(data.get("tool_call", {}).get("args", {}))
if "rm -rf" in cmd:
    print(json.dumps({"decision": "deny", "reason": "Destructive command blocked by security gate."}))
else:
    print(json.dumps({"decision": "allow"}))
`;

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Run `rm -rf /tmp/forbidden` using code_execution.",
    tools: [{ type: "code_execution" }],
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/hooks.json",
                content: JSON.stringify(hooksConfig, null, 2),
            },
            {
                type: "inline",
                target: ".agents/hooks-scripts/gate.py",
                content: gateScript,
            },
        ],
    },
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-05-2026",
      "input": [{"type": "text", "text": "Run `rm -rf /tmp/forbidden` using code_execution."}],
      "tools": [{"type": "code_execution"}],
      "environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/hooks.json",
                  "content": "{\"security-gate\": {\"pre_tool_execution\": [{\"matcher\": \"code_execution\", \"hooks\": [{\"type\": \"command\", \"command\": \"python3 /.agents/hooks-scripts/gate.py\", \"timeout\": 10}]}]}}"
              },
              {
                  "type": "inline",
                  "target": ".agents/hooks-scripts/gate.py",
                  "content": "#!/usr/bin/env python3\nimport sys, json\ndata = json.load(sys.stdin)\ncmd = str(data.get(\"tool_call\", {}).get(\"args\", {}))\nif \"rm -rf\" in cmd:\n    print(json.dumps({\"decision\": \"deny\", \"reason\": \"Destructive command blocked by security gate.\"}))\nelse:\n    print(json.dumps({\"decision\": \"allow\"}))\n"
              }
          ]
      }
  }'

Unterstützte Lebenszyklusereignisse

Hooks unterstützen zwei Ereignisse in der Sandbox:

Ereignis Auslöser Funktion
pre_tool_execution Kurz bevor ein Tool ausgeführt wird Kann das Tool genehmigen (allow) oder blockieren (deny), bevor es ausgeführt wird. Wenn es blockiert wird, sieht das Modell den Grund für Ihre Ablehnung und passt sich an.
post_tool_execution Kurz nachdem ein Tool beendet wurde Führt Folgeaufgaben aus, z. B. Code formatieren, Unit-Tests ausführen oder Telemetriedaten protokollieren. Abgeschlossene Aktionen können nicht blockiert oder rückgängig gemacht werden.

pre_tool_execution

Wird kurz vor der Ausführung eines Tools ausgelöst. Ihr Skript liest die Details des Toolaufrufs aus stdin und gibt die JSON-Entscheidung (allow oder deny) an stdout aus.

Eingabe-Payload (stdin):

{
  "tool_call": {
    "name": "code_execution",
    "args": {
      "code": "rm -rf /tmp/forbidden",
      "language": "bash"
    }
  },
  "environment_id": "env_xyz789"
}

Ausgabeantwort (stdout):

So genehmigen Sie den Toolaufruf:

{
  "decision": "allow"
}

So blockieren Sie den Toolaufruf und geben Feedback an das Modell zurück:

{
  "decision": "deny",
  "reason": "Destructive command blocked by security gate."
}

Wenn ein Hook einen Befehl ablehnt, wird der Toolaufruf sofort übersprungen. Der Agent sieht direkt in seiner aktuellen Runde ein Fehlerergebnis mit dem Grund für Ihre Ablehnung. Das Modell kann sich dann selbst korrigieren, indem es einen alternativen Befehl auswählt oder die Blockierung dem Nutzer erklärt.

Wenn Ihr Skript nicht erkannte JSON, Nur-Text oder etwas anderes als {"decision": "deny"} ausgibt, behandelt die Laufzeit die Antwort als Genehmigung (allow).

post_tool_execution

Wird kurz nach Abschluss eines Tools ausgelöst. Ihr Skript liest die Ausführungsdetails und den Fehlerstatus aus stdin.

Eingabe-Payload (stdin):

{