GPT-6 Astra Async Tool Calling Python Tutorial: Build Faster Agents
Learn how to use GPT-6 Astra async tool calling in Python, return tool results safely, and coordinate multiple background jobs with task handles.
On this page
A slow database query, test suite, or external API call can leave an AI application waiting even when the model has useful work it could continue doing. GPT-6 Astra changes that pattern with async tool calling: your application can start a tool job, let Astra continue with independent work, and return the result later through the same Responses API conversation.
What GPT-6 Astra async tool calling actually changes
With a normal function tool, the model requests the tool and waits for your application to return its result before the turn can continue. An asynchronous tool adds async: true to the function definition, allowing Astra to continue working after issuing the call while your application executes the job. The important distinction is that OpenAI does not run your background job for you. Your application still owns execution, job tracking, retries, timeouts, authorization, and the final tool result.
This makes async tool calling useful when part of a task is slow but another part does not depend on it. For example, an assistant could start a repository test suite while preparing a deployment checklist. It should not invent the test results or make a decision that requires them; it can continue only with work that is genuinely independent. That separation between independent work and dependent work is the key idea behind the feature.
If you are already building a broader cloud agent, async tools can become another execution pattern inside the agent rather than a replacement for your existing orchestration layer.
What you need before writing the Python code
You need Python, an OpenAI API key, and the current OpenAI Python SDK. GPT-6 Astra is accessed with the gpt-6-astra model name through the Responses API. For tool calling, use Responses rather than treating the feature as a drop-in change to an older Chat Completions tool loop.
- Install or update the OpenAI Python package with
pip install -U openai. - Set your API key in the
OPENAI_API_KEYenvironment variable. - Create an application function that performs the slow operation.
- Expose that function as a strict tool with
async: true. - Return the completed result using the original tool
call_id.
For a first test, use a fake weather lookup rather than a real external service. That keeps the example deterministic and makes it obvious which part is the model and which part belongs to your application.
Define the async tool and let Astra continue
The tool definition is almost identical to a normal function tool. The significant addition is async: True. In this example, the application asks Astra to check Paris weather while also answering an unrelated packing question. The weather function is deliberately local demo data, so the result is not dependent on an external service.
import json
from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI
from openai.types.responses import FunctionToolParam
def get_weather(city):
weather = {
"Paris": {
"city": "Paris",
"temperature_c": 22,
"condition": "Clear",
"source": "demo weather snapshot"
}
}
return weather[city]
worker = ThreadPoolExecutor()
client = OpenAI()
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="gpt-6-astra",
tools=tools,
instructions=instructions,
input=(
"Check the demo weather in Paris. Meanwhile, "
"list three essentials for any city trip."
)
)The first response can contain both the function call and useful model output. Your application should inspect the response, find the function call, parse its arguments, and start the actual job. The model does not execute get_weather; your Python process does.
Run the slow job without blocking the model
Once the function call arrives, submit the application work to a worker. The returned future represents the pending job. While that job runs, your application can perform other independent work or handle another conversation event. When the result is ready, continue the Responses conversation using previous_response_id and send a function_call_output containing the original call_id.
call = next(
item for item in response.output
if item.type == "function_call"
)
arguments = json.loads(call.arguments)
if call.async_:
job = worker.submit(get_weather, **arguments)
```
# Astra may already have produced useful independent output.
print(response.output_text)
# Wait only when the next step actually needs the result.
result = job.result()
```
else:
result = get_weather(**arguments)
response = client.responses.create(
model="gpt-6-astra",
tools=tools,
instructions=instructions,
previous_response_id=response.id,
input=[
{
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps(result)
}
]
)
print(response.output_text)
worker.shutdown(wait=True)The important identifier here is call_id. It ties your application's result back to the exact tool request Astra made. The previous_response_id keeps the continuation attached to the existing Responses API conversation instead of forcing you to rebuild the entire transcript.
Use a wait tool when several jobs have dependencies
A single background job is easy to understand, but production workflows often have several pending operations. OpenAI's current async-tool pattern uses an application-defined wait_for_tasks function so the model can decide when it actually needs pending results. Each asynchronous tool receives a unique task_handle, while your application keeps a registry connecting that handle to the original call_id and running job.
tools = [
{
"type": "function",
"name": "lookup_price",
"description": "Look up a product price in the background.",
"async": True,
"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."
),
"strict": True,
"parameters": {
"type": "object",
"properties": {
"task_handles": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["task_handles"],
"additionalProperties": False
}
}
]The wait function is not a built-in OpenAI service. You implement its behavior in your application. When Astra launches two price lookups, for example, your job registry can associate widget_price_1 with one API call and gadget_price_1 with another. When the model later asks to wait for both, your application resolves those jobs and returns each completed result using its original call_id, followed by the wait tool's status.
This design is useful because the model does not have to wait immediately after every asynchronous call. It can start independent work first and pause only at the point where a pending result becomes necessary.
Async does not mean your application can ignore dependencies
The biggest mistake is treating every slow operation as independent. If a model needs the result of a security scan before it can approve a deployment, starting the scan asynchronously does not make the approval safe to produce immediately. The application needs a clear dependency boundary and must prevent the workflow from proceeding past that boundary without the required result.
The same principle matters for side effects. A payment, database mutation, deployment, or account change should have its own authorization and idempotency controls. Async tool calling changes when the model waits; it does not turn a model-generated tool request into a trusted execution command.
That is also why async execution should be part of a broader reliable agents design rather than treated as a performance switch.
Where GPT-6 Astra async tools fit and where they do not
Async tool calling is designed for application-executed function and custom tools. It does not apply to OpenAI-hosted built-in tools, and OpenAI's documentation also says not to combine async tools with parallel tool calls in multi-agent mode. Those boundaries matter because several different kinds of concurrency can otherwise look interchangeable when they are not.
Parallel tool calls let a model request multiple tools together. Async tool calling instead lets your application defer a tool's result while Astra continues with independent work. A normal synchronous tool remains the simplest option when the operation is quick or when every following step depends on its result.
How to tell whether async actually helped
Do not assume that adding async: true automatically makes an agent faster. The feature reduces waiting only when the model has useful independent work to perform while the application runs the tool. If the next model decision immediately requires the result, there may be little or no wall-clock benefit.
Measure the complete workflow rather than only the tool duration. Record the time from the initial request to the final response, tool execution time, number of model turns, pending-job duration, and failures caused by shared state. Then compare the asynchronous version with the simplest synchronous implementation under the same workload.
A useful test is to deliberately give one tool a noticeable delay and pair it with an independent task. If the model can produce that independent work while the delayed operation runs, you have a workload that can demonstrate the feature. If every operation depends on the delayed result, asynchronous execution is unlikely to change the critical path.
The useful pattern is simple: launch, work, wait, resume
GPT-6 Astra's async tool calling is less about putting a function in a background thread and more about making dependencies explicit in an AI workflow. Your application launches the slow operation, Astra continues where it safely can, and the application resumes the conversation when the required result is available. Once several jobs are involved, unique task handles and a small job registry give the model a controlled way to wait for exactly what it needs.
That leaves the most important design decision with the developer: identify which parts of a workflow can truly happen independently. If that boundary is clear, async tools can remove unnecessary waiting without handing control of background execution or side effects to the model.
Share this post



