Bei einem asynchronen Tool-Aufruf kann das Modell weiterarbeiten, ohne auf das Ergebnis zu warten. So kann es zeitaufwendige Abfragen frühzeitig starten und unabhängige Teile einer Anfrage beantworten. Deine Anwendung liefert die Ergebnisse, sobald sie vorliegen.
So funktionieren asynchrone Tools
Bei einem normalen Funktionsaufruf wartet das Modell auf die Antwort des Tools, bevor es weiterarbeitet. Setze async: true in der Definition einer Funktion oder eines benutzerdefinierten Tools. So kann das Modell nach dem Aufruf weiterarbeiten, noch bevor deine Anwendung die Ausgabe zurückgibt.
Deine Anwendung führt das Tool weiterhin selbst aus. Asynchrone Tools verlagern die Ausführung nicht zu OpenAI und übernehmen auch nicht die Verwaltung deiner Hintergrundjobs.
Im Hintergrundmodus läuft die Generierung der Antwort asynchron. Bei einem asynchronen Tool-Aufruf hingegen arbeitet das Modell weiter, während deine Anwendung das Tool ausführt.
Sobald ein Job abgeschlossen ist, sende seine Ausgabe in einer späteren Anfrage an die Responses API. Ordne das Ergebnis anhand der ursprünglichen call_id der API dem zugehörigen Aufruf zu.
| Tool-Typ | Aufrufelement | Ausgabeelement |
|---|---|---|
| Funktion | function_call |
function_call_output |
| Benutzerdefiniert | custom_tool_call |
custom_tool_call_output |
Ein asynchrones Tool aufrufen
Ergänze die Tool-Definition um async: true. Die zugehörigen Aufrufelemente in response.output enthalten dann async: true.
import json
from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI
from openai.types.responses import FunctionToolParam
def get_weather(city):
# Demo data. Replace this function with your weather service.
weather = {
"Paris": {
"city": "Paris",
"temperature_c": 22,
"condition": "Clear",
"source": "demo weather snapshot",
}
}
return weather[city]
worker = ThreadPoolExecutor()
def main():
client = OpenAI()
model = "gpt-6-astra"
tools: list[FunctionToolParam] = [
{
"type": "function",
"name": "get_weather",
"description": "Read the demo weather snapshot for a city.",
"async": True,
"strict": True,
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
"additionalProperties": False,
},
},
]
instructions = (
"Start the weather lookup and answer the independent packing "
"question without waiting. Use the actual tool result when it "
"arrives; never invent it. Identify the weather as demo data."
)
response = client.responses.create(
model=model,
tools=tools,
instructions=instructions,
input=(
"Check the demo weather in Paris. Meanwhile, "
"list three essentials for any city trip."
),
)
call = next(item for item in response.output if item.type == "function_call")
arguments = json.loads(call.arguments)
if call.name != "get_weather" or arguments != {"city": "Paris"}:
raise ValueError("Expected a weather lookup for Paris")
latest_response_id = response.id
if call.async_:
job = worker.submit(get_weather, **arguments)
print(response.output_text)
# Independent work or conversation turns can happen here.
# Update latest_response_id after each continuation.
result = job.result()
else:
result = get_weather(**arguments)
response = client.responses.create(
model=model,
tools=tools,
instructions=instructions,
previous_response_id=latest_response_id,
input=[
{
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps(result),
},
],
)
print(response.output_text)
if __name__ == "__main__":
try:
main()
finally:
worker.shutdown(wait=True)Die API-Antwort kann sowohl den asynchronen Aufruf als auch eine Antwort des Modells enthalten. Wenn das Gespräch weitergeht, bevor der Job abgeschlossen ist, aktualisiere latest_response_id, um an die jüngste Antwort anzuknüpfen. Behalte dabei die ursprüngliche call_id des Tool-Aufrufs bei.
Mit Streaming kannst du den Job früher starten. Starte ihn, sobald das vollständige Aufrufelement eintrifft, und lies die Antwort währenddessen weiter ein.
Ein Tool zum Warten hinzufügen
Mit einem solchen Tool kann das Modell selbst entscheiden, wann es ein ausstehendes Ergebnis braucht. Es kann beispielsweise zwei Preisabfragen starten, eine unabhängige Aufgabe bearbeiten und erst dann auf die Ergebnisse warten, wenn es die Preise vergleichen möchte.
Ergänze jedes asynchrone Tool um das Argument task_handle. Das Modell weist jedem Aufruf eine Kennung zu. Deine Anwendung verknüpft diese Kennung mit der ursprünglichen call_id der API und dem laufenden Job. Verwende jede Kennung im gesamten Gespräch nur einmal. Das gilt auch für bereits abgeschlossene Aufgaben und wiederholte Abfragen.
Definiere das Tool zum Warten als gewöhnliche synchrone Funktion. Lass async weg oder setze es auf false. Deine Anwendung legt das Schema und das Verhalten des Tools fest. wait_for_tasks ist kein integriertes Tool der Responses API.
Verwende die folgenden Definitionen im Array tools der Anfrage.
[
{
"type": "function",
"name": "lookup_price",
"async": true,
"description": "Look up a product price in the background. Choose a fresh task_handle unique within this conversation, including completed tasks.",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"sku": { "type": "string" },
"task_handle": { "type": "string" }
},
"required": ["sku", "task_handle"],
"additionalProperties": false
}
},
{
"type": "function",
"name": "wait_for_tasks",
"description": "Wait for selected tasks whose results you need. Pass a nonempty list of distinct task_handles from your earlier async tool calls. Results arrive on their original calls; this tool returns status only. Do not wait again for results that have already arrived.",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"task_handles": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["task_handles"],
"additionalProperties": false
}
}
]
Jeden Job registrieren
Registriere und starte jeden Job, bevor du einen Warteaufruf verarbeitest, der von diesem Job abhängt. Die Aufrufe können zusammen oder in verschiedenen Antworten eintreffen. Die folgenden Ausgabeelemente zeigen zwei Aufrufe, die jeweils einen Job starten, und einen Warteaufruf, der von beiden abhängt.
[
{
"type": "function_call",
"name": "lookup_price",
"async": true,
"call_id": "call_widget",
"arguments": "{\"sku\":\"WIDGET\",\"task_handle\":\"widget_price_1\"}"
},
{
"type": "function_call",
"name": "lookup_price",
"async": true,
"call_id": "call_gadget",
"arguments": "{\"sku\":\"GADGET\",\"task_handle\":\"gadget_price_1\"}"
},
{
"type": "function_call",
"name": "wait_for_tasks",
"call_id": "call_wait",
"arguments": "{\"task_handles\":[\"widget_price_1\",\"gadget_price_1\"]}"
}
]
Deine Anwendung führt ein Verzeichnis, das jede Kennung mit dem ursprünglichen Aufruf und dem laufenden Job verknüpft.
| Aufgabenkennung | Ursprüngliche Aufruf-ID | Job |
|---|---|---|
widget_price_1 |
call_widget |
Preisabfrage für WIDGET |
gadget_price_1 |
call_gadget |
Preisabfrage für GADGET |
Behalte das Verzeichnis während des gesamten Gesprächs bei, damit die Kennung einer abgeschlossenen Aufgabe nicht erneut vergeben wird.
Ergebnisse vor dem Status des Warteaufrufs zurückgeben
Schlage die angeforderten Kennungen im Verzeichnis nach und warte nur auf die zugehörigen Jobs. Gib für jeden neu abgeschlossenen Job das Ergebnis mit der ursprünglichen call_id zurück. Gib anschließend den Status mit der call_id des Warteaufrufs zurück. So liegen dem Modell die Ergebnisse vor, wenn es weiterarbeitet.
Sende beispielsweise die folgenden Ausgabeelemente im Array input der nächsten Anfrage. Die Preise dienen als Beispiel.
[
{
"type": "function_call_output",
"call_id": "call_widget",
"output": "{\"task_handle\":\"widget_price_1\",\"price_cents\":1200,\"currency\":\"USD\"}"
},
{
"type": "function_call_output",
"call_id": "call_gadget",
"output": "{\"task_handle\":\"gadget_price_1\",\"price_cents\":1500,\"currency\":\"USD\"}"
},
{
"type": "function_call_output",
"call_id": "call_wait",
"output": "{\"status\":\"completed\",\"completed_task_handles\":[\"widget_price_1\",\"gadget_price_1\"]}"
}
]
Setze previous_response_id auf die ID der jüngsten Antwort und sende die Tools und Anweisungen in der Folgeanfrage mit. Deine Anwendung kann Ergebnisse auch ohne Warteaufruf liefern, sobald sie vorliegen. Verwende das Tool zum Warten nur, wenn das Modell für seinen nächsten Schritt Ergebnisse braucht, die noch ausstehen.
Ein Tool für Rückfragen hinzufügen
Mit einem asynchronen Tool kann das Modell der Person, die die Anwendung nutzt, eine Frage stellen und währenddessen an unabhängigen Aufgaben weiterarbeiten. Es kann etwa fragen, für wen ein Bericht bestimmt ist, in der Zwischenzeit Fakten zusammentragen und den Bericht anhand der Antwort auf die Zielgruppe zuschneiden.
Definiere eine Funktion mit async: true, um fehlende Informationen oder eine Präferenz zu erfragen. Deine Anwendung zeigt die Frage an, nimmt die Antwort entgegen und gibt sie als Ergebnis des Tool-Aufrufs zurück. Deine Anwendung legt das Schema und das Verhalten des Tools fest. request_user_input_async ist kein integriertes Tool der Responses API.
Füge die folgende Definition im Array tools der Anfrage neben wait_for_tasks ein.
{
"type": "function",
"name": "request_user_input_async",
"async": true,
"description": "Ask the user for missing information or a preference. Choose a fresh task_handle unique within this conversation, including completed tasks. Continue independent work while the answer is pending. Use wait_for_tasks when your next step depends on the answer.",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"question": { "type": "string" },
"task_handle": { "type": "string" }
},
"required": ["question", "task_handle"],
"additionalProperties": false
}
}
Die Frage anzeigen
Sobald das vollständige Aufrufelement eintrifft, registriere den task_handle der Frage und die ursprüngliche call_id. Zeige der Person anschließend die Frage an. Im folgenden Beispiel fragt das Modell nach der Zielgruppe des Berichts.
{
"type": "function_call",
"name": "request_user_input_async",
"async": true,
"call_id": "call_audience",
"arguments": "{\"question\":\"Who is the report for: executives or engineers?\",\"task_handle\":\"report_audience_1\"}"
}
Lass die Frage in demselben Verzeichnis offen, das auch das Tool zum Warten verwendet. Lies die Antwort des Modells weiter ein, während die Person die Frage beantwortet. Eine Bestätigung, dass die Frage angezeigt wurde, darf den Tool-Aufruf nicht abschließen. Sein Ergebnis ist die Antwort der Person.
Die Antwort auf die Frage zurückgeben
Sobald die Person antwortet, sende ihre Antwort mit der ursprünglichen call_id der Frage. Sende beispielsweise das folgende Ausgabeelement im Array input der nächsten Anfrage.
[
{
"type": "function_call_output",
"call_id": "call_audience",
"output": "{\"task_handle\":\"report_audience_1\",\"answer\":\"Executives\"}"
}
]
Setze previous_response_id auf die ID der jüngsten Antwort und sende die Tools und Anweisungen in der Folgeanfrage mit. Wenn das Modell wait_for_tasks für report_audience_1 aufgerufen hat, gib die Antwort vor dem Status des Warteaufrufs zurück, wie im Beispiel für das Tool zum Warten.
Bei der asynchronen Ausführung bleibt die API-Antwort nicht offen, bis die Person antwortet. Weise das Modell an, unabhängige Aufgaben weiterzubearbeiten und zu warten, bevor es einen Schritt ausführt, für den es die Antwort braucht. Wenn deine Anwendung das Schließen der Frage ohne Antwort oder ein Zeitlimit unterstützt, gib in diesen Fällen ausdrücklich als Ergebnis zurück, dass keine Antwort vorliegt. So kann das Modell entscheiden, wie es weiter vorgeht.
Kompatibilität
GPT-6 Astra und spätere Modelle unterstützen asynchrone Tool-Aufrufe.
Die asynchrone Ausführung gilt für Funktionen und benutzerdefinierte Tools, die deine Anwendung ausführt. Für gehostete integrierte Tools gilt sie nicht. Rufe asynchrone Tools direkt auf. Konfiguriere sie nicht für programmgesteuerte Tool-Aufrufe.
Kombiniere im Multi-Agenten-Modus keine asynchronen Tools mit parallelen Tool-Aufrufen.