pydantic_ai.messages

SystemPrompt dataclass

A system prompt, generally written by the application developer.

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 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 sent when running a retriever failed, result validation failed, or no tool could be found to call.

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.

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.

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.

ToolCall dataclass

Either a retriever/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.

ModelStructuredResponse dataclass

A structured response from a model.

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.

ModelAnyResponse module-attribute

ModelAnyResponse = Union[
    ModelTextResponse, ModelStructuredResponse
]

Any response from a model.

Message module-attribute

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

Any message send to or returned by a model.