Annotation Interface OutputGuardrails


@Documented @Retention(RUNTIME) @Target({TYPE,METHOD}) public @interface OutputGuardrails
An annotation to apply guardrails to the output of the model using the declarative AiServices approach.

An output guardrail is a rule that is applied to the output of the model to ensure that the output is safe and meets certain expectations.

When a validation fails, the result can indicate whether the request should be retried as-is, or to provide a reprompt message to append to the prompt.

In the case of re-prompting, the reprompt message is added to the LLM context and the request is then retried.

If the annotation is present on a class, the guardrails will be applied to all the methods of the class. An annotation on a method takes precedence over one on the class: for that method, it replaces the annotation on the class as a whole, including its maxRetries(), and the two are not combined. Output guardrails set on the AiServices builder take precedence over the guardrails of both: they replace the guardrails of these annotations, and are not combined with them either. Passing null or an empty list of output guardrails to the builder does not disable these annotations.

The guardrails and their configuration are resolved independently of each other. An output guardrails configuration set on the builder takes precedence over the maxRetries() of these annotations. When only output guardrails, and no configuration, are set on the builder, the maxRetries() of these annotations still applies to the guardrails set on the builder.

When several guardrails are applied, the order of the guardrails is important, as the guardrails are applied in the order they are listed.

When several OutputGuardrails are applied, if any guardrail forces a retry or reprompt, then all of the guardrails will be re-applied to the new response.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    Class<? extends OutputGuardrail>[]
    The ordered list of guardrails to apply to the output of the model.
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    The maximum number of times the output guardrails validate a response of the model, including the first one: at most maxRetries - 1 retries or reprompts.
  • Element Details

    • value

      Class<? extends OutputGuardrail>[] value
      The ordered list of guardrails to apply to the output of the model.

      The order of the classes is important as the guardrails are applied in the order they are listed. Guardrails can not be present twice in the list.

    • maxRetries

      int maxRetries
      The maximum number of times the output guardrails validate a response of the model, including the first one: at most maxRetries - 1 retries or reprompts.

      Set to 0 or 1 to disable retries. A negative value uses OutputGuardrailsConfig.MAX_RETRIES_DEFAULT.

      See Also:
      Default:
      2