fix: don't emit ToolStream events for non generator functions

[zastrowm]

Description

Our current implementation of AgentTool.stream() has a problem that we don't differentiate between intermediate streaming events and the final ToolResult events. Our only contract is that the last event must be be the tool result that is passed to the LLM. Our switch to Typed Events (#755) pushes us in the right direction but for backwards compatibility we can't update the signature of AgentTool.stream() (nor have we exposed externally TypedEvents yet). That means that if we implemented tool-streaming today, then callers would see non-generator functions yielding both a ToolStreamEvent and ToolResultEvent even though they're not actually streaming responses.

To avoid the odd behavior noted above, we'll special-case SDK-defined functions by allowing them to emit ToolStreamEvent and ToolResultEvent types directly (bypassing our normal wrapping), since they have the knowledge of when tools are actually generators or not.

There's no observable difference in behavior to callers (this is all internal behavior), but this means that when we switch the flip for Tool Streaming, non-generator tools will not emit ToolStreamEvents - at least for AgentTool implementations that are in the SDK.

Note that we have tests verifying the e2e events emitted, including synchronous, asynchronous, and async generator tools:

sdk-python/tests/strands/agent/hooks/test_agent_events.py

Lines 15 to 30 in cb4b7fb

	@strands.tool
	def normal_tool(agent: Agent):
	return f"Done with synchronous {agent.name}!"
	@strands.tool
	async def async_tool(agent: Agent):
	await asyncio.sleep(0.1)
	return f"Done with asynchronous {agent.name}!"
	@strands.tool
	async def streaming_tool():
	await asyncio.sleep(0.2)
	yield {"tool_streaming": True}
	yield "Final result"

giving me confidence that nothing observable is changing here.

Related Issues

#543, #242

Documentation PR

Type of Change

Bug fix/tool streaming prep

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.