[DRAFT] Add OpenAI Client Error Handler

[lspinheiro]

Why are these changes needed?

This PR introduces an error handler decorator on the openai client. The implementation allow users to specify error callbacks in case the client fails. The goal is to always provide a create result that the client can propagate to the agent to avoid application termination due to the exception.

There are default implementatios for the content safety error and a retry mechanism for transient errors. Still needs to check how the change will propagate to agentchat.

Related issue number

Checks

• I've included any doc changes needed for https://microsoft.github.io/autogen/. See https://github.com/microsoft/autogen/blob/main/CONTRIBUTING.md to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

[lspinheiro]

@ekzhu , can you have a look and tag the relevant people for feedback?

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (2)

python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py:420

• [nitpick] Wrapping the 'create' and 'create_stream' methods inside the init may lead to unexpected behavior if these methods are later overridden or extended. Consider applying the decorator at the method definition level so the error handler is consistently applied across all class usages.

        # Wrap the methods in the error handler

python/packages/autogen-ext/tests/models/test_openai_model_client.py:1227

• [nitpick] The rate limiting test only verifies a single retry scenario with a fixed backoff delay. Consider adding a test case that triggers multiple consecutive retries to validate the exponential backoff logic more thoroughly.

    @patch("asyncio.sleep", return_value=None)

[ekzhu]

Thanks for the draft PR! It presents a good starting point. For create_stream the caller will be consume the output as an async generator. By wrapping the create_stream method, do you think it may result in weird behavior such as the generator restarts from the beginning without the caller's knowledge?

[lspinheiro]

Thanks for the draft PR! It presents a good starting point. For create_stream the caller will be consume the output as an async generator. By wrapping the create_stream method, do you think it may result in weird behavior such as the generator restarts from the beginning without the caller's knowledge?

What I think may happen is that if the exception occurs in the middle of the stream, then the client will start streaming the response and then it may retry and there may be a reset in the stream without any clear warning (I'm not sure there is much we can do, maybe add a warning in the callback to make it clear that there was an exception?)

I think the final processing of the CreateResult will flow as expected.

[ekzhu]

For create_stream I think a warning may not be sufficient, because the caller is not notified gracefully -- only the user inspecting the output is notified. It's gonna be tricky, but I think the best way from the caller's point of view is to emit some kind of truncated CreateResult signaling a pre-mature finish (TruncatedCreateResult, for example) but more string chunks will come. So the caller can handle it appropriately. From the AssistantAgent it can then emit a ModelClientStreamResetEvent to signal a reset of the stream due to error or retry.

It's all too complicated for one PR. Perhaps we can address create_stream separately in the future.