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 mit aktivierter Agent Identity erstellen und bereitstellen.

Agent Identity weist Ihrem bereitgestellten Agenten 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 Agent Identity Connector API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen.

    API aktivieren

  2. Achten Sie darauf, dass Sie die Rolle Vertex AI-Nutzer (roles/aiplatform.user) für Ihr Projekt haben.

Agent erstellen und bereitstellen

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

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

    pip install google-agents-cli uv
agents-cli setup

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

    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:

    (Hinweis: Der folgende Baum hebt die relevanten Konfigurationsdateien hervor und stellt möglicherweise nicht alle Dateien in Ihrem Verzeichnis dar.)

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

    mv app AGENT_NAME

    Aktualisieren Sie dann die Konfigurationsdatei agent.py, um den neuen Namen zu berücksichtigen:

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

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

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

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

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

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

    Bestätigen Sie Ihren Agenten lokal:

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

    So validieren Sie Ihren Agenten:

    1. Rufen Sie http://localhost:8501 auf.
    2. Senden Sie in der Chatoberfläche eine Testanfrage, um die Antwort zu prüfen.

  7. Stellen Sie Ihren Agenten 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 Region, in der Sie den Agenten bereitstellen möchten (z. B. us-west1).

    Nach Abschluss der Bereitstellung gibt die CLI eine Bestätigungsnachricht und einen Link zur Playground-Umgebung Ihres Agenten in der Google Cloud Console aus.

  8. Rufen Sie die SPIFFE-ID Ihres Agenten (Agent Identity) in der Google Cloud Console ab:

    1. Rufen Sie in der Google Cloud Console die Seite Agent Platform auf.
    2. Klicken Sie auf den Tab Bereitstellungen und wählen Sie Ihren bereitgestellten Agenten aus.
    3. Kopieren Sie den Wert Agent Identity (z. B. principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Nächste Schritte