MyPy issues when using DeferredToolRequests

[andrzej-pomirski-yohana]

Initial Checks

• I confirm that I'm using the latest version of Pydantic AI
• I confirm that I searched for my issue in https://github.com/pydantic/pydantic-ai/issues before opening this issue

Description

See sample code. The mypy typechecker is not able to infer the correct output type. I am unsure if it's even possible to do anything about it due to the runtime (probably) required to infer agent.output_type, so it might just be a case where a type ignore is required. I also tried the union operator instead of list elements, but then I encountered another bug (No overload variant of "run_stream" of "AbstractAgent" matches argument type "UnionType")

The code below results in error: Need type annotation for "result" [var-annotated].

Example Code

from pydantic_ai import Agent, DeferredToolRequests


async def run() -> None:
    agent = Agent(
        name="Chat Agent",
    )
    async with agent.run_stream(
        output_type=[agent.output_type, DeferredToolRequests]
    ) as result:
        async for _response in result.stream_output():
            pass


if __name__ == "__main__":
    import asyncio

    asyncio.run(run())

Python, Pydantic AI & LLM client version

Python 3.12
pydantic-ai-slim 1.14.1
mypy 1.18.2

[DouweM]

@andrzej-pomirski-yohana This is a known issue with mypy: python/mypy#19142

Check out the "Type checking considerations" section under https://ai.pydantic.dev/output/#structured-output, specifically point 2:

With mypy: When using a list, as a functionally equivalent alternative to a union, or because you're passing in output functions. Pyright does handle this correctly, and we've filed an issue with mypy to try and get this fixed.

In our test suite you can see that "mypy requires the generic parameters to be specified explicitly to be happy here" whereas "pyright is able to correctly infer the type here":

pydantic-ai/tests/typed_agent.py

Lines 208 to 257 in a980aa0

	if MYPY:
	# mypy requires the generic parameters to be specified explicitly to be happy here
	async_int_function_agent = Agent[None, int](output_type=foobar_plain)
	assert_type(async_int_function_agent, Agent[None, int])
	two_models_output_agent = Agent[None, Foo | Bar](output_type=[Foo, Bar])
	assert_type(two_models_output_agent, Agent[None, Foo | Bar])
	two_scalars_output_agent = Agent[None, int | str](output_type=[int, str])
	assert_type(two_scalars_output_agent, Agent[None, int | str])
	marker: ToolOutput[bool | tuple[str, int]] = ToolOutput(bool | tuple[str, int]) # type: ignore
	complex_output_agent = Agent[None, Foo | Bar | Decimal | int | bool | tuple[str, int] | str | re.Pattern[str]](
	output_type=[str, Foo, Bar, foobar_ctx, ToolOutput[int](foobar_plain), marker, TextOutput(str_to_regex)]
	)
	assert_type(
	complex_output_agent, Agent[None, Foo | Bar | Decimal | int | bool | tuple[str, int] | str | re.Pattern[str]]
	)
	complex_deferred_output_agent = Agent[
	None, Foo | Bar | Decimal | int | bool | tuple[str, int] | str | re.Pattern[str] | DeferredToolRequests
	](output_type=[complex_output_agent.output_type, DeferredToolRequests])
	assert_type(
	complex_deferred_output_agent,
	Agent[None, Foo | Bar | Decimal | int | bool | tuple[str, int] | str | re.Pattern[str] | DeferredToolRequests],
	)
	else:
	# pyright is able to correctly infer the type here
	async_int_function_agent = Agent(output_type=foobar_plain)
	assert_type(async_int_function_agent, Agent[None, int])
	two_models_output_agent = Agent(output_type=[Foo, Bar])
	assert_type(two_models_output_agent, Agent[None, Foo | Bar])
	two_scalars_output_agent = Agent(output_type=[int, str])
	assert_type(two_scalars_output_agent, Agent[None, int | str])
	marker: ToolOutput[bool | tuple[str, int]] = ToolOutput(bool | tuple[str, int]) # type: ignore
	complex_output_agent = Agent(
	output_type=[str, Foo, Bar, foobar_ctx, ToolOutput(foobar_plain), marker, TextOutput(str_to_regex)]
	)
	assert_type(
	complex_output_agent, Agent[None, Foo | Bar | Decimal | int | bool | tuple[str, int] | str | re.Pattern[str]]
	)
	complex_deferred_output_agent = Agent(output_type=[complex_output_agent.output_type, DeferredToolRequests])
	assert_type(
	complex_deferred_output_agent,
	Agent[None, Foo | Bar | Decimal | int | bool | tuple[str, int] | str | re.Pattern[str] | DeferredToolRequests],
	)

The relevant example is:

complex_deferred_output_agent = Agent(output_type=[complex_output_agent.output_type, DeferredToolRequests])