feat: add support for agent context history

Author: jpvajda

src/lib/types/AgentLiveSchema.ts

@@ -8,6 +8,9 @@ type SpeakProvider = {
   };
 };
 
+import type { HistoryConversationText } from "./HistoryConversationText";
+import type { HistoryFunctionCall } from "./HistoryFunctionCall";
+
 /**
  * @see https://developers.deepgram.com/docs/configure-voice-agent
  */
@@ -17,6 +20,19 @@ interface AgentLiveSchema extends Record<string, unknown> {
    * @default false
    */
   experimental?: boolean;
+
+  /**
+   * Configuration flags for agent features
+   */
+  flags?: {
+    /**
+     * @see https://developers.deepgram.com/docs/configure-voice-agent#agentcontext
+     * Enable or disable history message reporting
+     * @default true
+     */
+    history?: boolean;
+  };
+
   audio: {
     input?: {
       /**
@@ -47,6 +63,17 @@ interface AgentLiveSchema extends Record<string, unknown> {
      * @default "en"
      */
     language?: string;
+
+    /**
+     * Conversation context including the history of messages and function calls
+     */
+    context?: {
+      /**
+       * Conversation history as a list of messages and function calls
+       */
+      messages?: (HistoryConversationText | HistoryFunctionCall)[];
+    };
+
     listen?: {
       provider: Provider;
     };

src/lib/types/HistoryConversationText.ts

@@ -0,0 +1,20 @@
+/**
+ * History conversation text message schema for agent context
+ * @see API specification for agent context history
+ */
+export interface HistoryConversationText {
+  /**
+   * Message type identifier for conversation text
+   */
+  type: "History";
+
+  /**
+   * Identifies who spoke the statement
+   */
+  role: "user" | "assistant";
+
+  /**
+   * The actual statement that was spoken
+   */
+  content: string;
+}

src/lib/types/HistoryFunctionCall.ts

@@ -0,0 +1,40 @@
+/**
+ * History function call message schema for agent context
+ * @see API specification for agent context history
+ */
+export interface HistoryFunctionCall {
+  /**
+   * Message type identifier for function calls
+   */
+  type: "History";
+
+  /**
+   * List of function call objects
+   */
+  function_calls: {
+    /**
+     * Unique identifier for the function call
+     */
+    id: string;
+
+    /**
+     * Name of the function called
+     */
+    name: string;
+
+    /**
+     * Indicates if the call was client-side or server-side
+     */
+    client_side: boolean;
+
+    /**
+     * Arguments passed to the function
+     */
+    arguments: string;
+
+    /**
+     * Response from the function call
+     */
+    response: string;
+  }[];
+}

src/lib/types/index.ts

@@ -28,6 +28,8 @@ export * from "./GetProjectUsageSummarySchema";
 export * from "./GetTokenDetailsResponse";
 export * from "./GrantTokenResponse";
 export * from "./GrantTokenSchema";
+export * from "./HistoryConversationText";
+export * from "./HistoryFunctionCall";
 export * from "./ListOnPremCredentialsResponse";
 export * from "./LiveConfigOptions";
 export * from "./LiveMetadataEvent";

src/packages/AgentLiveClient.ts

@@ -1,6 +1,12 @@
 import { DEFAULT_AGENT_URL } from "../lib/constants";
 import { AgentEvents } from "../lib/enums/AgentEvents";
-import type { AgentLiveSchema, DeepgramClientOptions, FunctionCallResponse } from "../lib/types";
+import type {
+  AgentLiveSchema,
+  DeepgramClientOptions,
+  FunctionCallResponse,
+  HistoryConversationText,
+  HistoryFunctionCall,
+} from "../lib/types";
 import { AbstractLiveClient } from "./AbstractLiveClient";
 
 export class AgentLiveClient extends AbstractLiveClient {
@@ -167,4 +173,32 @@ export class AgentLiveClient extends AbstractLiveClient {
   public keepAlive(): void {
     this.send(JSON.stringify({ type: "KeepAlive" }));
   }
+
+  /**
+   * Send conversation history text to provide context to the agent.
+   * @param historyMessage - The history conversation text message.
+   */
+  public sendHistoryConversationText(historyMessage: HistoryConversationText): void {
+    this.send(JSON.stringify(historyMessage));
+  }
+
+  /**
+   * Send function call history to provide context to the agent.
+   * @param historyMessage - The history function call message.
+   */
+  public sendHistoryFunctionCall(historyMessage: HistoryFunctionCall): void {
+    this.send(JSON.stringify(historyMessage));
+  }
+
+  /**
+   * Send multiple history messages at once to provide comprehensive context to the agent.
+   * @param historyMessages - Array of history messages (conversation text and/or function calls).
+   */
+  public sendHistoryMessages(
+    historyMessages: (HistoryConversationText | HistoryFunctionCall)[]
+  ): void {
+    historyMessages.forEach((message) => {
+      this.send(JSON.stringify(message));
+    });
+  }
 }