跳过内容

Agent 输出

AgentOutputSchemaBase

基础: ABC

一个捕获输出 JSON schema 的对象，以及将 LLM 生成的 JSON 解析/验证为输出类型的对象。

源代码位于 src/agents/agent_output.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
class AgentOutputSchemaBase(abc.ABC):
    """An object that captures the JSON schema of the output, as well as validating/parsing JSON
    produced by the LLM into the output type.
    """

    @abc.abstractmethod
    def is_plain_text(self) -> bool:
        """Whether the output type is plain text (versus a JSON object)."""
        pass

    @abc.abstractmethod
    def name(self) -> str:
        """The name of the output type."""
        pass

    @abc.abstractmethod
    def json_schema(self) -> dict[str, Any]:
        """Returns the JSON schema of the output. Will only be called if the output type is not
        plain text.
        """
        pass

    @abc.abstractmethod
    def is_strict_json_schema(self) -> bool:
        """Whether the JSON schema is in strict mode. Strict mode constrains the JSON schema
        features, but guarantees valid JSON. See here for details:
        https://platform.openai.com/docs/guides/structured-outputs#supported-schemas
        """
        pass

    @abc.abstractmethod
    def validate_json(self, json_str: str) -> Any:
        """Validate a JSON string against the output type. You must return the validated object,
        or raise a `ModelBehaviorError` if the JSON is invalid.
        """
        pass

is_plain_text abstractmethod 

is_plain_text() -> bool

输出类型是否为纯文本（而非 JSON 对象）。

源代码位于 src/agents/agent_output.py 
21
22
23
24
@abc.abstractmethod
def is_plain_text(self) -> bool:
    """Whether the output type is plain text (versus a JSON object)."""
    pass

name abstractmethod 

name() -> str

输出类型的名称。

源代码位于 src/agents/agent_output.py 
26
27
28
29
@abc.abstractmethod
def name(self) -> str:
    """The name of the output type."""
    pass

json_schema abstractmethod 

json_schema() -> dict[str, Any]

返回输出的 JSON schema。仅当输出类型不是纯文本时才会被调用。

源代码位于 src/agents/agent_output.py 
31
32
33
34
35
36
@abc.abstractmethod
def json_schema(self) -> dict[str, Any]:
    """Returns the JSON schema of the output. Will only be called if the output type is not
    plain text.
    """
    pass

is_strict_json_schema abstractmethod 

is_strict_json_schema() -> bool

JSON schema 是否处于严格模式。严格模式会限制 JSON schema 的特性，但保证有效的 JSON。详情请参见：https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

源代码位于 src/agents/agent_output.py 
38
39
40
41
42
43
44
@abc.abstractmethod
def is_strict_json_schema(self) -> bool:
    """Whether the JSON schema is in strict mode. Strict mode constrains the JSON schema
    features, but guarantees valid JSON. See here for details:
    https://platform.openai.com/docs/guides/structured-outputs#supported-schemas
    """
    pass

validate_json abstractmethod 

validate_json(json_str: str) -> Any

根据输出类型验证 JSON 字符串。必须返回验证后的对象，或者如果 JSON 无效则引发 ModelBehaviorError。

源代码位于 src/agents/agent_output.py 
46
47
48
49
50
51
@abc.abstractmethod
def validate_json(self, json_str: str) -> Any:
    """Validate a JSON string against the output type. You must return the validated object,
    or raise a `ModelBehaviorError` if the JSON is invalid.
    """
    pass

AgentOutputSchema dataclass

Bases: AgentOutputSchemaBase

一个捕获输出 JSON schema 的对象，以及将 LLM 生成的 JSON 解析/验证为输出类型的对象。

源代码位于 src/agents/agent_output.py 
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
@dataclass(init=False)
class AgentOutputSchema(AgentOutputSchemaBase):
    """An object that captures the JSON schema of the output, as well as validating/parsing JSON
    produced by the LLM into the output type.
    """

    output_type: type[Any]
    """The type of the output."""

    _type_adapter: TypeAdapter[Any]
    """A type adapter that wraps the output type, so that we can validate JSON."""

    _is_wrapped: bool
    """Whether the output type is wrapped in a dictionary. This is generally done if the base
    output type cannot be represented as a JSON Schema object.
    """

    _output_schema: dict[str, Any]
    """The JSON schema of the output."""

    _strict_json_schema: bool
    """Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True,
    as it increases the likelihood of correct JSON input.
    """

    def __init__(self, output_type: type[Any], strict_json_schema: bool = True):
        """
        Args:
            output_type: The type of the output.
            strict_json_schema: Whether the JSON schema is in strict mode. We **strongly** recommend
                setting this to True, as it increases the likelihood of correct JSON input.
        """
        self.output_type = output_type
        self._strict_json_schema = strict_json_schema

        if output_type is None or output_type is str:
            self._is_wrapped = False
            self._type_adapter = TypeAdapter(output_type)
            self._output_schema = self._type_adapter.json_schema()
            return

        # We should wrap for things that are not plain text, and for things that would definitely
        # not be a JSON Schema object.
        self._is_wrapped = not _is_subclass_of_base_model_or_dict(output_type)

        if self._is_wrapped:
            OutputType = TypedDict(
                "OutputType",
                {
                    _WRAPPER_DICT_KEY: output_type,  # type: ignore
                },
            )
            self._type_adapter = TypeAdapter(OutputType)
            self._output_schema = self._type_adapter.json_schema()
        else:
            self._type_adapter = TypeAdapter(output_type)
            self._output_schema = self._type_adapter.json_schema()

        if self._strict_json_schema:
            try:
                self._output_schema = ensure_strict_json_schema(self._output_schema)
            except UserError as e:
                raise UserError(
                    "Strict JSON schema is enabled, but the output type is not valid. "
                    "Either make the output type strict, "
                    "or wrap your type with AgentOutputSchema(YourType, strict_json_schema=False)"
                ) from e

    def is_plain_text(self) -> bool:
        """Whether the output type is plain text (versus a JSON object)."""
        return self.output_type is None or self.output_type is str

    def is_strict_json_schema(self) -> bool:
        """Whether the JSON schema is in strict mode."""
        return self._strict_json_schema

    def json_schema(self) -> dict[str, Any]:
        """The JSON schema of the output type."""
        if self.is_plain_text():
            raise UserError("Output type is plain text, so no JSON schema is available")
        return self._output_schema

    def validate_json(self, json_str: str) -> Any:
        """Validate a JSON string against the output type. Returns the validated object, or raises
        a `ModelBehaviorError` if the JSON is invalid.
        """
        validated = _json.validate_json(json_str, self._type_adapter, partial=False)
        if self._is_wrapped:
            if not isinstance(validated, dict):
                _error_tracing.attach_error_to_current_span(
                    SpanError(
                        message="Invalid JSON",
                        data={"details": f"Expected a dict, got {type(validated)}"},
                    )
                )
                raise ModelBehaviorError(
                    f"Expected a dict, got {type(validated)} for JSON: {json_str}"
                )

            if _WRAPPER_DICT_KEY not in validated:
                _error_tracing.attach_error_to_current_span(
                    SpanError(
                        message="Invalid JSON",
                        data={"details": f"Could not find key {_WRAPPER_DICT_KEY} in JSON"},
                    )
                )
                raise ModelBehaviorError(
                    f"Could not find key {_WRAPPER_DICT_KEY} in JSON: {json_str}"
                )
            return validated[_WRAPPER_DICT_KEY]
        return validated

    def name(self) -> str:
        """The name of the output type."""
        return _type_to_str(self.output_type)

output_type instance-attribute 

output_type: type[Any] = output_type

输出的类型。

__init__ 

__init__(
    output_type: type[Any], strict_json_schema: bool = True
)

参数

名称 类型 描述 默认
output_type type[Any]

输出的类型。

 required
strict_json_schema bool

JSON 模式是否处于严格模式。我们强烈建议将其设置为 True，因为它会增加生成正确 JSON 输入的可能性。

 True
源代码位于 src/agents/agent_output.py 
 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
116
117
118
119
120
def __init__(self, output_type: type[Any], strict_json_schema: bool = True):
    """
    Args:
        output_type: The type of the output.
        strict_json_schema: Whether the JSON schema is in strict mode. We **strongly** recommend
            setting this to True, as it increases the likelihood of correct JSON input.
    """
    self.output_type = output_type
    self._strict_json_schema = strict_json_schema

    if output_type is None or output_type is str:
        self._is_wrapped = False
        self._type_adapter = TypeAdapter(output_type)
        self._output_schema = self._type_adapter.json_schema()
        return

    # We should wrap for things that are not plain text, and for things that would definitely
    # not be a JSON Schema object.
    self._is_wrapped = not _is_subclass_of_base_model_or_dict(output_type)

    if self._is_wrapped:
        OutputType = TypedDict(
            "OutputType",
            {
                _WRAPPER_DICT_KEY: output_type,  # type: ignore
            },
        )
        self._type_adapter = TypeAdapter(OutputType)
        self._output_schema = self._type_adapter.json_schema()
    else:
        self._type_adapter = TypeAdapter(output_type)
        self._output_schema = self._type_adapter.json_schema()

    if self._strict_json_schema:
        try:
            self._output_schema = ensure_strict_json_schema(self._output_schema)
        except UserError as e:
            raise UserError(
                "Strict JSON schema is enabled, but the output type is not valid. "
                "Either make the output type strict, "
                "or wrap your type with AgentOutputSchema(YourType, strict_json_schema=False)"
            ) from e

is_plain_text 

is_plain_text() -> bool

输出类型是否为纯文本（而非 JSON 对象）。

源代码位于 src/agents/agent_output.py 
122
123
124
def is_plain_text(self) -> bool:
    """Whether the output type is plain text (versus a JSON object)."""
    return self.output_type is None or self.output_type is str

is_strict_json_schema 

is_strict_json_schema() -> bool

JSON schema 是否处于严格模式。

源代码位于 src/agents/agent_output.py 
126
127
128
def is_strict_json_schema(self) -> bool:
    """Whether the JSON schema is in strict mode."""
    return self._strict_json_schema

json_schema 

json_schema() -> dict[str, Any]

输出类型的 JSON schema。

源代码位于 src/agents/agent_output.py 
130
131
132
133
134
def json_schema(self) -> dict[str, Any]:
    """The JSON schema of the output type."""
    if self.is_plain_text():
        raise UserError("Output type is plain text, so no JSON schema is available")
    return self._output_schema

validate_json 

validate_json(json_str: str) -> Any

根据输出类型验证 JSON 字符串。返回验证后的对象，或者如果 JSON 无效则引发 ModelBehaviorError。

源代码位于 src/agents/agent_output.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def validate_json(self, json_str: str) -> Any:
    """Validate a JSON string against the output type. Returns the validated object, or raises
    a `ModelBehaviorError` if the JSON is invalid.
    """
    validated = _json.validate_json(json_str, self._type_adapter, partial=False)
    if self._is_wrapped:
        if not isinstance(validated, dict):
            _error_tracing.attach_error_to_current_span(
                SpanError(
                    message="Invalid JSON",
                    data={"details": f"Expected a dict, got {type(validated)}"},
                )
            )
            raise ModelBehaviorError(
                f"Expected a dict, got {type(validated)} for JSON: {json_str}"
            )

        if _WRAPPER_DICT_KEY not in validated:
            _error_tracing.attach_error_to_current_span(
                SpanError(
                    message="Invalid JSON",
                    data={"details": f"Could not find key {_WRAPPER_DICT_KEY} in JSON"},
                )
            )
            raise ModelBehaviorError(
                f"Could not find key {_WRAPPER_DICT_KEY} in JSON: {json_str}"
            )
        return validated[_WRAPPER_DICT_KEY]
    return validated

name 

name() -> str

输出类型的名称。

源代码位于 src/agents/agent_output.py 
166
167
168
def name(self) -> str:
    """The name of the output type."""
    return _type_to_str(self.output_type)