feat(ai): add support for URL context

.changeset/poor-rings-admire.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/ai': minor
+---
+
+Add support for the URL Context tool.

common/api-review/ai.api.md

@@ -448,6 +448,8 @@ export interface GenerateContentCandidate {
     index: number;
     // (undocumented)
     safetyRatings?: SafetyRating[];
+    // (undocumented)
+    urlContextMetadata?: URLContextMetadata;
 }
 
 // @public
@@ -596,6 +598,8 @@ export interface GoogleAIGenerateContentCandidate {
     index: number;
     // (undocumented)
     safetyRatings?: SafetyRating[];
+    // (undocumented)
+    urlContextMetadata?: URLContextMetadata;
 }
 
 // Warning: (ae-internal-missing-underscore) The name "GoogleAIGenerateContentResponse" should be prefixed with an underscore because the declaration is marked as @internal
@@ -1301,7 +1305,7 @@ export interface ThinkingConfig {
 }
 
 // @public
-export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool;
+export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 
 // @public
 export interface ToolConfig {
@@ -1312,6 +1316,38 @@ export interface ToolConfig {
 // @public
 export type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;
 
+// @public
+export interface URLContext {
+}
+
+// @public
+export interface URLContextMetadata {
+    urlMetadata: URLMetadata[];
+}
+
+// @public
+export interface URLContextTool {
+    urlContext: URLContext;
+}
+
+// @public
+export interface URLMetadata {
+    retrievedUrl?: string;
+    urlRetrievalStatus?: URLRetrievalStatus;
+}
+
+// @public
+export const URLRetrievalStatus: {
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: string;
+    URL_RETRIEVAL_STATUS_SUCCESS: string;
+    URL_RETRIEVAL_STATUS_ERROR: string;
+    URL_RETRIEVAL_STATUS_PAYWALL: string;
+    URL_RETRIEVAL_STATUS_UNSAFE: string;
+};
+
+// @public
+export type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRetrievalStatus];
+
 // @public
 export interface UsageMetadata {
     // (undocumented)
@@ -1323,6 +1359,8 @@ export interface UsageMetadata {
     // (undocumented)
     promptTokensDetails?: ModalityTokenCount[];
     thoughtsTokenCount?: number;
+    toolUsePromptTokenCount?: number;
+    toolUsePromptTokensDetails?: ModalityTokenCount[];
     // (undocumented)
     totalTokenCount: number;
 }

docs-devsite/_toc.yaml

@@ -202,6 +202,14 @@ toc:
     path: /docs/reference/js/ai.thinkingconfig.md
   - title: ToolConfig
     path: /docs/reference/js/ai.toolconfig.md
+  - title: URLContext
+    path: /docs/reference/js/ai.urlcontext.md
+  - title: URLContextMetadata
+    path: /docs/reference/js/ai.urlcontextmetadata.md
+  - title: URLContextTool
+    path: /docs/reference/js/ai.urlcontexttool.md
+  - title: URLMetadata
+    path: /docs/reference/js/ai.urlmetadata.md
   - title: UsageMetadata
     path: /docs/reference/js/ai.usagemetadata.md
   - title: VertexAIBackend

docs-devsite/ai.generatecontentcandidate.md

@@ -29,6 +29,7 @@ export interface GenerateContentCandidate
 |  [groundingMetadata](./ai.generatecontentcandidate.md#generatecontentcandidategroundingmetadata) | [GroundingMetadata](./ai.groundingmetadata.md#groundingmetadata_interface) |  |
 |  [index](./ai.generatecontentcandidate.md#generatecontentcandidateindex) | number |  |
 |  [safetyRatings](./ai.generatecontentcandidate.md#generatecontentcandidatesafetyratings) | [SafetyRating](./ai.safetyrating.md#safetyrating_interface)<!-- -->\[\] |  |
+|  [urlContextMetadata](./ai.generatecontentcandidate.md#generatecontentcandidateurlcontextmetadata) | [URLContextMetadata](./ai.urlcontextmetadata.md#urlcontextmetadata_interface) |  |
 
 ## GenerateContentCandidate.citationMetadata
 
@@ -85,3 +86,11 @@ index: number;
 ```typescript
 safetyRatings?: SafetyRating[];
 ```
+
+## GenerateContentCandidate.urlContextMetadata
+
+<b>Signature:</b>
+
+```typescript
+urlContextMetadata?: URLContextMetadata;
+```

docs-devsite/ai.md

@@ -134,6 +134,10 @@ The Firebase AI Web SDK.
 |  [TextPart](./ai.textpart.md#textpart_interface) | Content part interface if the part represents a text string. |
 |  [ThinkingConfig](./ai.thinkingconfig.md#thinkingconfig_interface) | Configuration for "thinking" behavior of compatible Gemini models.<!-- -->Certain models utilize a thinking process before generating a response. This allows them to reason through complex problems and plan a more coherent and accurate answer. |
 |  [ToolConfig](./ai.toolconfig.md#toolconfig_interface) | Tool config. This config is shared for all tools provided in the request. |
+|  [URLContext](./ai.urlcontext.md#urlcontext_interface) | Specifies the URL Context configuration. |
+|  [URLContextMetadata](./ai.urlcontextmetadata.md#urlcontextmetadata_interface) | Metadata related to [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface)<!-- -->. |
+|  [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface) | A tool that allows you to provide additional context to the models in the form of URLs. By including URLs in your request, the Gemini model will access the content from those pages to inform and enhance its response. |
+|  [URLMetadata](./ai.urlmetadata.md#urlmetadata_interface) | Metadata for a URL that was used to provide context to the Gemini model. |
 |  [UsageMetadata](./ai.usagemetadata.md#usagemetadata_interface) | Usage metadata about a [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->. |
 |  [VideoMetadata](./ai.videometadata.md#videometadata_interface) | Describes the input video content. |
 |  [VoiceConfig](./ai.voiceconfig.md#voiceconfig_interface) | <b><i>(Public Preview)</i></b> Configuration for the voice to used in speech synthesis. |
@@ -165,6 +169,7 @@ The Firebase AI Web SDK.
 |  [POSSIBLE\_ROLES](./ai.md#possible_roles) | Possible roles. |
 |  [ResponseModality](./ai.md#responsemodality) | <b><i>(Public Preview)</i></b> Generation modalities to be returned in generation responses. |
 |  [SchemaType](./ai.md#schematype) | Contains the list of OpenAPI data types as defined by the [OpenAPI specification](https://swagger.io/docs/specification/data-models/data-types/) |
+|  [URLRetrievalStatus](./ai.md#urlretrievalstatus) | The status of a URL retrieval. |
 
 ## Type Aliases
 
@@ -197,6 +202,7 @@ The Firebase AI Web SDK.
 |  [SchemaType](./ai.md#schematype) | Contains the list of OpenAPI data types as defined by the [OpenAPI specification](https://swagger.io/docs/specification/data-models/data-types/) |
 |  [Tool](./ai.md#tool) | Defines a tool that model can call to access external knowledge. |
 |  [TypedSchema](./ai.md#typedschema) | A type that includes all specific Schema types. |
+|  [URLRetrievalStatus](./ai.md#urlretrievalstatus) | The status of a URL retrieval. |
 
 ## function(app, ...)
 
@@ -752,6 +758,22 @@ SchemaType: {
 }
 ```
 
+## URLRetrievalStatus
+
+The status of a URL retrieval.
+
+<b>Signature:</b>
+
+```typescript
+URLRetrievalStatus: {
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: string;
+    URL_RETRIEVAL_STATUS_SUCCESS: string;
+    URL_RETRIEVAL_STATUS_ERROR: string;
+    URL_RETRIEVAL_STATUS_PAYWALL: string;
+    URL_RETRIEVAL_STATUS_UNSAFE: string;
+}
+```
+
 ## AIErrorCode
 
 Standardized error codes that [AIError](./ai.aierror.md#aierror_class) can have.
@@ -1031,7 +1053,7 @@ Defines a tool that model can call to access external knowledge.
 <b>Signature:</b>
 
 ```typescript
-export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool;
+export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 ```
 
 ## TypedSchema
@@ -1043,3 +1065,15 @@ A type that includes all specific Schema types.
 ```typescript
 export type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;
 ```
+
+## URLRetrievalStatus
+
+The status of a URL retrieval.
+
+<b>URL\_RETRIEVAL\_STATUS\_UNSPECIFIED:</b> Unspecified retrieval status. <br/> <b>URL\_RETRIEVAL\_STATUS\_SUCCESS:</b> The URL retrieval was successful. <br/> <b>URL\_RETRIEVAL\_STATUS\_ERROR:</b> The URL retrieval failed due to an error. <br/> <b>URL\_RETRIEVAL\_STATUS\_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall. <br/> <b>URL\_RETRIEVAL\_STATUS\_UNSAFE:</b> The URL retrieval failed because the content is unsafe. <br/>
+
+<b>Signature:</b>
+
+```typescript
+export type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRetrievalStatus];
+```

docs-devsite/ai.urlcontext.md

@@ -0,0 +1,21 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# URLContext interface
+Specifies the URL Context configuration.
+
+Currently, this is an empty object, but it's reserved for future configuration.
+
+<b>Signature:</b>
+
+```typescript
+export interface URLContext 
+```

docs-devsite/ai.urlcontextmetadata.md

@@ -0,0 +1,35 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# URLContextMetadata interface
+Metadata related to [URLContextTool](./ai.urlcontexttool.md#urlcontexttool_interface)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export interface URLContextMetadata 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [urlMetadata](./ai.urlcontextmetadata.md#urlcontextmetadataurlmetadata) | [URLMetadata](./ai.urlmetadata.md#urlmetadata_interface)<!-- -->\[\] | List of URL metadata were used to provide context to the Gemini model. |
+
+## URLContextMetadata.urlMetadata
+
+List of URL metadata were used to provide context to the Gemini model.
+
+<b>Signature:</b>
+
+```typescript
+urlMetadata: URLMetadata[];
+```

docs-devsite/ai.urlcontexttool.md

@@ -0,0 +1,35 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# URLContextTool interface
+A tool that allows you to provide additional context to the models in the form of URLs. By including URLs in your request, the Gemini model will access the content from those pages to inform and enhance its response.
+
+<b>Signature:</b>
+
+```typescript
+export interface URLContextTool 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [urlContext](./ai.urlcontexttool.md#urlcontexttoolurlcontext) | [URLContext](./ai.urlcontext.md#urlcontext_interface) | Specifies the URL Context configuration. |
+
+## URLContextTool.urlContext
+
+Specifies the URL Context configuration.
+
+<b>Signature:</b>
+
+```typescript
+urlContext: URLContext;
+```

docs-devsite/ai.urlmetadata.md

@@ -0,0 +1,46 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# URLMetadata interface
+Metadata for a URL that was used to provide context to the Gemini model.
+
+<b>Signature:</b>
+
+```typescript
+export interface URLMetadata 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [retrievedUrl](./ai.urlmetadata.md#urlmetadataretrievedurl) | string | The retrieved URL. |
+|  [urlRetrievalStatus](./ai.urlmetadata.md#urlmetadataurlretrievalstatus) | [URLRetrievalStatus](./ai.md#urlretrievalstatus) | The status of the URL retrieval. |
+
+## URLMetadata.retrievedUrl
+
+The retrieved URL.
+
+<b>Signature:</b>
+
+```typescript
+retrievedUrl?: string;
+```
+
+## URLMetadata.urlRetrievalStatus
+
+The status of the URL retrieval.
+
+<b>Signature:</b>
+
+```typescript
+urlRetrievalStatus?: URLRetrievalStatus;
+```

docs-devsite/ai.usagemetadata.md

@@ -27,6 +27,8 @@ export interface UsageMetadata
 |  [promptTokenCount](./ai.usagemetadata.md#usagemetadataprompttokencount) | number |  |
 |  [promptTokensDetails](./ai.usagemetadata.md#usagemetadataprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] |  |
 |  [thoughtsTokenCount](./ai.usagemetadata.md#usagemetadatathoughtstokencount) | number | The number of tokens used by the model's internal "thinking" process. |
+|  [toolUsePromptTokenCount](./ai.usagemetadata.md#usagemetadatatooluseprompttokencount) | number | The number of tokens in the results from tool executions, which are provided back to the model as input. |
+|  [toolUsePromptTokensDetails](./ai.usagemetadata.md#usagemetadatatooluseprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] | A list of tokens used by tools whose usage was triggered from a prompt, broken down by modality. |
 |  [totalTokenCount](./ai.usagemetadata.md#usagemetadatatotaltokencount) | number |  |
 
 ## UsageMetadata.candidatesTokenCount
@@ -71,6 +73,26 @@ The number of tokens used by the model's internal "thinking" process.
 thoughtsTokenCount?: number;
 ```
 
+## UsageMetadata.toolUsePromptTokenCount
+
+The number of tokens in the results from tool executions, which are provided back to the model as input.
+
+<b>Signature:</b>
+
+```typescript
+toolUsePromptTokenCount?: number;
+```
+
+## UsageMetadata.toolUsePromptTokensDetails
+
+A list of tokens used by tools whose usage was triggered from a prompt, broken down by modality.
+
+<b>Signature:</b>
+
+```typescript
+toolUsePromptTokensDetails?: ModalityTokenCount[];
+```
+
 ## UsageMetadata.totalTokenCount
 
 <b>Signature:</b>