Guardrails

GuardrailFunctionOutput dataclass

guardrail 函数的输出。

Source code in agents/guardrail.py

@dataclass
class GuardrailFunctionOutput:
    """guardrail 函数的输出。"""

    output_info: Any
    """
    关于 guardrail 输出的可选信息。例如，guardrail 可以包含它执行的检查和细粒度结果的信息。
    """

    tripwire_triggered: bool
    """
    是否触发了 tripwire。如果被触发，agent 的执行将会被中止。
    """

output_info instance-attribute

output_info: Any

关于 guardrail 输出的可选信息。例如，guardrail 可以包含它执行的检查和细粒度结果的信息。

tripwire_triggered instance-attribute

tripwire_triggered: bool

是否触发了 tripwire。如果被触发，agent 的执行将会被中止。

InputGuardrailResult dataclass

guardrail 执行的结果。

Source code in agents/guardrail.py

@dataclass
class InputGuardrailResult:
    """guardrail 执行的结果。"""

    guardrail: InputGuardrail[Any]
    """
    被执行的 guardrail。
    """

    output: GuardrailFunctionOutput
    """guardrail 函数的输出。"""

guardrail instance-attribute

guardrail: InputGuardrail[Any]

被执行的 guardrail。

output instance-attribute

output: GuardrailFunctionOutput

guardrail 函数的输出。

OutputGuardrailResult dataclass

guardrail 执行的结果。

Source code in agents/guardrail.py

@dataclass
class OutputGuardrailResult:
    """guardrail 执行的结果。"""

    guardrail: OutputGuardrail[Any]
    """
    被执行的 guardrail。
    """

    agent_output: Any
    """
    被 guardrail 检查的 agent 输出。
    """

    agent: Agent[Any]
    """
    被 guardrail 检查的 agent。
    """

    output: GuardrailFunctionOutput
    """guardrail 函数的输出。"""

guardrail instance-attribute

guardrail: OutputGuardrail[Any]

被执行的 guardrail。

agent_output instance-attribute

agent_output: Any

被 guardrail 检查的 agent 输出。

agent instance-attribute

agent: Agent[Any]

被 guardrail 检查的 agent。

output instance-attribute

output: GuardrailFunctionOutput

guardrail 函数的输出。

InputGuardrail dataclass

Bases: Generic[TContext]

输入 guardrail 是与 agent 执行并行运行的检查。 它们可以用于如下场景： - 检查输入消息是否偏离主题 - 如果检测到意外输入，则接管 agent 的执行控制

你可以使用 @input_guardrail() 装饰器将函数转换为 InputGuardrail，或者手动创建一个 InputGuardrail。

guardrail 返回一个 GuardrailResult。如果 result.tripwire_triggered 为 True，agent 的执行将会立即停止，并抛出 InputGuardrailTripwireTriggered 异常。

Source code in agents/guardrail.py

@dataclass
class InputGuardrail(Generic[TContext]):
    """输入 guardrail 是与 agent 执行并行运行的检查。
    它们可以用于如下场景：
    - 检查输入消息是否偏离主题
    - 如果检测到意外输入，则接管 agent 的执行控制

    你可以使用 `@input_guardrail()` 装饰器将函数转换为 `InputGuardrail`，或者手动创建一个 `InputGuardrail`。

    guardrail 返回一个 `GuardrailResult`。如果 `result.tripwire_triggered` 为 `True`，agent
    的执行将会立即停止，并抛出 `InputGuardrailTripwireTriggered` 异常。
    """

    guardrail_function: Callable[
        [RunContextWrapper[TContext], Agent[Any], str | list[TResponseInputItem]],
        MaybeAwaitable[GuardrailFunctionOutput],
    ]
    """一个接收 agent 输入和上下文的函数，并返回
     `GuardrailResult`。结果标记 tripwire 是否被触发，并可选地包含 guardrail 输出的信息。
    """

    name: str | None = None
    """guardrail 的名称，用于追踪。如果未提供，将使用 guardrail
    函数的名称。
    """

    def get_name(self) -> str:
        if self.name:
            return self.name

        return self.guardrail_function.__name__

    async def run(
        self,
        agent: Agent[Any],
        input: str | list[TResponseInputItem],
        context: RunContextWrapper[TContext],
    ) -> InputGuardrailResult:
        if not callable(self.guardrail_function):
            raise UserError(f"Guardrail function must be callable, got {self.guardrail_function}")

        output = self.guardrail_function(context, agent, input)
        if inspect.isawaitable(output):
            return InputGuardrailResult(
                guardrail=self,
                output=await output,
            )

        return InputGuardrailResult(
            guardrail=self,
            output=output,
        )

guardrail_function instance-attribute

guardrail_function: Callable[[RunContextWrapper[TContext], Agent[Any], str | list[TResponseInputItem]], MaybeAwaitable[GuardrailFunctionOutput]]

一个接收 agent 输入和上下文的函数，并返回 GuardrailResult。结果标记 tripwire 是否被触发，并可选地包含 guardrail 输出的信息。

name class-attribute instance-attribute

name: str | None = None

guardrail 的名称，用于追踪。如果未提供，将使用 guardrail 函数的名称。

OutputGuardrail dataclass

Bases: Generic[TContext]

输出 guardrail 是在 agent 最终输出上运行的检查。 它们可以用于检查输出是否通过某些验证标准。

你可以使用 @output_guardrail() 装饰器将函数转换为 OutputGuardrail， 或者手动创建一个 OutputGuardrail。

guardrail 返回一个 GuardrailResult。如果 result.tripwire_triggered 为 True， 将抛出 OutputGuardrailTripwireTriggered 异常。

Source code in agents/guardrail.py

@dataclass
class OutputGuardrail(Generic[TContext]):
    """输出 guardrail 是在 agent 最终输出上运行的检查。
    它们可以用于检查输出是否通过某些验证标准。

    你可以使用 `@output_guardrail()` 装饰器将函数转换为 `OutputGuardrail`，
    或者手动创建一个 `OutputGuardrail`。

    guardrail 返回一个 `GuardrailResult`。如果 `result.tripwire_triggered` 为 `True`，
    将抛出 `OutputGuardrailTripwireTriggered` 异常。
    """

    guardrail_function: Callable[
        [RunContextWrapper[TContext], Agent[Any], Any],
        MaybeAwaitable[GuardrailFunctionOutput],
    ]
    """一个接收最终 agent、其输出和上下文的函数，并返回
     `GuardrailResult`。结果标记 tripwire 是否被触发，并可选地包含 guardrail 输出的信息。
    """

    name: str | None = None
    """guardrail 的名称，用于追踪。如果未提供，将使用 guardrail
    函数的名称。
    """

    def get_name(self) -> str:
        if self.name:
            return self.name

        return self.guardrail_function.__name__

    async def run(
        self, context: RunContextWrapper[TContext], agent: Agent[Any], agent_output: Any
    ) -> OutputGuardrailResult:
        if not callable(self.guardrail_function):
            raise UserError(f"Guardrail function must be callable, got {self.guardrail_function}")

        output = self.guardrail_function(context, agent, agent_output)
        if inspect.isawaitable(output):
            return OutputGuardrailResult(
                guardrail=self,
                agent=agent,
                agent_output=agent_output,
                output=await output,
            )

        return OutputGuardrailResult(
            guardrail=self,
            agent=agent,
            agent_output=agent_output,
            output=output,
        )

guardrail_function instance-attribute

guardrail_function: Callable[[RunContextWrapper[TContext], Agent[Any], Any], MaybeAwaitable[GuardrailFunctionOutput]]

一个接收最终 agent、其输出和上下文的函数，并返回 GuardrailResult。结果标记 tripwire 是否被触发，并可选地包含 guardrail 输出的信息。

name class-attribute instance-attribute

name: str | None = None

guardrail 的名称，用于追踪。如果未提供，将使用 guardrail 函数的名称。

input_guardrail

input_guardrail(func: _InputGuardrailFuncSync[TContext_co]) -> InputGuardrail[TContext_co]

input_guardrail(func: _InputGuardrailFuncAsync[TContext_co]) -> InputGuardrail[TContext_co]

input_guardrail(*, name: str | None = None) -> Callable[[_InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co]], InputGuardrail[TContext_co]]

input_guardrail(func: _InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co] | None = None, *, name: str | None = None) -> InputGuardrail[TContext_co] | Callable[[_InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co]], InputGuardrail[TContext_co]]

装饰器，将同步或异步函数转换为 InputGuardrail。 可以直接使用（无括号），也可以带关键字参数使用，例如：

@input_guardrail
def my_sync_guardrail(...): ...

@input_guardrail(name="guardrail_name")
async def my_async_guardrail(...): ...

Source code in agents/guardrail.py

def input_guardrail(
    func: _InputGuardrailFuncSync[TContext_co]
    | _InputGuardrailFuncAsync[TContext_co]
    | None = None,
    *,
    name: str | None = None,
) -> (
    InputGuardrail[TContext_co]
    | Callable[
        [_InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co]],
        InputGuardrail[TContext_co],
    ]
):
    """
    装饰器，将同步或异步函数转换为 `InputGuardrail`。
    可以直接使用（无括号），也可以带关键字参数使用，例如：

        @input_guardrail
        def my_sync_guardrail(...): ...

        @input_guardrail(name="guardrail_name")
        async def my_async_guardrail(...): ...
    """

    def decorator(
        f: _InputGuardrailFuncSync[TContext_co] | _InputGuardrailFuncAsync[TContext_co],
    ) -> InputGuardrail[TContext_co]:
        return InputGuardrail(guardrail_function=f, name=name)

    if func is not None:
        # Decorator was used without parentheses
        return decorator(func)

    # Decorator used with keyword arguments
    return decorator

output_guardrail

output_guardrail(func: _OutputGuardrailFuncSync[TContext_co]) -> OutputGuardrail[TContext_co]

output_guardrail(func: _OutputGuardrailFuncAsync[TContext_co]) -> OutputGuardrail[TContext_co]

output_guardrail(*, name: str | None = None) -> Callable[[_OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co]], OutputGuardrail[TContext_co]]

output_guardrail(func: _OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co] | None = None, *, name: str | None = None) -> OutputGuardrail[TContext_co] | Callable[[_OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co]], OutputGuardrail[TContext_co]]

装饰器，将同步或异步函数转换为 OutputGuardrail。 可以直接使用（无括号），也可以带关键字参数使用，例如：

@output_guardrail
def my_sync_guardrail(...): ...

@output_guardrail(name="guardrail_name")
async def my_async_guardrail(...): ...

Source code in agents/guardrail.py

def output_guardrail(
    func: _OutputGuardrailFuncSync[TContext_co]
    | _OutputGuardrailFuncAsync[TContext_co]
    | None = None,
    *,
    name: str | None = None,
) -> (
    OutputGuardrail[TContext_co]
    | Callable[
        [_OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co]],
        OutputGuardrail[TContext_co],
    ]
):
    """
    装饰器，将同步或异步函数转换为 `OutputGuardrail`。
    可以直接使用（无括号），也可以带关键字参数使用，例如：

        @output_guardrail
        def my_sync_guardrail(...): ...

        @output_guardrail(name="guardrail_name")
        async def my_async_guardrail(...): ...
    """

    def decorator(
        f: _OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co],
    ) -> OutputGuardrail[TContext_co]:
        return OutputGuardrail(guardrail_function=f, name=name)

    if func is not None:
        # Decorator was used without parentheses
        return decorator(func)

    # Decorator used with keyword arguments
    return decorator