如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

异步工具调用

应用程序在后台运行工具时,模型可以继续工作。

通过异步工具调用,模型可以在调用工具后继续工作,无需等待该工具返回结果。您可以提前发起耗时的查询,让模型先回答请求中不依赖查询结果的部分,再由应用程序在获得结果后将其返回。

异步工具的工作原理

常规函数调用会让模型暂停当前轮次,等待工具响应。在函数工具或自定义工具的定义中设置 async: true 后,模型就可以在发起调用后继续工作,无需等到应用程序返回输出。

工具仍由您的应用程序执行。异步工具不会将工具的执行交给 OpenAI,也不会代您管理后台作业。

这与后台模式不同。后台模式会异步生成响应,而异步工具调用让模型在您的应用程序运行工具时继续工作。

作业完成后,请在后续的 Responses 请求中包含其输出。使用 API 为原始调用提供的 call_id 将结果与对应的调用匹配:

工具类型 调用项 输出项
函数工具 function_call function_call_output
自定义工具 custom_tool_call custom_tool_call_output

调用异步工具

在工具定义中添加 async: true。response.output 中对应的调用项会包含 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)

同一条响应可以同时包含异步调用和回答。如果作业完成前对话又进行了其他轮次,请更新 latest_response_id,以便从最新响应继续,同时保留原始工具调用的 call_id。

使用流式传输时,您可以在收到完整的调用项后立即启动作业,同时继续读取响应,无需等到整个响应结束。

添加等待工具

等待工具让模型自行决定何时需要等待尚未返回的结果。例如,模型可以发起两个价格查询,先处理不依赖查询结果的工作,等到要比较价格时再等待结果。

为每个异步工具添加 task_handle 参数。模型为每次调用分配一个句柄,您的应用程序将该句柄与 API 提供的原始 call_id 和正在运行的作业绑定。在整个对话中,每次调用都必须使用唯一的句柄。即使任务已经完成,或再次发起相同的查询,也不能复用句柄。

将等待工具定义为普通的同步函数:省略 async 或将其设为 false。该工具的模式和行为由您的应用程序定义。wait_for_tasks 并非 Responses 的内置工具。

在请求的 tools 数组中使用以下定义:

[
  {
    "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
    }
  }
]

注册每个作业

先注册并启动每个作业,再处理依赖这些作业的等待调用。这些调用可能在同一条响应中一起到达,也可能分布在多条响应中。以下示例输出项包含两次启动作业的调用,以及一次依赖这两个作业的等待调用:

[
  {
    "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\"]}"
  }
]

应用程序的注册表将每个句柄与其原始调用和正在运行的作业绑定:

任务句柄 原始调用 ID 作业
widget_price_1 call_widget 查询 WIDGET 的价格
gadget_price_1 call_gadget 查询 GADGET 的价格

请在整个对话期间保留注册表,以免复用已完成任务的句柄。

先返回结果,再返回等待状态

在注册表中查找请求指定的句柄,仅等待对应的作业。先使用每个新完成作业的原始 call_id 分别返回结果,再使用等待调用自身的 call_id 返回状态。按此顺序返回,模型恢复工作时就能获取这些结果。

例如,您可以在下一个请求的 input 数组中发送以下输出项。价格仅为示例:

[
  {
    "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\"]}"
  }
]

将 previous_response_id 设为最新响应的 ID,并在用于继续对话的请求中包含工具和指令。您的应用程序也可以在获得结果时直接返回,无需调用等待工具。仅当模型的下一步依赖尚未返回的结果时,才使用等待工具。

添加向用户提问的工具

异步工具可以向用户提问,同时让模型继续处理不依赖回答的工作。例如,模型可以先询问报告的读者是谁,在用户回答期间收集资料,再根据回答调整报告内容。

定义一个设置了 async: true 的函数,用于请用户补充信息或说明偏好。您的应用程序负责显示问题、接收回答,并将回答作为工具结果返回。该工具的模式和行为由您的应用程序定义。request_user_input_async 并非 Responses 的内置工具。

将以下定义添加到请求的 tools 数组中,与 wait_for_tasks 一起使用:

{
  "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
  }
}

显示问题

收到完整的调用项后,先注册该问题的 task_handle 和原始 call_id,再向用户显示问题。以下示例输出项询问报告的目标读者:

{
  "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\"}"
}

在等待工具使用的同一注册表中,将问题保持为待回答状态。在用户回答期间,继续读取模型的响应。请勿在显示问题后就返回确认消息并结束工具调用。该调用的结果应为用户的回答。

返回用户的回答

收到用户回复后,使用该问题的原始 call_id 返回回答。例如,在下一个请求的 input 数组中包含以下输出项:

[
  {
    "type": "function_call_output",
    "call_id": "call_audience",
    "output": "{\"task_handle\":\"report_audience_1\",\"answer\":\"Executives\"}"
  }
]

将 previous_response_id 设为最新响应的 ID,并在用于继续对话的请求中包含工具和指令。如果模型调用了 wait_for_tasks 来等待 report_audience_1,请先返回回答,再返回等待状态,具体做法见等待工具示例。

异步执行不会让响应一直保持打开状态直到用户回复。请指示模型继续处理不依赖回答的工作,等收到回答后再执行需要该回答的步骤。如果您的应用程序允许用户关闭问题,或支持为问题设置超时,请在问题被关闭或超时时返回明确表示未收到回答的结果,以便模型决定下一步如何处理。

兼容性

GPT-6 Astra 及后续模型支持异步工具调用。

异步执行适用于由您的应用程序运行的函数工具和自定义工具,不适用于托管的内置工具。请直接调用工具,不要为程序化工具调用配置异步工具。

在多智能体模式下,请勿将异步工具与并行工具调用结合使用。