Agent mit Agent CLI und Agent Identity erstellen und bereitstellen

In diesem Leitfaden erfahren Sie, wie Sie einen Agenten in der Agent Runtime auf der Gemini Enterprise Agent Platform erstellen und bereitstellen, wenn die Agent Identity aktiviert ist.

Agent Identity weist Ihrem bereitgestellten Agenten eine sichere SPIFFE-Identität zu. Der Agent verwendet diese Identität, um sich bei Google Cloud -Diensten zu authentifizieren und Anmeldedaten vom Authentifizierungsmanager für die Identität von KI-Agenten abzurufen.

Hinweis

  1. Aktivieren Sie die Agent Identity API, die Agent Platform API, die Agent Registry API und die App Hub API, falls sie noch nicht aktiviert sind.

    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.

KI-Agenten erstellen und bereitstellen

Erstellen Sie einen Beispiel-KI-Agenten mit google-agents-cli und stellen Sie ihn mit Agent Identity bereit:

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

    pip install uv
uvx google-agents-cli setup

  2. So erstellen Sie ein Agent-Projekt mit der Prototypvorlage:

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

    Ersetzen Sie AGENT_PROJECT durch den Namen des neuen Agent-Projektverzeichnisses (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 Agenten übereinstimmt (AGENT_NAME, z. B. maps_agent). Agentennamen müssen gültige Python-Kennzeichnungen 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, damit der neue Name berücksichtigt wird:

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

  5. Wählen Sie ein Modell basierend auf seiner regionalen Verfügbarkeit aus. Aktualisieren Sie den Wert für MODEL in agent.py, damit er mit dem ausgewählten Modell übereinstimmt.

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

    Wenn Sie ein Modell verwenden möchten, das nur in der Region global 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 den Verweis auf die neue abgeleitete Klasse:

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

  6. Aktivieren Sie die Agent-Identität, 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. So testen Sie den Agenten lokal:

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

    So validieren Sie Ihren Agent:

    1. Öffnen Sie http://localhost:8501. Wenn Sie Cloud Shell verwenden, können Sie alternativ auf den Link klicken, der in der Ausgabe des Webservers angezeigt wird.

    2. Senden Sie in der Chatoberfläche einen Test-Prompt, um die Antwort zu überprüfen.

  10. Beenden Sie den Server mit CTRL+C.

  11. Stellen Sie Ihren Agent in Google Cloudbereit:

    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 Ausführung gibt die CLI eine Bestätigungsmeldung und einen Link zum Playground Ihres Agents in der Google Cloud -Konsole aus.

  12. SPIFFE-ID Ihres Agent Identity abrufen (Agent Identity):

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

      Zu Deployments

    2. Wenn Sie die SPIFFE-ID Ihres Agenten in die Zwischenablage kopieren möchten, suchen Sie die Zeile, in der sich Ihr bereitgestellter Agent befindet, und klicken Sie in der Spalte Identität dieser Zeile auf  In die Zwischenablage kopieren. Die Identität sieht dann ungefähr so aus: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Nächste Schritte