Skip to content

pydantic_ai.messages

Message module-attribute 

Message = Union[
    SystemPrompt,
    UserPrompt,
    ToolReturn,
    RetryPrompt,
    ModelTextResponse,
    ModelStructuredResponse,
]

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.

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.

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 retriever.

tool_name instance-attribute 

tool_name: str

The name of the "tool" was called.

content instance-attribute 

content: str | dict[str, Any]

The return value.

tool_id class-attribute instance-attribute 

tool_id: str | None = None

Optional tool 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 retriever arguments failed, here content is derived from a Pydantic ValidationError
  • a retriever raised a ModelRetry exception
  • no retriever 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

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_id class-attribute instance-attribute 

tool_id: str | None = None

The tool identifier, if any.

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.

ModelAnyResponse module-attribute 

ModelAnyResponse = Union[
    ModelTextResponse, ModelStructuredResponse
]

Any response from a model.

ModelTextResponse dataclass

A plain text response from a model.

content instance-attribute 

content: str

The text content of the response.

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.

role class-attribute instance-attribute 

role: Literal["model-text-response"] = "model-text-response"

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

ModelStructuredResponse dataclass

A structured response from a model.

This is used either to call a retriever or to return a structured response from an agent run.

calls instance-attribute 

calls: list[ToolCall]

The tool calls being made.

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.

role class-attribute instance-attribute 

role: Literal["model-structured-response"] = (
    "model-structured-response"
)

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

ToolCall dataclass

Either a tool call from the agent.

tool_name instance-attribute 

tool_name: str

The name of the tool to call.

args instance-attribute 

args: ArgsJson | ArgsObject

The arguments to pass to the tool.

Either as JSON or a Python dictionary depending on how data was returned.

tool_id class-attribute instance-attribute 

tool_id: str | None = None

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

ArgsJson dataclass

args_json instance-attribute 

args_json: str

A JSON string of arguments.

ArgsObject dataclass

args_object instance-attribute 

args_object: dict[str, Any]

A python dictionary of arguments.

MessagesTypeAdapter module-attribute 

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

Pydantic TypeAdapter for (de)serializing messages.