A2A-Agenten, die eine Website-API aufrufen

A2A-Agenten ermöglichen es einem KI-System, ein anderes zu finden, ihm eine Aufgabe zu übergeben und ein strukturiertes Ergebnis zu erhalten. Kann ein solcher Agent eine Website-API aufrufen, wird er Teil eines realen Geschäftsprozesses: Er prüft die Verfügbarkeit, erstellt eine Anfrage, berechnet ein Angebot, aktualisiert einen Bestellstatus oder sammelt Daten für einen Bericht.

• A2A - ein Protokoll für die Kommunikation zwischen Agenten
• Website-API - ein kontrollierter Zugang zu Daten und Aktionen
• Agent Card - eine Beschreibung der Fähigkeiten und Verbindungsdaten
• Task - eine Aufgabe mit Status, Ergebnis und Verlauf
• Grundprinzip - der Agent ruft freigegebene Geschäftsoperationen auf, keine beliebigen URLs

Was ist A2A?

A2A, oder Agent2Agent, verbindet unabhängige Agenten. Ein Agent ist der Client, ein anderer veröffentlicht seine Fähigkeiten und bearbeitet Aufgaben. Beide können unterschiedliche Programmiersprachen, Modelle und Infrastrukturen verwenden.

Ein typischer Ablauf:

1. Der Client-Agent erhält eine Anfrage.
2. Er findet über die Agent Card einen geeigneten Remote-Agenten.
3. Er erstellt eine Aufgabe und übergibt den Kontext.
4. Der Remote-Agent ruft die Website-API auf.
5. Das Ergebnis kommt als Nachricht oder Artefakt zurück.

A2A regelt die Kommunikation der Agenten. Die API stellt die Funktionen der Website bereit. Beide Ebenen ergänzen sich, ersetzen sich aber nicht.

Warum braucht ein Agent eine Website-API?

Ohne API ist ein Agent meist auf Text, Dokumentensuche oder fragile UI-Automatisierung beschränkt. Eine API bietet einen stabilen Vertrag und ermöglicht Aktionen ohne simulierte Klicks.

Sinnvolle Operationen sind:

• Produkte, Leistungen und Inhalte suchen;
• Preise, Lieferzeiten oder Tarife berechnen;
• Leads, Anfragen oder Bestellungen erstellen;
• Zahlungs- und Lieferstatus prüfen;
• Profile oder Reservierungen aktualisieren;
• nach der Autorisierung personalisierte Ergebnisse abrufen.

Ein Beratungsagent kann den Website-Agenten zum Beispiel bitten: "Finde einen verfügbaren Tarif für ein Team mit 20 Personen." Der Website-Agent prüft die aktuellen Regeln über die interne API und liefert strukturierte Optionen.

Architektur der Integration

Eine praktische Lösung besteht aus fünf Teilen:

Geben Sie dem Modell kein universelles Tool wie request(url, method, body). Definieren Sie enge Funktionen:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

So lassen sich Rechte, Argumente, Tests und Protokolle besser kontrollieren.

Agent Card und Fähigkeiten

Die Agent Card zeigt einem Client, welche Aufgaben der Agent übernehmen kann. Sie enthält üblicherweise Name, Beschreibung, URL, unterstützte Authentifizierung und eine Liste von Skills.

Eine Skill-Beschreibung sollte konkret sein. "Arbeitet mit der Website" hilft kaum. Besser ist: "Durchsucht den Katalog, berechnet Angebote und erstellt nach Bestätigung eine Anfrage".

Nicht in die Agent Card gehören:

• API-Schlüssel oder interne Tokens;
• private Service-Adressen;
• Details, die das Umgehen der Autorisierung erleichtern;
• Operationen, die externe Clients nicht nutzen dürfen.

Authentifizierung und Rechte

Die A2A-Verbindung und der API-Aufruf können verschiedene Zugangsdaten verwenden. Der Agent weist seine Identität nach, während die API wissen muss, in wessen Namen eine Aktion erfolgt.

Drei verbreitete Varianten:

1. Service-Account - für gemeinsame Daten und Hintergrundprozesse.
2. Delegierter Benutzerzugriff - für Bestellungen, Profile und persönliche Daten.
3. Bestätigte Aktion - der Agent bereitet die Änderung vor, der Benutzer gibt sie frei.

Begrenzen Sie Rechte nach Endpoint, HTTP-Methode, Benutzer und Datentyp. Lesezugriff auf den Katalog darf nicht automatisch das Ändern von Preisen oder Löschen von Bestellungen erlauben.

Sicherheit der Aufrufe

Die wichtigsten Risiken sind manipulierte Anweisungen, ungültige Argumente, Datenlecks und doppelte Ausführung.

Eine Mindestabsicherung umfasst:

• Eingaben nach einem strikten Schema prüfen;
• erlaubte Operationen über eine Allowlist begrenzen;
• Secrets aus Prompts und A2A-Nachrichten heraushalten;
• Idempotency Keys für Erstellen und Bezahlen verwenden;
• Häufigkeit und Kosten von Aufrufen begrenzen;
• finanzielle und irreversible Aktionen bestätigen lassen;
• persönliche Daten und Tokens in Logs maskieren;
• nur benötigte Antwortfelder an den Agenten zurückgeben.

Texte von Benutzern und anderen Agenten sind nicht vertrauenswürdig. Auch eine überzeugende Anweisung in einem Dokument darf die Rechte eines Tools niemals erweitern.

Synchrone und lang laufende Aufgaben

Suche und Berechnung können oft sofort antworten. Import, große Berichte oder Bestellverarbeitung können Minuten dauern. Dafür eignen sich Status wie submitted, working, completed, failed und canceled.

Der Client kann Updates per Event-Stream, Webhook oder Statusabfrage erhalten. Eine erneute Verbindung darf die Geschäftsoperation nicht noch einmal starten.

Fehler und Observability

Der Agent braucht ein verständliches Ergebnis statt eines rohen Stack Trace: vorübergehend nicht verfügbar, ungültiges Argument, Zugriff verweigert oder Bestätigung erforderlich. Interne Details bleiben in geschützten Logs.

Für die Diagnose sollten Sie speichern:

• IDs von Task, Session und Benutzer;
• den Namen des aufgerufenen Tools;
• eine sichere Kopie der Argumente;
• API-Code und Ausführungszeit;
• den Bestätigungsstatus;
• Versionen von Agent und Tool-Schema.

So lassen sich Modellfehler von API-, Netzwerk- und Geschäftsregelfehlern unterscheiden.

Plan für die Einführung

1. Einen Anwendungsfall mit messbarem Nutzen auswählen.
2. Einen engen API-Vertrag und Datenschemata definieren.
3. Separate Tools statt universellem HTTP-Zugriff entwickeln.
4. Authentifizierung, Limits und Audit hinzufügen.
5. Eine Agent Card mit präzisen Skills veröffentlichen.
6. Fehler, Wiederholungen, Abbruch und schädliche Eingaben testen.
7. Mit read-only oder Entwurfsmodus starten.
8. Schreibzugriffe erst nach Prüfung realer Logs erlauben.

Fazit

Ein A2A-Agent mit Zugriff auf die Website-API kann externe KI-Systeme mit realen Geschäftsleistungen verbinden. Eine zuverlässige Integration basiert auf engen Tools, strikten Schemata, begrenzten Rechten, Bestätigungen und Auditierbarkeit, nicht auf unbegrenzter Freiheit des Modells.

Wenn Sie einen A2A-Agenten an Ihre Website-API anbinden möchten - schreiben Sie mir.

Häufig gestellte Fragen

Wie unterscheidet sich A2A von einer normalen REST API?

Eine REST API beschreibt Anwendungsoperationen, A2A dagegen die Kommunikation der Agenten und den Lebenszyklus von Aufgaben. A2A kann REST oder einen anderen Transport nutzen. Der Agent greift anschließend über kontrollierte Tools auf die Website-API zu.

Brauche ich A2A, wenn mein Agent bereits APIs aufrufen kann?

Nicht immer. Für einen internen Agenten kann ein direkter API-Aufruf reichen. A2A ist sinnvoll, wenn unabhängige Agenten einander finden, Aufgaben delegieren und Ergebnisse über ein gemeinsames Protokoll austauschen sollen.

Kann der Agent einen universellen HTTP-Client bekommen?

Technisch ja, in Produktion ist das jedoch riskant. Enge Funktionen mit Allowlist, Schemata und getrennten Rechten lassen sich leichter absichern, testen und auditieren.

Wie verhindere ich doppelte Bestellungen?

Verwenden Sie einen Idempotency Key und speichern Sie die Verbindung zwischen A2A-Task und Geschäftsoperation. Eine Wiederholung mit demselben Schlüssel muss das frühere Ergebnis liefern, statt einen neuen Datensatz anzulegen.

Welche Aktionen brauchen eine Bestätigung?

Zahlungen, Veröffentlichungen, externe Nachrichten, Änderungen persönlicher Daten und andere teure oder irreversible Aktionen sollten bestätigt werden. Suche, Lesen öffentlicher Daten und Entwürfe lassen sich meist automatisieren.