Verwenden Sie Elicitation mit Ihrem Gateway AgentCore
Elicitation ist eine MCP-Funktion, die es einem MCP-Server ermöglicht, während eines Tool-Aufrufs zusätzliche Informationen vom Client anzufordern. Wenn ein Tool eine Benutzerbestätigung, Authentifizierung oder zusätzliche Eingaben benötigt, um fortzufahren, sendet der Server eine Abrufanforderung zurück an den Client. AgentCore Das Gateway leitet Auslöseanfragen von MCP-Serverzielen an Ihre Clients weiter und ersetzt die Anfrage durch eine vom Gateway generierte Kennung. id
Voraussetzungen
Um Elicitation mit Ihrem Gateway verwenden zu können, benötigen Sie:
-
Sitzungen aktiviert — Für Elicitation ist Sitzungsunterstützung erforderlich. Siehe Verwenden von MCP-Sitzungen mit Ihrem Gateway.
-
Antwort-Streaming aktiviert — Elicitation-Anfragen werden während einer offenen Verbindung als Server-Sent Event-Chunks (SSE) gesendet. In Ihren
streamingConfiguration.enableResponseStreamingGateways auftrueeingestellt.protocolConfiguration.mcp -
MCP-Serverzieltyp — Die Erfassung wird nur für MCP-Serverziele unterstützt. Die Abfrage stammt vom MCP-Server und wird über das Gateway an den Client weitergeleitet.
-
Der Client deklariert die Abruffunktion — Der Client muss während der Anfrage angeben, dass das Gateway die Abrufanforderungen weiterleiten kann.
initialize
Unterstützte Erhebungsmodi
AgentCore Gateway unterstützt drei in der MCP-Spezifikation definierte Auslösemodi:
| Mode | Description |
|---|---|
|
Formularmodus |
Der Server sendet ein strukturiertes Formular mit Feldern, die der Kunde ausfüllen kann. Wird zum Sammeln von Benutzerbestätigungen, Einstellungen oder Eingabedaten verwendet. Die Anfrage bleibt geöffnet, während auf die Antwort gewartet wird. |
|
URL-Modus (anforderungsbasiert) |
Der Server sendet eine URL, die der Benutzer aufrufen muss, um eine Aktion abzuschließen (normalerweise Authentifizierung). Die Anfrage bleibt geöffnet, während auf den Abschluss der Aktion gewartet wird. |
|
URL-Modus (ausnahmenbasiert) |
Der Server gibt eine URL aus, die eine URL |
Aushandlung von Fähigkeiten
Das Gateway deklariert einem MCP-Serverziel nur dann Unterstützung für Abrufe, wenn:
-
Der Client hat während angegeben, dass die Abfrage unterstützt wird.
initialize -
Die MCP-Protokollversion unterstützt den Elicitation-Modus —
formfür den Modus ist eine Version oder höher erforderlich, für dieurlModi ist eine Version2025-03-26oder höher erforderlich.2025-11-25 -
Das Gateway entspricht den vom Client deklarierten spezifischen Abruffunktionen (Form, URL oder beides).
Abfragefluss im Formularmodus
-
Der Client sendet eine
tools/callAnfrage mit demMcp-Session-IdHeader. -
Das Gateway leitet den Tool-Aufruf an das MCP-Serverziel weiter.
-
Das Ziel öffnet einen SSE-Stream und sendet als erstes
elicitation/createEreignis eine Anfrage. -
Das Gateway leitet die
elicitation/createAnfrage im SSE-Stream an den Client weiter und ersetzt die Anfrageid. -
Der Client präsentiert dem Benutzer das Formular und sammelt die Antwort.
-
Der Client sendet eine neue Anfrage mit der Auslösungsantwort (Aktion:
acceptoderdecline) und verwendet dieselbe.Mcp-Session-Id -
Das Gateway leitet die Antwort an das MCP-Serverziel weiter.
-
Das Ziel bestätigt dies mit HTTP 202 Accepted.
-
Das Ziel schließt den Tool-Aufruf ab und sendet das Endergebnis im ursprünglichen SSE-Stream.
-
Gateway leitet das Endergebnis an den Client weiter und schließt den Stream.
Auslöseablauf im URL-Modus (ausnahmenbasiert)
-
Der Client sendet eine
tools/callAnfrage mit dem Header.Mcp-Session-Id -
Das Gateway leitet den Tool-Aufruf an das MCP-Serverziel weiter.
-
Das Ziel gibt
URLElicitationRequiredErrorals JSON-RPC Fehler ein aus, das die URL und eine Auslöse-ID enthält. -
Das Gateway leitet das
URLElicitationRequiredErroran den Client weiter und ersetzt die Anfrage.id -
Der Client leitet den Benutzer zur angegebenen URL weiter, um die Aktion abzuschließen (normalerweise OAuth-Authentifizierung).
-
Nachdem der Benutzer die Aktion abgeschlossen hat, wiederholt der Client die ursprüngliche Anfrage.
tools/call -
Gateway leitet den Wiederholungsversuch an das Ziel weiter. Das Ziel schließt den Tool-Aufruf ab, da die URL-Abfrage abgeschlossen wurde.
-
Gateway leitet das endgültige Tool-Ergebnis an den Client weiter.
Parallele Werkzeugabrufe mit Elicitationen
Ein Client kann innerhalb derselben Sitzung mehrere tools/call Anfragen initiieren, auch wenn noch eine Anfrage aussteht. Jede Anfrage wird unabhängig anhand ihrer Daten nachverfolgt. id Beim Senden einer Antwortantwort muss der Client dieselbe Antwort, die vom Gateway gesendet wurdeid, in die Anfrage aufnehmen. elicitation/create
Anleitung für Entwickler von MCP-Servern
Wichtig
MCP-Serverziele, die Exicitation-Anfragen senden, sollten Exicitation-Aufrufe in Try-Catch-Blöcke packen und den Fall behandeln, dass der Client die Auslösung nicht unterstützt. Wenn der Client des Gateways keine Auslösefähigkeit deklariert hat, deklariert das Gateway sie nicht gegenüber dem Ziel. Wenn das Ziel trotzdem eine Exicitation sendet, gibt das Gateway einen Fehler -32601 (Methode nicht gefunden) an das Ziel zurück.
Server sollten einen Fallback-Pfad implementieren (z. B. Standardwerte verwenden oder den Vorgang überspringen), wenn die Auslösung nicht verfügbar ist.
Fehlerbehandlung
| Szenario | Fehler | Description |
|---|---|---|
|
Der Client sendet eine Abfrageantwort, wenn keine Abfrage aussteht |
JSON-RPC |
Für diese Sitzung wurde kein passendes Ergebnis gefunden. |
|
Der Client sendet eine Antwortantwort mit einer |
JSON-RPC |
Die |
|
Verbindungsabbrüche zwischen Gateway und MCP-Serverziel |
JSON-RPC Fehler bei DependencyFailedException |
Der Kunde sollte die ursprüngliche Tool-Call-Anfrage erneut versuchen. |
|
Verbindungsabbrüche zwischen Client und Gateway |
N/A |
Die ausstehende Abfrage wurde bereinigt. Der Client sollte den Toolaufruf erneut versuchen. |
|
Der MCP-Server sendet eine Anfrage, aber das Gateway hat keine Unterstützung angegeben |
JSON-RPC |
Zum MCP-Serverziel zurückgekehrt. Siehe Problembehandlung. |
Fehlerbehebung
Fehler: „Fehler beim Aufrufen des Tools 'sample_tool': Methode nicht gefunden:" elicitation/create
Dieser Fehler tritt auf, wenn ein MCP-Serverziel eine Abrufanforderung sendet, der Client des Gateways währenddessen jedoch keine Abruffunktion deklariert hat. initialize Das Gateway gibt einen Fehler -32601 (Methode nicht gefunden) an das Ziel zurück, und das Ziel gibt dies möglicherweise als Fehler bei der Ausführung des Tools an den Client zurück.
Um dies zu lösen:
-
Wenn Sie der MCP-Serverentwickler sind: Fügen Sie eine Fehlerbehandlung zu Ihren Elicitation-Aufrufen hinzu. Implementieren Sie einen Fallback-Pfad, wenn die Auslösung nicht unterstützt wird:
try: result = await context.session.create_elicitation( message="Confirm this action?", requested_schema={"type": "object", "properties": {"confirm": {"type": "boolean"}}} ) except Exception as e: # Fallback when client doesn't support elicitation logger.warning(f"Elicitation not supported: {e}") result = default_action() -
Wenn Sie der Gateway-Client-Entwickler sind: Stellen Sie sicher, dass Ihr Client in den folgenden Fällen die Möglichkeit zur Datenabfrage deklariert:
initialize{ "capabilities": { "elicitation": { "form": {}, "url": {} } } }
Codebeispiele
Beispiel für den Formularmodus
Im Formularmodus sendet der Server ein strukturiertes Schema, das der Client ausfüllen kann. Die Anfrage bleibt geöffnet, während auf die Antwort gewartet wird.
Beispiel
Beispiel für den URL-Modus
Im URL-Modus sendet der Server eine URL, die der Benutzer aufrufen muss, um eine Aktion abzuschließen (normalerweise OAuth-Authentifizierung). Die Anfrage bleibt geöffnet, während darauf gewartet wird, dass der Benutzer die Aktion an der URL abschließt.