pydantic_ai.exceptions

ModelRetry

基类：Exception

当工具函数应重试时引发的异常。

代理（agent）将把消息返回给模型，并要求它再次尝试调用该函数/工具。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class ModelRetry(Exception):
    """Exception to raise when a tool function should be retried.

    The agent will return the message to the model and ask it to try calling the function/tool again.
    """

    message: str
    """The message to return to the model."""

    def __init__(self, message: str):
        self.message = message
        super().__init__(message)

    def __eq__(self, other: Any) -> bool:
        return isinstance(other, self.__class__) and other.message == self.message

    @classmethod
    def __get_pydantic_core_schema__(cls, _: Any, __: Any) -> core_schema.CoreSchema:
        """Pydantic core schema to allow `ModelRetry` to be (de)serialized."""
        schema = core_schema.typed_dict_schema(
            {
                'message': core_schema.typed_dict_field(core_schema.str_schema()),
                'kind': core_schema.typed_dict_field(core_schema.literal_schema(['model-retry'])),
            }
        )
        return core_schema.no_info_after_validator_function(
            lambda dct: ModelRetry(dct['message']),
            schema,
            serialization=core_schema.plain_serializer_function_ser_schema(
                lambda x: {'message': x.message, 'kind': 'model-retry'},
                return_schema=schema,
            ),
        )

message 实例属性

message: str = message

要返回给模型的消息。

__get_pydantic_core_schema__ classmethod

__get_pydantic_core_schema__(_: Any, __: Any) -> CoreSchema

Pydantic核心模式，允许对 ModelRetry进行（反）序列化。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

@classmethod
def __get_pydantic_core_schema__(cls, _: Any, __: Any) -> core_schema.CoreSchema:
    """Pydantic core schema to allow `ModelRetry` to be (de)serialized."""
    schema = core_schema.typed_dict_schema(
        {
            'message': core_schema.typed_dict_field(core_schema.str_schema()),
            'kind': core_schema.typed_dict_field(core_schema.literal_schema(['model-retry'])),
        }
    )
    return core_schema.no_info_after_validator_function(
        lambda dct: ModelRetry(dct['message']),
        schema,
        serialization=core_schema.plain_serializer_function_ser_schema(
            lambda x: {'message': x.message, 'kind': 'model-retry'},
            return_schema=schema,
        ),
    )

CallDeferred

基类：Exception

当工具调用应延迟时引发的异常。

更多信息请参见工具文档。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class CallDeferred(Exception):
    """Exception to raise when a tool call should be deferred.

    See [tools docs](../deferred-tools.md#deferred-tools) for more information.
    """

    pass

ApprovalRequired

基类：Exception

当工具调用需要人工审批时引发的异常。

更多信息请参见工具文档。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class ApprovalRequired(Exception):
    """Exception to raise when a tool call requires human-in-the-loop approval.

    See [tools docs](../deferred-tools.md#human-in-the-loop-tool-approval) for more information.
    """

    pass

UserError

基类：RuntimeError

由应用程序开发人员（即您）的使用错误引起的错误。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class UserError(RuntimeError):
    """Error caused by a usage mistake by the application developer — You!"""

    message: str
    """Description of the mistake."""

    def __init__(self, message: str):
        self.message = message
        super().__init__(message)

message 实例属性

message: str = message

对错误的描述。

AgentRunError

基类：RuntimeError

代理（agent）运行期间发生错误的基类。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class AgentRunError(RuntimeError):
    """Base class for errors occurring during an agent run."""

    message: str
    """The error message."""

    def __init__(self, message: str):
        self.message = message
        super().__init__(message)

    def __str__(self) -> str:
        return self.message

message 实例属性

message: str = message

错误信息。

UsageLimitExceeded

基类：AgentRunError

当模型的使用量超过指定限制时引发的错误。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class UsageLimitExceeded(AgentRunError):
    """Error raised when a Model's usage exceeds the specified limits."""

UnexpectedModelBehavior

基类：AgentRunError

由意外的模型行为引起的错误，例如意外的响应码。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class UnexpectedModelBehavior(AgentRunError):
    """Error caused by unexpected Model behavior, e.g. an unexpected response code."""

    message: str
    """Description of the unexpected behavior."""
    body: str | None
    """The body of the response, if available."""

    def __init__(self, message: str, body: str | None = None):
        self.message = message
        if body is None:
            self.body: str | None = None
        else:
            try:
                self.body = json.dumps(json.loads(body), indent=2)
            except ValueError:
                self.body = body
        super().__init__(message)

    def __str__(self) -> str:
        if self.body:
            return f'{self.message}, body:\n{self.body}'
        else:
            return self.message

message 实例属性

message: str = message

对意外行为的描述。

body instance-attribute

body: str | None = dumps(loads(body), indent=2)

响应的主体内容（如果可用）。

ModelHTTPError

基类：AgentRunError

当模型提供商的响应状态码为4xx或5xx时引发。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class ModelHTTPError(AgentRunError):
    """Raised when an model provider response has a status code of 4xx or 5xx."""

    status_code: int
    """The HTTP status code returned by the API."""

    model_name: str
    """The name of the model associated with the error."""

    body: object | None
    """The body of the response, if available."""

    message: str
    """The error message with the status code and response body, if available."""

    def __init__(self, status_code: int, model_name: str, body: object | None = None):
        self.status_code = status_code
        self.model_name = model_name
        self.body = body
        message = f'status_code: {status_code}, model_name: {model_name}, body: {body}'
        super().__init__(message)

message 实例属性

message: str

包含状态码和响应主体的错误消息（如果可用）。

status_code instance-attribute

status_code: int = status_code

API返回的HTTP状态码。

model_name instance-attribute

model_name: str = model_name

与此错误关联的模型名称。

body instance-attribute

body: object | None = body

响应的主体内容（如果可用）。

FallbackExceptionGroup

基类：ExceptionGroup

当所有备用模型都失败时可以引发的一组异常。

源代码位于 pydantic_ai_slim/pydantic_ai/exceptions.py

class FallbackExceptionGroup(ExceptionGroup):
    """A group of exceptions that can be raised when all fallback models fail."""