Azure AI Foundry SDK: How to stream agent responses with tool call events using azure-ai-projects in Python

Question

Azure AI Foundry SDK: How to stream agent responses with tool call events using azure-ai-projects in Python

Jubin Soni 160

Hi all! I'm building a Foundry Agent in Python using azure-ai-projects and I want to stream the agent's response to the user in real time, including visibility into when a tool is being called and when the final answer is being generated.

Environment:

SDK: azure-ai-projects==1.0.0b11
Python 3.11
Model: gpt-4o
Tools: one OpenAPI tool and one Azure AI Search knowledge base

What I've tried:

Used create_stream on the runs API but I'm not sure how to distinguish between tool call events and text delta events in the stream
Reviewed the SDK docs but couldn't find a streaming example that includes tool call event handling

Can someone share a working Python example that streams agent responses and handles tool call events separately from text output? Thank you in advance!

0 comments

Answer accepted by question author

Alex Burlachenko 25,285 MVP Volunteer Moderator

hi Jubin Soni & thx for sharing urs issue here at Q&A portal,

In azure-ai-projects==1.0.0b11, streaming events are a bit clunky. U need to inspect the event type/name and branch on it. Text deltas and tool/run-step events come as different stream events.

Basic pattern

with project_client.agents.create_stream(
    thread_id=thread.id,
    agent_id=agent.id
) as stream:
    for event_type, event_data, _ in stream:
        name = str(event_type)
        if 'message.delta' in name:
            for item in event_data.delta.content:
                if hasattr(item, 'text') and item.text:
                    print(item.text.value, end='', flush=True)
        elif 'run.step' in name or 'tool' in name:
            print(f'\n[tool event] {name}')
        elif 'requires_action' in name:
            print('\n[tool call required]')
        elif 'done' in name:
            print('\n[done]')

For hosted/OpenAPI/Search tools, u may not always get nice human-readable tool payloads. Sometimes u only see run-step/tool-call lifecycle events, while the actual tool execution stays service-side.

azure-ai-projects has moved fast and event shapes changed across beta versions. If u can, test w/ the latest SDK and print raw event_type once. That’s the easiest way to see the exact event names ur version emits.

rgds,

Alex

&

If my answer was helpful pls mark it and additional thx if u follow me at Q&A portal

and at my blog https://ctrlaltdel.blog/

0 comments

1 additional answer

Your answer

Answer 1

Hello @Jubin Soni ,

Welcome to Microsoft Q&A .Thank you for reaching out to us.

The behavior observed is primarily due to how the Azure AI Agents streaming model is designed. During a run, the service emits different event types for response generation, tool execution, and run lifecycle updates. Because these events are surfaced independently, it is not always immediately clear which events represent assistant-generated text and which represent tool activity when relying solely on event names.

The recommended approach is therefore to distinguish events based on the type of the returned event_data object rather than string-matching event names. This provides a more reliable and maintainable implementation pattern across SDK versions.

The stream can emit several event types, each representing a different stage of execution:

MessageDeltaChunk – Incremental assistant response text.
RunStep – Execution step information, including tool calls.
RunStepDeltaChunk – Incremental updates while a run step is executing.
ThreadRun – Overall run lifecycle status.
ThreadMessage – Completed assistant messages.
AgentStreamEvent.ERROR / AgentStreamEvent.DONE – Stream termination events.

The practical implementation pattern is:

Use MessageDeltaChunk events to process streamed assistant responses.
Monitor RunStep events and check whether RunStep.type == "tool_calls".
Use the associated RunStep.status (in_progress, completed, or failed) to track tool execution progress.
Optionally monitor RunStepDeltaChunk events when additional visibility into tool execution is required.

For Azure AI Search and OpenAPI tools

Use MessageDeltaChunk for streamed assistant text.
Use RunStep and RunStepDeltaChunk for tool execution tracking and progress indicators.
Treat these event streams independently to clearly separate tool activity from generated responses.

Azure AI Search and OpenAPI integrations are generally used as hosted (service-side) tools. In these scenarios, tool execution occurs within the Azure AI Foundry service rather than within the client application process. The OpenAPI tool documentation explicitly notes that execution does not occur client-side.

As a result, hosted tools are typically surfaced through:

RunStep lifecycle events
RunStepDeltaChunk updates
Run status changes
Streamed assistant responses

Hosted tools are generally monitored through these lifecycle events rather than through detailed client-side execution workflows. For this reason, RunStep and RunStepDeltaChunk are typically the most useful indicators for displaying progress such as "Searching..." or "Calling API..." while execution is in progress.

By contrast, requires_action is primarily associated with Function Tools, where execution occurs outside the service and tool outputs must be submitted back to continue processing.

If the expected tool events are not being observed:

Verify the SDK version currently installed.
Log both event_type and type(event_data) to identify the exact event objects emitted by the runtime.
Confirm that the prompt is triggering Azure AI Search or OpenAPI tool invocation.
Verify that the implementation is monitoring both RunStep.type == "tool_calls" and the associated step status.
If possible, validate behavior against the latest supported azure-ai-agents and azure-ai-projects packages, as streaming event models have evolved across releases.

The following references might be helpful , please check them out

Thank you

Please "Accept" the answer with an "Upvote" if the response was helpful. This will be benefitting other community members who face the same issue.