A2A Protocol

Implementing A2A Agents with ADK: Complete Development Guide

deutschEnglishfrançaisहिंदी日本語한국어中文
MILO•
Share
ADK
Implementing A2A Agents with ADK: Complete Development Guide

Inhaltsverzeichnis

  1. Überblick über ADK und A2A-Protokoll
  2. Umgebungseinrichtung und Abhängigkeitsinstallation
  3. Projektstrukturdesign
  4. A2A-serverseitige Agentenentwicklung
  5. A2A-clientseitige Agentenentwicklung
  6. Agentenkonfiguration und Metadaten
  7. A2A-Server-Start und -Test
  8. Web-UI-Integrationstest
  9. Detaillierte Erklärung des A2A-Kommunikationsflusses

Überblick über ADK und A2A-Protokoll

Was sind ADK und A2A?

ADK (Agent Development Kit) ist ein von Google entwickeltes Framework für die Entwicklung intelligenter Agenten, während A2A (Agent2Agent Protocol) ein standardisiertes Inter-Agenten-Kommunikationsprotokoll ist. Das ADK-Framework integriert umfassende Unterstützung für A2A-Agenten und bietet Kernkomponenten wie RemoteA2aAgent, die es Entwicklern ermöglichen:

  • 🔗 Nahtlose Verbindung: Standardisierte Kommunikation zwischen verteilten Agenten implementieren
  • 🚀 Schnelle Entwicklung: Komplexe Agentensysteme schnell mit einfachen APIs erstellen
  • 🔄 Protokollstandardisierung: A2A-Protokollspezifikationen befolgen, um Interoperabilität sicherzustellen
  • 🎯 Intelligentes Routing: Nachrichtenrouting und Formatkonvertierung automatisch handhaben
  • 📊 Beobachtbarkeit: Integrierte Logging- und Überwachungsfähigkeiten

Wichtiger Hinweis: ADK ist ein Entwicklungsframework, A2A ist ein Kommunikationsprotokoll. ADK enthält die Implementierung des A2A-Protokolls, wodurch Entwickler leicht intelligente Agentensysteme erstellen können, die Agent2Agent-Kommunikation unterstützen. Dieser Leitfaden zeigt, wie die A2A-Funktionalität innerhalb des ADK-Frameworks verwendet wird.

Hauptvorteile der A2A-Funktionalität in ADK

  1. Verteilte Architektur: Unterstützt die Bereitstellung von Agenten auf verschiedenen Servern und Umgebungen, die über das A2A-Protokoll kommunizieren
  2. Standardisiertes Protokoll: Befolgt A2A-Kommunikationsprotokollspezifikationen und gewährleistet plattformübergreifende Kompatibilität
  3. Sofort einsatzbereit: ADK bietet umfassende CLI-Tools und Web-UI mit integrierter A2A-Unterstützung
  4. Hohe Erweiterbarkeit: Unterstützt benutzerdefinierte Tools und komplexe Geschäftslogik, kompatibel mit dem A2A-Ökosystem
  5. Produktionsbereit: Sicherheits- und Zuverlässigkeitsgarantien auf Unternehmensebene

Umgebungseinrichtung und Abhängigkeitsinstallation

Systemanforderungen

  • Python: 3.10 oder höher
  • Betriebssystem: Linux, macOS oder Windows
  • API-Schlüssel: Gemini API-Schlüssel (für LLM-Funktionalität)

Schritt 1: Projektverzeichnis erstellen

# Projekt-Root-Verzeichnis erstellen
mkdir adk-a2a-demo
cd adk-a2a-demo

# Virtuelle Umgebung erstellen
python -m venv .venv

# Virtuelle Umgebung aktivieren
# Linux/macOS:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

Schritt 2: ADK-Abhängigkeiten installieren (mit A2A-Unterstützung)

# ADK-Kernpaket installieren (mit A2A-Protokollunterstützung)
pip install google-adk[a2a]>=1.6.1

# Installation überprüfen
adk --version

Schritt 3: Umgebungsvariablen konfigurieren

# .env-Datei erstellen
echo "GOOGLE_API_KEY=your_gemini_api_key_here" > .env

# Umgebungsvariable setzen (temporär)
export GOOGLE_API_KEY="your_gemini_api_key_here"

Projektstrukturdesign

Empfohlene ADK-basierte A2A-Projektstruktur

adk-a2a-demo/
├── .env                    # Umgebungsvariablenkonfiguration
├── requirements.txt        # Python-Abhängigkeiten
├── __init__.py            # Hauptprojektinitialisierung
├── agent.py               # A2A-Client-Agent (RemoteA2aAgent)
├── remote_a2a/            # A2A-serverseitige Agentenverzeichnis
│   └── facts_agent/       # Spezifische Agentenimplementierung
│       ├── __init__.py    # Agentenpaketinitialisierung
│       ├── agent.py       # Agentenkernlogik
│       └── agent.json     # A2A-Agentenmetadatenkonfiguration
└── README.md              # Projektdokumentation

Grundlegende Projektstruktur erstellen

# Erforderliche Verzeichnisse und Dateien erstellen
mkdir -p remote_a2a/facts_agent
touch __init__.py agent.py
touch remote_a2a/facts_agent/__init__.py
touch remote_a2a/facts_agent/agent.py
touch remote_a2a/facts_agent/agent.json
touch requirements.txt

A2A-serverseitige Agentenentwicklung

Schritt 1: Serverseitige Agentenimplementierung erstellen

Der serverseitige Agent ist die Hauptkomponente, die tatsächlich die Geschäftslogik ausführt. Implementierung in remote_a2a/facts_agent/agent.py:

# remote_a2a/facts_agent/agent.py

from google.adk import Agent
from google.adk.tools import google_search

# Serverseitigen Agenten definieren
root_agent = Agent(
    # Eindeutige Agentenkennung
    name="facts_agent",
    
    # Zu verwendendes großes Sprachmodell
    model="gemini-2.0-flash",
    
    # Beschreibung der Agentenfähigkeiten
    description="Ein Agent, der interessante Fakten bereitstellt.",
    
    # Agentenverhaltensanweisungen
    instruction=(
        "Sie sind ein hilfreicher Agent, der interessante Fakten bereitstellen kann. "
        "Verwenden Sie die Google-Suche, um genaue und aktuelle Informationen zu finden. "
        "Geben Sie immer Quellen für Ihre Fakten an."
    ),
    
    # Liste verfügbarer Tools
    tools=[google_search],
)

Schritt 2: Agentenpaketinitialisierung konfigurieren

In remote_a2a/facts_agent/__init__.py:

# remote_a2a/facts_agent/__init__.py

# Agentenimplementierung importieren, damit sie von ADK entdeckt wird
from . import agent

Schritt 3: Analyse der Hauptfunktionalitäten des serverseitigen Agenten

# Erklärung der Hauptkomponenten des Agenten

# 1. Name (name)
# - Muss eindeutig sein, wird zur Identifizierung des Agenten im A2A-Netzwerk verwendet
# - Empfohlen, beschreibende Namen zu verwenden

# 2. Modell (model)
# - Spezifiziert das zu verwendende große Sprachmodell
# - Unterstützt Gemini-Serie-Modelle

# 3. Beschreibung (description)
# - Kurze Beschreibung der Agentenfähigkeiten
# - Wird anderen Agenten während der Agentenerkennung angezeigt

# 4. Anweisung (instruction)
# - Detaillierte Verhaltensführung
# - Definiert Agentenpersönlichkeit und Antwortstil

# 5. Tools (tools)
# - Externe Tools, die der Agent aufrufen kann
# - Wie Suche, Berechnung, API-Aufrufe usw.

A2A-clientseitige Agentenentwicklung

Schritt 1: Clientseitigen Agenten erstellen

Der clientseitige Agent verwendet RemoteA2aAgent, um sich mit entfernten Diensten zu verbinden. Implementierung in agent.py:

# agent.py

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# Entfernten A2A-Client-Agenten definieren
root_agent = RemoteA2aAgent(
    # Client-Agentenname
    name="facts_agent",
    
    # Fähigkeitsbeschreibung
    description="Ein Agent, der interessante Fakten bereitstellt.",
    
    # Entfernte Agentenkarten-URL
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
)

Schritt 2: Detaillierte RemoteA2aAgent-Konfiguration

# Erweiterte Konfigurationsbeispiel
root_agent = RemoteA2aAgent(
    name="facts_agent",
    description="Ein Agent, der interessante Fakten bereitstellt.",
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
    
    # Optionale Konfiguration
    timeout=300.0,          # HTTP-Timeout (Sekunden)
    httpx_client=None,      # Benutzerdefinierter HTTP-Client
)

Schritt 3: Funktionsprinzip des clientseitigen Agenten

  1. Agentenerkennung: Entfernte Agenteninformationen über agent_card-URL abrufen
  2. Verbindungsaufbau: HTTP-Verbindung zum entfernten A2A-Server erstellen
  3. Nachrichtentransformation: Lokale Ereignisse in A2A-Protokollnachrichten umwandeln
  4. Entfernte Aufrufe: Anfragen an entfernte Agenten senden
  5. Antwortverarbeitung: Antworten von entfernten Agenten empfangen und umwandeln

Agentenkonfiguration und Metadaten

Schritt 1: Agentenkonfigurationsdatei erstellen

Agentenmetadaten in remote_a2a/facts_agent/agent.json definieren:

{
  "name": "facts_agent",
  "description": "Ein Agent, der interessante Fakten bereitstellt.",
  "url": "http://localhost:8001/a2a/facts_agent",
  "version": "1.0.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "capabilities": {
    "streaming": true,
    "functions": true
  },
  "skills": [
    {
      "id": "give_facts",
      "name": "Interessante Fakten",
      "description": "Bietet interessante Fakten zu verschiedenen Themen mit Google-Suche.",
      "tags": ["Information", "Fakten", "Wissen", "Suche", "Google"],
      "examples": [
        "Erzählen Sie mir einen interessanten Fakt über New York City.",
        "Teilen Sie etwas Faszinierendes über Quantenphysik mit.",
        "Was ist ein ungewöhnlicher Fakt über das Meeresleben?"
      ]
    }
  ]
}

Schritt 2: Erklärung der Konfigurationsfelder

{
  // Grundinformationen
  "name": "Eindeutige Agentenkennung",
  "description": "Kurze Beschreibung der Agentenfähigkeiten",
  "url": "A2A-Service-Endpunkt-URL",
  "version": "Versionsnummer (semantische Versionierung)",
  
  // Ein-/Ausgabemodi
  "defaultInputModes": ["Unterstützte Eingabeformate"],
  "defaultOutputModes": ["Unterstützte Ausgabeformate"],
  
  // Agentenfähigkeiten
  "capabilities": {
    "streaming": "Ob Streaming-Antwort unterstützt wird",
    "functions": "Ob Funktionsaufrufe unterstützt werden"
  },
  
  // Fähigkeitsdefinitionen
  "skills": [
    {
      "id": "Eindeutige Fähigkeitskennung",
      "name": "Fähigkeitsanzeigename",
      "description": "Detaillierte Fähigkeitsbeschreibung",
      "tags": ["Tag1", "Tag2"],
      "examples": ["Verwendungsbeispiel 1", "Verwendungsbeispiel 2"]
    }
  ]
}

Schritt 3: Abhängigkeitsdateien erstellen

In requirements.txt:

google-adk[a2a]>=1.6.1

In __init__.py:

# Projektinitialisierungsdatei
from . import agent

A2A-Server-Start und -Test

Schritt 1: A2A-Server starten

# Sicherstellen, dass Sie im Projekt-Root-Verzeichnis sind und die virtuelle Umgebung aktiviert ist
source .venv/bin/activate

# A2A-Server starten
adk api_server --a2a --port 8001 remote_a2a

# Erwartete Ausgabe:
# INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
# INFO:     A2A endpoints enabled for agents: facts_agent

Schritt 2: A2A-Endpunkte überprüfen

# Agentenerkennung-Endpunkt testen
curl http://localhost:8001/a2a/facts_agent/.well-known/agent.json

# Sollte Agentenkonfigurations-JSON zurückgeben

Schritt 3: A2A-Server-Architekturanalyse

Nach dem Start des A2A-Servers erstellt er die folgenden Endpunkte:

  1. Agentenerkennung-Endpunkt: /.well-known/agent.json

    • Bietet Agentenmetadaten und Fähigkeitsinformationen
    • Wird für automatische Agentenerkennung und -konfiguration verwendet

  2. Nachrichtenverarbeitungs-Endpunkt: /a2a/{agent_name}

    • Empfängt Nachrichten von anderen Agenten
    • Verarbeitet A2A-Protokollanfragen

  3. Gesundheitsprüfungs-Endpunkt: /health

    • Serverstatusüberwachung
    • Load-Balancer-Gesundheitsprüfung

Web-UI-Integrationstest

Schritt 1: ADK-Webserver starten

In einem neuen Terminalfenster:

# Virtuelle Umgebung aktivieren
source .venv/bin/activate

# Web-UI-Server starten
adk web .

# Erwartete Ausgabe:
# INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO:     Available agents: facts_agent

Schritt 2: Web-UI-Testprozess

  1. Web-UI-Zugriff: http://localhost:8000 im Browser öffnen

  2. Agentenauswahl: facts_agent aus dem Dropdown-Menü auswählen

  3. Gesprächstest: Testnachricht eingeben, zum Beispiel:

    "Erzählen Sie mir einen interessanten Fakt über künstliche Intelligenz"

  4. Antwortbeobachtung: Überprüfen, ob der Agent korrekt antwortet und das Google-Suchtool verwendet

Schritt 3: Testfall-Beispiele

# Testfall 1: Grundlegende Faktenfrage
Eingabe: Was ist ein interessanter Fakt über die Chinesische Mauer?
Erwartet: Interessante Fakten über die Chinesische Mauer mit Suchquellen zurückgeben

# Testfall 2: Wissenschaftliche Wissensfrage
Eingabe: Teilen Sie etwas Faszinierendes über schwarze Löcher mit.
Erwartet: Wissenschaftliche Fakten über schwarze Löcher zurückgeben

# Testfall 3: Aktuelle Ereignisfrage
Eingabe: Was ist eine kürzliche Entdeckung in der Weltraumforschung?
Erwartet: Neueste Weltraumforschungsentdeckungen zurückgeben

Detaillierte Erklärung des A2A-Kommunikationsflusses

Vollständiges A2A-Kommunikationssequenzdiagramm

sequenceDiagram
    participant User as Benutzer
    participant WebUI as ADK Web UI<br/>(localhost:8000)
    participant Client as Client-Agent<br/>(RemoteA2aAgent)
    participant A2AServer as A2A-Server<br/>(localhost:8001)
    participant Agent as Server-Agent<br/>(facts_agent)
    participant LLM as Gemini LLM
    participant Search as Google-Suche

    User->>WebUI: 1. Fragenachricht eingeben
    WebUI->>Client: 2. Client-Agent aufrufen
    
    Note over Client: 3. Agenteninitialisierung prüfen
    Client->>A2AServer: 4. GET /.well-known/agent.json
    A2AServer-->>Client: 5. Agentenkonfiguration zurückgeben
    
    Note over Client: 6. A2A-Nachricht erstellen
    Client->>A2AServer: 7. POST /a2a/facts_agent<br/>A2A-Nachricht senden
    
    A2AServer->>Agent: 8. In internes Ereignis umwandeln
    Agent->>LLM: 9. Prompt senden
    LLM-->>Agent: 10. Antwort zurückgeben (mit Tool-Aufruf)
    
    Agent->>Search: 11. Google-Suche ausführen
    Search-->>Agent: 12. Suchergebnisse zurückgeben
    
    Agent->>LLM: 13. Suchergebnisse integrieren
    LLM-->>Agent: 14. Endgültige Antwort generieren
    
    Agent-->>A2AServer: 15. Verarbeitungsergebnis zurückgeben
    A2AServer-->>Client: 16. A2A-Antwort zurückgeben
    
    Note over Client: 17. In internes Ereignis umwandeln
    Client-->>WebUI: 18. Antwort zurückgeben
    WebUI-->>User: 19. Endgültiges Ergebnis anzeigen

Analyse der wichtigsten Kommunikationsschritte

1. Agentenerkennung-Phase (Schritte 4-5)

GET http://localhost:8001/a2a/facts_agent/.well-known/agent.json

Antwort:
{
  "name": "facts_agent",
  "url": "http://localhost:8001/a2a/facts_agent",
  "skills": [...]
}

2. Nachrichtensendung-Phase (Schritt 7)

POST http://localhost:8001/a2a/facts_agent
Content-Type: application/json

{
  "id": "uuid-123",
  "params": {
    "message": {
      "messageId": "msg-456",
      "parts": [{"text": "Erzählen Sie mir einen Fakt über KI"}],
      "role": "user"
    }
  }
}

3. Antwort-Rückgabe-Phase (Schritt 16)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "messageId": "response-789",
    "parts": [{"text": "Hier ist ein interessanter KI-Fakt..."}],
    "role": "agent"
  }
}

Zusammenfassung

Durch diesen Leitfaden haben Sie gelernt, wie Sie das A2A-Protokoll mit dem ADK-Framework implementieren, um ein vollständiges Agent-zu-Agent-Kommunikationssystem zu erstellen. Die wichtigsten Lernpunkte sind:

🎯 Kernfähigkeiten

  • ✅ ADK A2A-Umgebungseinrichtung: Entwicklungsumgebung von Grund auf konfigurieren
  • ✅ A2A-serverseitige Agentenentwicklung: Intelligente Agenten mit realer Funktionalität mit ADK erstellen
  • ✅ A2A-clientseitige Agentenentwicklung: Entfernte Agentenverbindung über RemoteA2aAgent implementieren
  • ✅ A2A-Protokollverständnis: Tiefes Verständnis des Agent2Agent-Kommunikationsprotokolls
  • ✅ ADK Web-UI-Test: End-to-End-Test mit der von ADK bereitgestellten Web-UI

🚀 Technische Vorteile

  • Standardisierung: Standardisierte Agentenkommunikation basierend auf A2A-Protokoll
  • Verteilt: ADK unterstützt serverübergreifende A2A-Agentenbereitstellung
  • Skalierbar: Einfach neue Funktionen hinzuzufügen und mit dem A2A-Ökosystem zu integrieren
  • Produktionsbereit: Stabilität und Sicherheit auf Unternehmensebene

🔮 Nächste Schritte

  • Mehr ADK-Tools und A2A-Integrationsoptionen erkunden
  • Multi-A2A-Agenten-Kollaborationssysteme erstellen
  • Benutzerdefinierte A2A-Protokollerweiterungen implementieren
  • ADK A2A-Lösungen in Produktionsumgebungen bereitstellen

ADKs A2A-Implementierung bietet eine leistungsstarke Grundlage für den Aufbau intelligenter Agentensysteme der nächsten Generation und macht die Agentenkollaboration einfach und effizient. Beginnen Sie Ihre ADK A2A-Entwicklungsreise!

Referenzressourcen

Schlüsselwörter: A2A ADK, Agent Development Kit, A2A-Protokoll, Agentenentwicklung, intelligente Agentenkommunikation, Google ADK, Agentenprotokoll, verteiltes Agentensystem, RemoteA2aAgent, Gemini API