Agent mit Agent CLI und Agent Identity erstellen und bereitstellen

In diesem Leitfaden erfahren Sie, wie Sie einen Agenten in 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 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.

    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 einen Beispielagenten mit agents-cli 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 ein neues Agentenprojekt mit der Prototypvorlage:

    agents-cli create AGENT_PROJECT --prototype --yes

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

    Mit diesem Befehl wird die folgende Projektverzeichnisstruktur generiert:

    (Hinweis: Die folgende Struktur 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 mit dem neuen Namen:

    # 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 Befehlszeilenschnittstelle eine Bestätigungsnachricht und einen Link zum Playground Ihres Agenten in der Google Cloud Console aus.

  8. Rufen Sie die SPIFFE-ID Ihres Agenten (Agent Identity) aus 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