type error when trying to process `agent: Agent[None, BaseModel]` as a type on `BaseModel`

[NorthIsUp]

this seems like something that testing might have caught, so I'm still looking for how it could be my local setup, but any thoughts are appreciated.

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

this:

from pydantic import BaseModel
from pydantic_ai import Agent


class ImBroke(BaseModel):
    agent: Agent[None, BaseModel]

produces the error:

TypeError: string indices must be integers, not 'typing.TypeVar'
Unable to evaluate type annotation 'ToolsPrepareFunc[AgentDepsT] | None'.

using 0.6.1 and python 3.13

repo with uv.lock for reproduction: https://github.com/NorthIsUp/pydantic-ai-issue1

$ uv run main.py
Traceback (most recent call last):
  File "/Users/adam/src/pydantic-ai-issue/main.py", line 5, in <module>
    class ImBroke(BaseModel):
        agent: Agent[None, BaseModel]
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_model_construction.py", line 237, in __new__
    complete_model_class(
    ~~~~~~~~~~~~~~~~~~~~^
        cls,
        ^^^^
    ...<3 lines>...
        create_model_module=_create_model_module,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_model_construction.py", line 597, in complete_model_class
    schema = gen_schema.generate_schema(cls)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 711, in generate_schema
    schema = self._generate_schema_inner(obj)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 1004, in _generate_schema_inner
    return self._model_schema(obj)
           ~~~~~~~~~~~~~~~~~~^^^^^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 837, in _model_schema
    {k: self._generate_md_field_schema(k, v, decorators) for k, v in fields.items()},
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 1206, in _generate_md_field_schema
    common_field = self._common_field_schema(name, field_info, decorators)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 1372, in _common_field_schema
    schema = self._apply_annotations(
        source_type,
        annotations + validators_from_decorators,
    )
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 2297, in _apply_annotations
    schema = get_inner_schema(source_type)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_schema_generation_shared.py", line 83, in __call__
    schema = self._handler(source_type)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 2279, in inner_handler
    schema = self._generate_schema_inner(obj)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 1009, in _generate_schema_inner
    return self.match_type(obj)
           ~~~~~~~~~~~~~~~^^^^^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 1123, in match_type
    return self._match_generic_type(obj, origin)
           ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 1135, in _match_generic_type
    return self._dataclass_schema(obj, origin)  # pyright: ignore[reportArgumentType]
           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_generate_schema.py", line 1942, in _dataclass_schema
    fields = collect_dataclass_fields(
        dataclass,
        typevars_map=typevars_map,
        config_wrapper=self._config_wrapper,
    )
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_fields.py", line 384, in collect_dataclass_fields
    ann_type, evaluated = _typing_extra.try_eval_type(dataclass_field.type, globalns, localns)
                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_typing_extra.py", line 378, in try_eval_type
    return eval_type_backport(value, globalns, localns), True
           ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_typing_extra.py", line 429, in eval_type_backport
    return _eval_type_backport(value, globalns, localns, type_params)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_typing_extra.py", line 466, in _eval_type_backport
    return _eval_type(value, globalns, localns, type_params)
  File "/Users/adam/src/pydantic-ai-issue/.venv/lib/python3.13/site-packages/pydantic/_internal/_typing_extra.py", line 496, in _eval_type
    return typing._eval_type(  # type: ignore
           ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
        value, globalns, localns, type_params=type_params
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/Users/adam/.local/share/uv/python/cpython-3.13.3-macos-aarch64-none/lib/python3.13/typing.py", line 474, in _eval_type
    return t._evaluate(globalns, localns, type_params, recursive_guard=recursive_guard)
           ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/adam/.local/share/uv/python/cpython-3.13.3-macos-aarch64-none/lib/python3.13/typing.py", line 1081, in _evaluate
    eval(self.__forward_code__, globalns, localns),
    ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 1, in <module>
TypeError: string indices must be integers, not 'typing.TypeVar'
Unable to evaluate type annotation 'ToolsPrepareFunc[AgentDepsT] | None'.

Example Code

from pydantic import BaseModel
from pydantic_ai import Agent


class ImBroke(BaseModel):
    agent: Agent[None, BaseModel]

Python, Pydantic AI & LLM client version

uv run python --version
Python 3.13.3

pydantic-ai>=0.6.1

[NorthIsUp]

repro using GitHub actions: https://github.com/NorthIsUp/pydantic-ai-issue1/actions/runs/16809565342/job/47611051102

[DouweM]

@Viicos Can you have a look here please?

[Viicos]

The Agent class will not be supported as a Pydantic field annotation. Agent is a stdlib dataclass, so Pydantic will try evaluate its annotations but most of them aren't supported by Pydantic. cc @dmontagu, I recall the exact same use case on our Slack but can't find the thread anymore.

If you just want to assert that a proper Agent instance was provided, you can use the following ¹:

from pydantic import BaseModel, GetPydanticSchema
from pydantic_core import core_schema
from pydantic_ai import Agent

from typing_extensions import get_origin

class ImBroke(BaseModel):
    agent: Annotated[
        Agent[None, BaseModel],
        GetPydanticSchema(lambda tp, handler: core_schema.is_instance_schema(get_origin(tp) or tp)),
     ]

Footnotes

1. This is what InstanceOf is also doing, but it also tries to generate a core schema for the actual type for the JSON mode, without catching the TypeError. ↩

[fswair]

Hi @Viicos , i faced this issue before with same error message. In this case, error comes from https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/tools.py#L92

I wonder something why that pydantic-ai uses quoted type annotations in pydantic_ai.tools module?

I understand some of types in quoted annotation not defined yet in this line but i was just considering is there a better way to define them in there.

we should make something better for this module i think. changing definition order or something else. splitting some definitions to another module may also works.

[NorthIsUp]

The Agent class will not be supported as a Pydantic field annotation.

I appreciate the workaround but it's quite counter intuitive that pydantic_ai.Agent can't be used with pydantic models! If there is any way to encapsulate this complexity it would significantly improve the end user experience

[fswair]

It works, I just changed ToolDefinition's and its dependent annotations (ToolKind and ObjectJsonSchema) place by adding them to top:

https://gist.github.com/fswair/1c262bd0f5266f6c2d634b5c4a5bac97

It works!

[Viicos]

I understand some of types in quoted annotation not defined yet in this line but i was just considering is there a better way to define them in there

This is not the main issue here: some of Pydantic AIs types are still not going to work with Pydantic (one example: Agent.model_settings.timeout is float | httpx.Timeout, and httpx.Timeout isn't supported by Pydantic). Having Agent supported by Pydantic is way more work than just moving some type aliases around to remove string annotations (which by itself can be annoying already as a constraint when using type hints as a developer).

I appreciate the workaround but it's quite counter intuitive that pydantic_ai.Agent can't be used with pydantic models!

I find it neither intuitive nor counter intuitive. What is your use case to use Agent as an annotation? Do you expect a simple isinstance() check to be performed? Or having all Agent fields validated? What if you want to use model_validate_json()? model_dump_json()?

[NorthIsUp]

a few things

1. why did this surpise me? i had the assumption (which was completely on my side) that the core classes the pydantic team ships were all "clean" subclasses of BaseModel by design and were designed to be extendable and usable as base classes. Not just for final classes consumption by end users. This behavior seems to be the norm for the other libraries from pydantic (like pydantic-settings) so i had some expectations from that.

   Big emphasis on assumption. Maybe this is a nice principle to have, but that is for you and your team to debate and decide on. Personally, I'd love to see it adopted :)

2. the error was wonky. I'd expect the usual "Set `arbitrary_types_allowed=True`" error. If I got that error I'd probably have just followed the guidance and moved on, but the error message about the string index caught me off guard and i spent a while digging into the code to find out what was going on.

   e.g.:

   class FooImNotPydantic:
       bar: str
   
   
   class FooImPydantic(BaseModel):
       foo: FooImNotPydantic

   cause the more expected error of

   pydantic.errors.PydanticSchemaGenerationError: Unable to generate pydantic-core schema for <class '__main__.FooImNotPydantic'>. Set `arbitrary_types_allowed=True` in the model_config to ignore this error or implement `__get_pydantic_core_schema__` on your type to fully support it.
   
   If you got this error by calling handler(<some type>) within `__get_pydantic_core_schema__` then you likely need to call `handler.generate_schema(<some type>)` since we do not call `__get_pydantic_core_schema__` on `<some type>` otherwise to avoid infinite recursion.
   
   For further information visit https://errors.pydantic.dev/2.11/u/schema-for-unknown-type
   

3. it's mostly about being able to have tool-assisted type consistency that pyright/ruff/ty/mypy can understand and help with.

   a toy example of how we are using it is like this:

   class OurWorkflow[InputT: BaseInputModel, OutputT: BaseModel](BaseModel):
       agent: Agent[None, OutputT]
   
       def run_agent(self, input: OurCompaniesStandardEvalInput[InputT]) -> OurCompaniesStandardEvalOutput[OutputT]:
           the_prompt = input.to_prompt()
           the_output = self.agent.run(the_prompt)
           return OurCompaniesStandardEvalOutput(output=the_output)

   Your fist suggestion of the Annotation does work, but its quite the moutfull and make it so our scientists will have a harder time understanding the type system.

4. but it's also about being able to checkpoint state. being able to use model_dump_json() to report the complete agent state is fantastic for debugging what was going on with the config when exceptions occur.

5. totally understand that internal implementation details like float | httpx.Timeout are a bit of a pita to deal with. If you did want to support this there are many options. I won't even try to suggest any since i'm sure y'all are much better at using validators and serialzers than i am!

6. I love the work y'all are putting out! hope this helps 🙇

[DouweM]

@Viicos Could we make the error message more clear? This looks like Pydantic is doing something wrong, as the ToolsPrepareFunc[AgentDepsT] | None annotation is valid afaik:

TypeError: string indices must be integers, not 'typing.TypeVar'
Unable to evaluate type annotation 'ToolsPrepareFunc[AgentDepsT] | None'.

[Viicos]

This looks like Pydantic is doing something wrong

It's more related to a runtime vs static type checking behavior discrepancy: at runtime (even though annotated as : TypeAlias), ToolsPrepareFunc is a string. So indexing with anything else than an integer will fail and raise the encountered TypeError. Only wrapping the necessary forward references with quotes (namely ToolDefinition) ¹ will fix this bug (although as mentioned this won't make Agent a supported type for Pydantic).

Surprisingly, this wasn't ever reported in Pydantic. We could try to catch this error and provide a clearer error message, but this will only be relevant if ToolsPrepareFunc[AgentDepsT] is itself used in a stringified annotation (otherwise the TypeError will be raised at import time).

Footnotes

1. And using TypeAliasType to avoid limitations if this annotation needs to be supported by Pydantic. ↩

[Viicos]

1. why did this surpise me? i had the assumption (which was completely on my side) that the core classes the pydantic team ships were all "clean" subclasses of BaseModel by design and were designed to be extendable and usable as base classes.

We only do so when it is relevant. Making a class as a Pydantic model adds extra constraints:

• only supported types can be used (unless you specify validation/serialization logic for custom types, which can be quite complex if you want to support JSON).
• Resolving forward references might require rebuilding models.
• Some typing features aren't supported (in particular, ParamSpec, which is an enormous amount of work and is used quite a bit in Pydantic AI).

Pydantic models allow arbitrary data to be validated. There's no point in doing so for the Agent class, as inputs are provided by the developer directly in 99% of the cases (and if they came from untrusted input, validation would be performed before, e.g. in a FastAPI endpoint).

the error was wonky. I'd expect the usual "Set arbitrary_types_allowed=True" error. If I got that error I'd probably have just followed the guidance and moved on

You're right, my suggestion above should address this.

it's mostly about being able to have tool-assisted type consistency that pyright/ruff/ty/mypy can understand and help with.

Static type checkers and linters don't really need Pydantic for this: stdlib dataclasses work fine.

Similarly, on your end, if your OurWorkflow class isn't taking untrusted data as inputs, it might be worth considering switching to a stdlib dataclass for this.

but it's also about being able to checkpoint state. being able to use model_dump_json() to report the complete agent state is fantastic for debugging what was going on with the config when exceptions occur.

That could be valuable (my previous points only mentioned validation, but serialization is a valid use case), although I'm not sure Pydantic would be the best fit for this. For instance, you can provide callables for various arguments of the Agent class, and these can't be serialized to JSON. So probably Pydantic AI can provide its own dump state to JSON functionality.