Agent mit Agent CLI und Agent Identity erstellen und bereitstellen

Mit Agent Identity können Sie eine verwaltete Identität für Agenten bereitstellen, die Sie in der Agent Runtime auf der Gemini Enterprise Agent Platform mit der Agent CLI und dem Agent Development Kit (ADK) erstellen und bereitstellen. Der bereitgestellte Agent kann sich dann beiGoogle Cloud -Diensten authentifizieren und Anmeldedaten vom Agent Identity-Authentifizierungsmanager abrufen, ohne dass eine manuelle Verwaltung der Anmeldedaten erforderlich ist.

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 Inhaberrolle (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 Beispiel-KI-Agenten mit google-agents-cli und stellen Sie ihn mit der Agentenidentität 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 KI-Agentenprojekt mit der Prototypvorlage:

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

    Ersetzen Sie AGENT_PROJECT durch den Namen Ihres 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 dem Namen Ihres KI-Agenten entspricht (AGENT_NAME, z. B. maps_agent). KI-Agentennamen müssen ein gültiger Python-Bezeichner 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, um den neuen Namen zu übernehmen:

    # 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 dem ausgewählten Modell entspricht.

    Problemumgehung 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 ihn so, dass er auf die neue Unterklasse verweist:

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

  6. Aktivieren Sie die Agentenidentitä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. Testen Sie den KI-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, klicken Sie alternativ auf den Link, der von der Webserverausgabe bereitgestellt wird.

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

  10. Beenden Sie den Server mit CTRL+C.

  11. Stellen Sie Ihren KI-Agenten 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 des Vorgangs gibt die Befehlszeile eine Bestätigungsmeldung und einen Link zum Playground Ihres KI-Agenten in der Google Cloud Console aus.

  12. Rufen Sie die SPIFFE-ID (Agentenidentität) Ihres KI-Agenten ab:

    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