feat(ai): Automatic function calling (#9489)

Author: hsubox76

.changeset/cool-bulldogs-impress.md

@@ -0,0 +1,6 @@
+---
+'@firebase/ai': minor
+'firebase': minor
+---
+
+Added automatic function calling capability when using `ChatSession`.

common/api-review/ai.api.md

@@ -143,6 +143,12 @@ export class BooleanSchema extends Schema {
 export class ChatSession {
     // Warning: (ae-incompatible-release-tags) The symbol "__constructor" is marked as @public, but its signature references "ChromeAdapter" which is marked as @beta
     constructor(apiSettings: ApiSettings, model: string, chromeAdapter?: ChromeAdapter | undefined, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
+    // @internal
+    _callFunctionsAsNeeded(functionCalls: FunctionCall[]): Promise<FunctionResponsePart[]>;
+    // @internal
+    _formatRequest(incomingContent: Content, tempHistory: Content[]): GenerateContentRequest;
+    // @internal
+    _getCallableFunctionCalls(response?: GenerateContentResponse): FunctionCall[] | undefined;
     getHistory(): Promise<Content[]>;
     // (undocumented)
     model: string;
@@ -407,6 +413,7 @@ export interface FunctionCallPart {
 // @public
 export interface FunctionDeclaration {
     description: string;
+    functionReference?: Function;
     name: string;
     parameters?: ObjectSchema | ObjectSchemaRequest;
 }
@@ -422,6 +429,8 @@ export interface FunctionResponse {
     // (undocumented)
     name: string;
     // (undocumented)
+    parts?: Part[];
+    // (undocumented)
     response: object;
 }
 
@@ -1145,6 +1154,7 @@ export interface PromptFeedback {
 // @public
 export interface RequestOptions {
     baseUrl?: string;
+    maxSequentalFunctionCalls?: number;
     timeout?: number;
 }
 

docs-devsite/ai.functiondeclaration.md

@@ -23,6 +23,7 @@ export interface FunctionDeclaration
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [description](./ai.functiondeclaration.md#functiondeclarationdescription) | string | Description and purpose of the function. Model uses it to decide how and whether to call the function. |
+|  [functionReference](./ai.functiondeclaration.md#functiondeclarationfunctionreference) | Function | Reference to an actual function to call. Specifying this will cause the function to be called automatically when requested by the model. |
 |  [name](./ai.functiondeclaration.md#functiondeclarationname) | string | The name of the function to call. Must start with a letter or an underscore. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a max length of 64. |
 |  [parameters](./ai.functiondeclaration.md#functiondeclarationparameters) | [ObjectSchema](./ai.objectschema.md#objectschema_class) \| [ObjectSchemaRequest](./ai.objectschemarequest.md#objectschemarequest_interface) | Optional. Describes the parameters to this function in JSON Schema Object format. Reflects the Open API 3.03 Parameter Object. Parameter names are case-sensitive. For a function with no parameters, this can be left unset. |
 
@@ -36,6 +37,16 @@ Description and purpose of the function. Model uses it to decide how and whether
 description: string;
 ```
 
+## FunctionDeclaration.functionReference
+
+Reference to an actual function to call. Specifying this will cause the function to be called automatically when requested by the model.
+
+<b>Signature:</b>
+
+```typescript
+functionReference?: Function;
+```
+
 ## FunctionDeclaration.name
 
 The name of the function to call. Must start with a letter or an underscore. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a max length of 64.

docs-devsite/ai.functionresponse.md

@@ -24,6 +24,7 @@ export interface FunctionResponse
 |  --- | --- | --- |
 |  [id](./ai.functionresponse.md#functionresponseid) | string | The id of the [FunctionCall](./ai.functioncall.md#functioncall_interface)<!-- -->. |
 |  [name](./ai.functionresponse.md#functionresponsename) | string |  |
+|  [parts](./ai.functionresponse.md#functionresponseparts) | [Part](./ai.md#part)<!-- -->\[\] |  |
 |  [response](./ai.functionresponse.md#functionresponseresponse) | object |  |
 
 ## FunctionResponse.id
@@ -46,6 +47,14 @@ id?: string;
 name: string;
 ```
 
+## FunctionResponse.parts
+
+<b>Signature:</b>
+
+```typescript
+parts?: Part[];
+```
+
 ## FunctionResponse.response
 
 <b>Signature:</b>

docs-devsite/ai.requestoptions.md

@@ -23,6 +23,7 @@ export interface RequestOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [baseUrl](./ai.requestoptions.md#requestoptionsbaseurl) | string | Base url for endpoint. Defaults to https://firebasevertexai.googleapis.com, which is the [Firebase AI Logic API](https://console.cloud.google.com/apis/library/firebasevertexai.googleapis.com?project=_) (used regardless of your chosen Gemini API provider). |
+|  [maxSequentalFunctionCalls](./ai.requestoptions.md#requestoptionsmaxsequentalfunctioncalls) | number | Limits amount of sequential function calls the SDK can make during automatic function calling, in order to prevent infinite loops. If not specified, this value defaults to 10.<!-- -->When it reaches this limit, it will return the last response received from the model, whether it is a text response or further function calls. |
 |  [timeout](./ai.requestoptions.md#requestoptionstimeout) | number | Request timeout in milliseconds. Defaults to 180 seconds (180000ms). |
 
 ## RequestOptions.baseUrl
@@ -35,6 +36,18 @@ Base url for endpoint. Defaults to https://firebasevertexai.googleapis.com, whic
 baseUrl?: string;
 ```
 
+## RequestOptions.maxSequentalFunctionCalls
+
+Limits amount of sequential function calls the SDK can make during automatic function calling, in order to prevent infinite loops. If not specified, this value defaults to 10.
+
+When it reaches this limit, it will return the last response received from the model, whether it is a text response or further function calls.
+
+<b>Signature:</b>
+
+```typescript
+maxSequentalFunctionCalls?: number;
+```
+
 ## RequestOptions.timeout
 
 Request timeout in milliseconds. Defaults to 180 seconds (180000ms).