Skip to content

pydantic_ai.messages

Message module-attribute 

Message = Union[
    SystemPrompt,
    UserPrompt,
    ToolReturn,
    RetryPrompt,
    ModelResponse,
]

Any message send to or returned by a model.

SystemPrompt dataclass

A system prompt, generally written by the application developer.

This gives the model context and guidance on how to respond.

Source code in pydantic_ai_slim/pydantic_ai/messages.py 
14
15
16
17
18
19
20
21
22
23
24
@dataclass
class SystemPrompt:
    """A system prompt, generally written by the application developer.

    This gives the model context and guidance on how to respond.
    """

    content: str
    """The content of the prompt."""
    role: Literal['system'] = 'system'
    """Message type identifier, this type is available on all message as a discriminator."""

content instance-attribute 

content: str

The content of the prompt.

role class-attribute instance-attribute 

role: Literal['system'] = 'system'

Message type identifier, this type is available on all message as a discriminator.

UserPrompt dataclass

A user prompt, generally written by the end user.

Content comes from the user_prompt parameter of Agent.run, Agent.run_sync, and Agent.run_stream.

Source code in pydantic_ai_slim/pydantic_ai/messages.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@dataclass
class UserPrompt:
    """A user prompt, generally written by the end user.

    Content comes from the `user_prompt` parameter of [`Agent.run`][pydantic_ai.Agent.run],
    [`Agent.run_sync`][pydantic_ai.Agent.run_sync], and [`Agent.run_stream`][pydantic_ai.Agent.run_stream].
    """

    content: str
    """The content of the prompt."""
    timestamp: datetime = field(default_factory=_now_utc)
    """The timestamp of the prompt."""
    role: Literal['user'] = 'user'
    """Message type identifier, this type is available on all message as a discriminator."""

content instance-attribute 

content: str

The content of the prompt.

timestamp class-attribute instance-attribute 

timestamp: datetime = field(default_factory=now_utc)

The timestamp of the prompt.

role class-attribute instance-attribute 

role: Literal['user'] = 'user'

Message type identifier, this type is available on all message as a discriminator.

ToolReturn dataclass

A tool return message, this encodes the result of running a tool.

Source code in pydantic_ai_slim/pydantic_ai/messages.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@dataclass
class ToolReturn:
    """A tool return message, this encodes the result of running a tool."""

    tool_name: str
    """The name of the "tool" was called."""
    content: Any
    """The return value."""
    tool_call_id: str | None = None
    """Optional tool call identifier, this is used by some models including OpenAI."""
    timestamp: datetime = field(default_factory=_now_utc)
    """The timestamp, when the tool returned."""
    role: Literal['tool-return'] = 'tool-return'
    """Message type identifier, this type is available on all message as a discriminator."""

    def model_response_str(self) -> str:
        if isinstance(self.content, str):
            return self.content
        else:
            return tool_return_ta.dump_json(self.content).decode()

    def model_response_object(self) -> dict[str, Any]:
        # gemini supports JSON dict return values, but no other JSON types, hence we wrap anything else in a dict
        if isinstance(self.content, dict):
            return tool_return_ta.dump_python(self.content, mode='json')  # pyright: ignore[reportUnknownMemberType]
        else:
            return {'return_value': tool_return_ta.dump_python(self.content, mode='json')}

tool_name instance-attribute 

tool_name: str

The name of the "tool" was called.

content instance-attribute 

content: Any

The return value.

tool_call_id class-attribute instance-attribute 

tool_call_id: str | None = None

Optional tool call identifier, this is used by some models including OpenAI.

timestamp class-attribute instance-attribute 

timestamp: datetime = field(default_factory=now_utc)

The timestamp, when the tool returned.

role class-attribute instance-attribute 

role: Literal['tool-return'] = 'tool-return'

Message type identifier, this type is available on all message as a discriminator.

RetryPrompt dataclass

A message back to a model asking it to try again.

This can be sent for a number of reasons:

  • Pydantic validation of tool arguments failed, here content is derived from a Pydantic ValidationError
  • a tool raised a ModelRetry exception
  • no tool was found for the tool name
  • the model returned plain text when a structured response was expected
  • Pydantic validation of a structured response failed, here content is derived from a Pydantic ValidationError
  • a result validator raised a ModelRetry exception
Source code in pydantic_ai_slim/pydantic_ai/messages.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
@dataclass
class RetryPrompt:
    """A message back to a model asking it to try again.

    This can be sent for a number of reasons:

    * Pydantic validation of tool arguments failed, here content is derived from a Pydantic
      [`ValidationError`][pydantic_core.ValidationError]
    * a tool raised a [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] exception
    * no tool was found for the tool name
    * the model returned plain text when a structured response was expected
    * Pydantic validation of a structured response failed, here content is derived from a Pydantic
      [`ValidationError`][pydantic_core.ValidationError]
    * a result validator raised a [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] exception
    """

    content: list[pydantic_core.ErrorDetails] | str
    """Details of why and how the model should retry.

    If the retry was triggered by a [`ValidationError`][pydantic_core.ValidationError], this will be a list of
    error details.
    """
    tool_name: str | None = None
    """The name of the tool that was called, if any."""
    tool_call_id: str | None = None
    """Optional tool call identifier, this is used by some models including OpenAI."""
    timestamp: datetime = field(default_factory=_now_utc)
    """The timestamp, when the retry was triggered."""
    role: Literal['retry-prompt'] = 'retry-prompt'
    """Message type identifier, this type is available on all message as a discriminator."""

    def model_response(self) -> str:
        if isinstance(self.content, str):
            description = self.content
        else:
            json_errors = ErrorDetailsTa.dump_json(self.content, exclude={'__all__': {'ctx'}}, indent=2)
            description = f'{len(self.content)} validation errors: {json_errors.decode()}'
        return f'{description}\n\nFix the errors and try again.'

content instance-attribute 

content: list[ErrorDetails] | str

Details of why and how the model should retry.

If the retry was triggered by a ValidationError, this will be a list of error details.

tool_name class-attribute instance-attribute 

tool_name: str | None = None

The name of the tool that was called, if any.

tool_call_id class-attribute instance-attribute 

tool_call_id: str | None = None

Optional tool call identifier, this is used by some models including OpenAI.

timestamp class-attribute instance-attribute 

timestamp: datetime = field(default_factory=now_utc)

The timestamp, when the retry was triggered.

role class-attribute instance-attribute 

role: Literal['retry-prompt'] = 'retry-prompt'

Message type identifier, this type is available on all message as a discriminator.

ModelResponse dataclass

A response from a model.

Source code in pydantic_ai_slim/pydantic_ai/messages.py 
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
@dataclass
class ModelResponse:
    """A response from a model."""

    parts: list[ModelResponsePart]
    """The parts of the response."""

    role: Literal['model-response'] = 'model-response'
    """Message type identifier, this type is available on all message as a discriminator."""
    timestamp: datetime = field(default_factory=_now_utc)
    """The timestamp of the response.

    If the model provides a timestamp in the response (as OpenAI does) that will be used.
    """

    @staticmethod
    def from_text(content: str, timestamp: datetime | None = None) -> ModelResponse:
        return ModelResponse([TextPart(content)], timestamp=timestamp or _now_utc())

parts instance-attribute 

parts: list[ModelResponsePart]

The parts of the response.

role class-attribute instance-attribute 

role: Literal['model-response'] = 'model-response'

Message type identifier, this type is available on all message as a discriminator.

timestamp class-attribute instance-attribute 

timestamp: datetime = field(default_factory=now_utc)

The timestamp of the response.

If the model provides a timestamp in the response (as OpenAI does) that will be used.

ArgsJson dataclass

Tool arguments as a JSON string.

Source code in pydantic_ai_slim/pydantic_ai/messages.py 
128
129
130
131
132
133
@dataclass
class ArgsJson:
    """Tool arguments as a JSON string."""

    args_json: str
    """A JSON string of arguments."""

args_json instance-attribute 

args_json: str

A JSON string of arguments.

MessagesTypeAdapter module-attribute 

MessagesTypeAdapter = LazyTypeAdapter(
    list[Annotated[Message, Discriminator("role")]]
)

Pydantic TypeAdapter for (de)serializing messages.