[repo] fix: C# Citations' encodingFormat to not be hardcoded. Fix J…

…S AssistantsPlanner options to set api version (#2235)

## Linked issues

closes: #2234
closes: #2233

## Details

- Fix C# `AIEntity` to make `encodingFormat` optional and not hardcoded.
- Change inline docs to indicate `encodingFormat` is for
`citation.appearance.text`
- Update `AssistantsPlannerOptions` to include `api_version` field
- Update `AssistantsPlanner` to set `api_version`

## Attestation Checklist

- [x] My code follows the style guidelines of this project

- I have checked for/fixed spelling, linting, and other errors
- I have commented my code for clarity
- I have made corresponding changes to the documentation (updating the
doc strings in the code is sufficient)
- My changes generate no new warnings
- I have added tests that validates my changes, and provides sufficient
test coverage. I have tested with:
  - Local testing
  - E2E testing in Teams
- New and existing unit tests pass locally with my changes

---------

Co-authored-by: Corina Gum <>

dotnet/packages/Microsoft.TeamsAI/Microsoft.TeamsAI/AI/Action/AIEntity.cs

@@ -94,7 +94,7 @@ public class ClientCitationAppearance
         public string Name { get; set; } = string.Empty;
 
         /// <summary>
-        /// Optional. The citation appreance text. It is ignored in Teams.
+        /// Optional. The citation appearance text.
         /// </summary>
         [JsonProperty(PropertyName = "text")]
         public string? Text { get; set; }
@@ -112,10 +112,10 @@ public class ClientCitationAppearance
         public string Abstract { get; set; } = string.Empty;
 
         /// <summary>
-        /// The encoding format used for the icon.
+        /// Optional. Encoding format of the `citation.appearance.text` field.
         /// </summary>
         [JsonProperty(PropertyName = "encodingFormat")]
-        public string EncodingFormat { get; set; } = "text/html";
+        public string? EncodingFormat { get; set; }
 
         /// <summary>
         /// The icon provided in the citation ui.

js/packages/teams-ai/src/planners/AssistantsPlanner.spec.ts

@@ -53,7 +53,8 @@ describe('AssistantsPlanner', () => {
 
         const options: AssistantsPlannerOptions = {
             apiKey: 'test-key',
-            assistant_id: 'test-assistant-id'
+            assistant_id: 'test-assistant-id',
+            api_version: '2024-02-15'
         };
 
         planner = new AssistantsPlanner<TurnState>(options);

js/packages/teams-ai/src/planners/AssistantsPlanner.ts

@@ -68,6 +68,11 @@ export interface AssistantsPlannerOptions {
      * Defaults to 'conversation.assistants_state'.
      */
     assistants_state_variable?: string;
+
+    /**
+     * Optional. Version of the API being called. Default is '2024-02-15-preview'.
+     */
+    api_version?: string;
 }
 
 /**
@@ -92,6 +97,7 @@ export class AssistantsPlanner<TState extends TurnState = TurnState> implements
         this._options = {
             polling_interval: DEFAULT_POLLING_INTERVAL,
             assistants_state_variable: DEFAULT_ASSISTANTS_STATE_VARIABLE,
+            api_version: '2024-02-15-preview',
             ...options
         };
 

js/packages/teams-ai/src/types/ClientCitation.ts

@@ -73,7 +73,7 @@ export interface ClientCitation {
         abstract: string;
 
         /**
-         * Encoding format of the ` citation.appearance.text` field. 
+         * Encoding format of the `citation.appearance.text` field.
          */
         encodingFormat?: 'application/vnd.microsoft.card.adaptive';
 

js/samples/04.ai-apps/d.assistants-mathBot/src/bot.ts

@@ -40,7 +40,8 @@ if (!process.env.ASSISTANT_ID) {
 const planner = new AssistantsPlanner({
     apiKey: apiKey,
     endpoint: endpoint,
-    assistant_id: process.env.ASSISTANT_ID!
+    assistant_id: process.env.ASSISTANT_ID!,
+    api_version: '2024-02-15-preview'
 });
 
 // Define storage and application

js/samples/04.ai-apps/e.assistants-orderBot/src/bot.ts

@@ -61,7 +61,8 @@ if (!process.env.ASSISTANT_ID) {
 const planner = new AssistantsPlanner({
     apiKey: apiKey,
     endpoint: endpoint,
-    assistant_id: process.env.ASSISTANT_ID ?? assistantId
+    assistant_id: process.env.ASSISTANT_ID ?? assistantId,
+    api_version: '2024-02-15-preview'
 });
 
 // Define storage and application

python/packages/ai/teams/ai/citations/citations.py

@@ -64,11 +64,11 @@ class Appearance(Model):
     Attributes:
         @type (str): Required; must be 'DigitalDocument'
         name (str): The name of the document
-        text (str): Optional; ignored in Teams
+        text (str): Optional; the appearance text of the citation.
         url (str): The url of the document
         abstract (str): Content of the citation. Must be clipped if longer than 480 characters
-        encodingFormat (str): The encoding format of the citation
-        image (str): Used for icon; for not it is ignored
+        encodingFormat (str): Encoding format of the `citation.appearance.text` field.
+        image (str): Used for icon; for now it is ignored
         keywords (list[str]): The optional keywords to the citation
         usageInfo (SensitivityUsageInfo): The optional sensitivity content information
     """