Agent mit Agent CLI und Agent Identity erstellen und bereitstellen

In diesem Leitfaden erfahren Sie, wie Sie einen Agent in der Agent Runtime auf der Gemini Enterprise Agent Platform mit aktivierter Agent Identity erstellen und bereitstellen.

Agent Identity weist Ihrem bereitgestellten Agent eine sichere SPIFFE-Identität zu. Der Agent verwendet diese Identität zur Authentifizierung bei Google Cloud Diensten und zum Abrufen von Anmeldedaten vom Agent Identity-Authentifizierungsmanager.

Hinweis

  1. Aktivieren Sie die APIs Agent Identity API, Agent Platform API, Agent Registry API und App Hub API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen.

    APIs aktivieren

  2. Sie benötigen die Rolle Agent Platform User (roles/aiplatform.user) für Ihr Projekt.

Agent erstellen und bereitstellen

Erstellen Sie einen Beispielagenten mit google-agents-cli und stellen Sie ihn mit Agent Identity bereit:

  1. Installieren Sie uv und führen Sie dann die Einrichtung von google-agents-cli aus:

    pip install uv
uvx google-agents-cli setup

  2. Erstellen Sie ein Agent-Projekt mit der Prototypvorlage:

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    Ersetzen Sie AGENT_PROJECT durch den Namen für Ihr neues Agent-Projektverzeichnis (z. B. maps-agent).

    Mit diesem Befehl wird die folgende Projektverzeichnisstruktur generiert:

    AGENT_PROJECT/
├── app/                       # Core agent code
│   ├── agent.py               # Main agent logic
│   ├── fast_api_app.py        # Client application logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit and integration tests
├── GEMINI.md                  # Development guide
└── pyproject.toml             # Project dependencies

  3. Benennen Sie den Standardanwendungsordner (app) so um, dass er mit dem Namen Ihres Agent übereinstimmt (AGENT_NAME, z. B. maps_agent). Agent-Namen müssen eine gültige Python-Kennung sein: Sie müssen mit einem Buchstaben beginnen und dürfen nur Buchstaben, Zahlen und Unterstriche enthalten.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. Aktualisieren Sie die Konfigurationsdatei agent.py mit dem neuen Namen:

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  5. Wählen Sie ein zu verwendendes Modell basierend auf seiner regionalen Verfügbarkeit aus. Aktualisieren Sie den Wert für MODEL in agent.py entsprechend dem ausgewählten Modell.

    Problemumgehung für Modelle, die nur in der global Region verfügbar sind

    Wenn Sie ein Modell verwenden möchten, das nur in der global Region verfügbar ist, müssen Sie agent.py so ändern, dass Ihr Agent darauf zugreifen kann.

    1. Fügen Sie die folgenden Importe hinzu:

      from functools import cached_property
from google.genai import Client

    2. Fügen Sie nach den Importen die folgende Unterklasse hinzu:

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. Suchen Sie den folgenden Code:

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      Ändern Sie ihn so, dass er auf die neue abgeleitete Klasse verweist:

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. Aktivieren Sie Agent Identity, indem Sie eine Konfigurationsdatei erstellen:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  7. Erstellen Sie eine requirements.txt-Datei für die Bereitstellungsabhängigkeiten:

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. Prüfen Sie die Projektverzeichnisstruktur:

    AGENT_PROJECT/
├── AGENT_NAME/                 # Agent application folder
│   ├── .agent_engine_config.json # Agent Identity configuration
│   ├── agent.py                  # Main agent logic
│   ├── fast_api_app.py           # Client application logic
│   ├── requirements.txt          # Deployment dependencies
│   └── app_utils/                # App helpers
├── tests/                        # Tests
├── GEMINI.md                     # Development guide
└── pyproject.toml                # Project dependencies

  9. Testen Sie Ihren Agent lokal:

    uv run adk web . --port 8501 --reload_agents

    So prüfen Sie Ihren Agent:

    1. Rufen Sie http://localhost:8501 auf. Wenn Sie Cloud Shell verwenden, klicken Sie alternativ auf den Link, der in der Ausgabe des Webservers angegeben ist.

    2. Senden Sie in der Chatoberfläche eine Testanfrage, um die Antwort zu prüfen.

  10. Beenden Sie den Server mit CTRL+C.

  11. Stellen Sie Ihren Agent unter folgender Adresse bereit Google Cloud:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Google Cloud Projekt ID.

    • LOCATION: Die unterstützte Region, in der Sie den Agent bereitstellen möchten (z. B. us-west1).

    Die Bereitstellung kann einige Minuten dauern. Nach Abschluss der Bereitstellung gibt die CLI eine Bestätigungsnachricht und einen Link zum Playground Ihres Agent in der Google Cloud Console aus.

  12. Rufen Sie die SPIFFE-ID Ihres Agent (Agent Identity) ab:

    1. Rufen Sie in der Google Cloud Console die Bereitstellungen Seite auf.

      Zu Deployments

    2. Suchen Sie die Zeile mit dem bereitgestellten Agent und klicken Sie in der Spalte Identität dieser Zeile auf In die Zwischenablage kopieren , um die SPIFFE-ID Ihres Agent in die Zwischenablage zu kopieren. Die Identität sieht in etwa so aus: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Nächste Schritte