diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/function-callback.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/function-callback.adoc index 2ad3bfdaa..4b88740a4 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/function-callback.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/function-callback.adoc @@ -1,12 +1,8 @@ = FunctionCallback -== Overview - The `FunctionCallback` interface in Spring AI provides a standardized way to implement Large Language Model (LLM) function calling capabilities. It allows developers to register custom functions that can be called by AI models when specific conditions or intents are detected in the prompts. -== FunctionCallback Interface - -The main interface defines several key methods: +The `FunctionCallback` interface defines several key methods: * `getName()`: Returns the unique function name within the AI model context * `getDescription()`: Provides a description that helps the model decide when to invoke the function @@ -16,19 +12,24 @@ The main interface defines several key methods: == Builder Pattern -Spring AI provides a fluent builder API for creating `FunctionCallback` implementations. - +Spring AI provides a fluent builder API for creating `FunctionCallback` implementations. This is particularly useful for defining function callbacks that you can register, pragmatically, on the fly, with your `ChatClient` or `ChatModel` model calls. -The builders helps with complex configurations, such as custom response handling, schema types (e.g. JSONSchema or OpenAPI), and object mapping. +Use the `FunctionCallback.builder()` method to create a new builder instance and chain the configuration methods to set the function name, description, input type, and other properties. +The `FunctionCallback.Builder` is a hierarchical with the following structure: -=== Function-Invoking Approach +- FunctionCallback.Builder - The root builder interface used for configuring the xref:_common_configurations[shared properties]. +- FunctionInvokingSpec - The xref:Function-Invoking[function invoking] builder interface. +- MethodInvokingSpec - The xref:Method-Invoking[method invoking] builder interface. + +[[Function-Invoking]] +== Function-Invoking Approach Converts any `java.util.function.Function`, `BiFunction`, `Supplier` or `Consumer` into a `FunctionCallback` that can be called by the AI model. NOTE: You can use lambda expressions or method references to define the function logic but you must provide the input type of the function using the `inputType(TYPE)`. -==== Function +=== Function [source,java] ---- @@ -39,7 +40,7 @@ FunctionCallback callback = FunctionCallback.builder() .build(); ---- -==== BiFunction +=== BiFunction Using Function with input type and additional xref:api/functions.adoc#Tool-Context[ToolContext] parameter: @@ -53,7 +54,7 @@ FunctionCallback callback = FunctionCallback.builder() .build(); ---- -==== Supplier +=== Supplier Use `java.util.Supplier` or `java.util.function.Function` to define functions that don't take any input: @@ -66,7 +67,7 @@ FunctionCallback.builder() .build(); ---- -==== Consumer +=== Consumer Use `java.util.Consumer` or `java.util.function.Function` to define functions that don't produce output: @@ -83,7 +84,7 @@ FunctionCallback.builder() .build(); ---- -==== Generics Input Type +=== Generics Input Type Use the `ParameterizedTypeReference` to define functions with generic input types: @@ -105,7 +106,8 @@ FunctionCallback.builder() .build(); ---- -=== Method Invoking Approach +[[Method-Invoking]] +== Method Invoking Approach Enables method invocation through reflection while automatically handling JSON schema generation and parameter conversion. It’s particularly useful for integrating Java methods as callable functions within AI model interactions. @@ -117,7 +119,7 @@ The method invoking implements the `FunctionCallback` interface and provides: - Any parameter/return types (primitives, objects, collections) - Special handling for xref:api/functions.adoc#Tool-Context[ToolContext] parameters -==== Static Method Invocation +=== Static Method Invocation You can refer to a static method in a class by providing the method name, parameter types, and the target class. @@ -136,7 +138,7 @@ FunctionCallback callback = FunctionCallback.builder() .build(); ---- -==== Object instance Method Invocation +=== Object instance Method Invocation You can refer to an instance method in a class by providing the method name, parameter types, and the target object instance. @@ -236,20 +238,19 @@ FunctionCallback.builder() * Use xref:api/functions.adoc#Tool-Context[ToolContext] when additional state or context is required that is provided from the User and not part of the function input generated by the AI model. * Use `BiFunction` to access the ToolContext in the function invocation approach and add `ToolContext` parameter in the method invoking approach. - -== Notes on Schema Generation +=== Notes on Schema Generation * The framework automatically generates JSON schemas from Java types * For function invoking, the schema is generated based on the input type for the function that needs to be set using `inputType(TYPE)`. Use `ParameterizedTypeReference` for generic types. * Generated schemas respect Jackson annotations on model classes * You can bypass the automatic generation by providing custom schemas using `inputTypeSchema()` -== Common Pitfalls to Avoid +=== Common Pitfalls to Avoid -=== Lack of Description +==== Lack of Description * Always provide explicit descriptions instead of relying on auto-generated ones * Clear descriptions improve model's function selection accuracy -=== Schema Mismatches +==== Schema Mismatches * Ensure input types match the Function's input parameter types. * Use `ParameterizedTypeReference` for generic types.