How to intermediate · 3 min read

How to submit tool outputs to a run

Q: How to submit tool outputs to a run

Use the client.assistants.runs.submit_tool_output() method to submit tool outputs to a run in OpenAI Assistants. Provide the run_id, tool name, and tool_output as parameters to update the run with the tool's results.

Quick answer

Use the client.assistants.runs.submit_tool_output() method to submit tool outputs to a run in OpenAI Assistants. Provide the run_id, tool name, and tool_output as parameters to update the run with the tool's results.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official OpenAI Python SDK and set your API key as an environment variable.

Run pip install openai>=1.0 to install the SDK.
Set your API key in your shell: export OPENAI_API_KEY='your_api_key_here' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key_here" (Windows).

bash

pip install openai>=1.0

Step by step

This example demonstrates how to submit a tool output to an existing run using the OpenAI Assistants API. Replace run_id and tool_name with your actual values.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Define your run ID and tool output
run_id = "run_1234567890abcdef"
tool_name = "my_custom_tool"
tool_output = {
    "result": "Tool execution successful",
    "data": {"value": 42, "status": "ok"}
}

# Submit the tool output to the run
response = client.assistants.runs.submit_tool_output(
    run_id=run_id,
    tool=tool_name,
    tool_output=tool_output
)

print("Tool output submitted successfully:", response)

output

Tool output submitted successfully: {'id': 'run_1234567890abcdef', 'status': 'updated', 'tool': 'my_custom_tool', 'tool_output': {'result': 'Tool execution successful', 'data': {'value': 42, 'status': 'ok'}}}

Common variations

You can submit tool outputs asynchronously or use different models for the run. The submit_tool_output method supports JSON-serializable outputs. For streaming or async usage, integrate with async frameworks or event loops accordingly.

python

import asyncio
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def submit_tool_output_async():
    run_id = "run_1234567890abcdef"
    tool_name = "my_custom_tool"
    tool_output = {"result": "Async tool output"}

    response = await client.assistants.runs.submit_tool_output(
        run_id=run_id,
        tool=tool_name,
        tool_output=tool_output
    )
    print("Async tool output submitted:", response)

asyncio.run(submit_tool_output_async())

output

Async tool output submitted: {'id': 'run_1234567890abcdef', 'status': 'updated', 'tool': 'my_custom_tool', 'tool_output': {'result': 'Async tool output'}}

Troubleshooting

If you get a 401 Unauthorized error, verify your OPENAI_API_KEY environment variable is set correctly.
If the run_id is invalid or not found, confirm the run exists and you have access.
Ensure tool_output is JSON-serializable; otherwise, serialization errors will occur.

✅

Key Takeaways

Use client.assistants.runs.submit_tool_output() to update runs with tool outputs.
Always provide a valid run_id, tool name, and JSON-serializable tool_output.
Set your API key in os.environ["OPENAI_API_KEY"] to authenticate requests.
Async submission is supported; adapt code to your async environment as needed.

Verified 2026-04 · gpt-4o

Verify ↗