feat: redux of function calling and adds context example

Author: jpvajda

examples/agent/websocket/context-history/main.go

@@ -46,6 +46,8 @@ func NewDefaultChanHandler() *DefaultChanHandler {
 		closeChan:                    make(chan *interfaces.CloseResponse),
 		errorChan:                    make(chan *interfaces.ErrorResponse),
 		unhandledChan:                make(chan *[]byte),
+		historyConversationTextChan:  make(chan *interfaces.HistoryConversationText),
+		historyFunctionCallsChan:     make(chan *interfaces.HistoryFunctionCalls),
 	}
 
 	go func() {
@@ -133,6 +135,16 @@ func (dch DefaultChanHandler) GetSettingsApplied() []*chan *interfaces.SettingsA
 	return []*chan *interfaces.SettingsAppliedResponse{&dch.settingsAppliedResponse}
 }
 
+// GetHistoryConversationText returns the history conversation text channels
+func (dch DefaultChanHandler) GetHistoryConversationText() []*chan *interfaces.HistoryConversationText {
+	return []*chan *interfaces.HistoryConversationText{&dch.historyConversationTextChan}
+}
+
+// GetHistoryFunctionCalls returns the history function calls channels
+func (dch DefaultChanHandler) GetHistoryFunctionCalls() []*chan *interfaces.HistoryFunctionCalls {
+	return []*chan *interfaces.HistoryFunctionCalls{&dch.historyFunctionCallsChan}
+}
+
 // Open is the callback for when the connection opens
 //
 //nolint:funlen,gocyclo // this is a complex function. keep as is

pkg/api/agent/v1/websocket/chan_default.go

@@ -55,9 +55,12 @@ func NewChanRouter(chans interfaces.AgentMessageChan) *ChanRouter {
 		closeChan:                    make([]*chan *interfaces.CloseResponse, 0),
 		errorChan:                    make([]*chan *interfaces.ErrorResponse, 0),
 		unhandledChan:                make([]*chan *[]byte, 0),
+		historyConversationTextChan:  make([]*chan *interfaces.HistoryConversationText, 0),
+		historyFunctionCallsChan:     make([]*chan *interfaces.HistoryFunctionCalls, 0),
 	}
 
 	if chans != nil {
+		// CORE FUNCTIONALITY: Always available via AgentMessageChan interface
 		router.binaryChan = append(router.binaryChan, chans.GetBinary()...)
 		router.openChan = append(router.openChan, chans.GetOpen()...)
 		router.welcomeResponse = append(router.welcomeResponse, chans.GetWelcome()...)
@@ -73,6 +76,18 @@ func NewChanRouter(chans interfaces.AgentMessageChan) *ChanRouter {
 		router.injectionRefusedResponse = append(router.injectionRefusedResponse, chans.GetInjectionRefused()...)
 		router.keepAliveResponse = append(router.keepAliveResponse, chans.GetKeepAlive()...)
 		router.settingsAppliedResponse = append(router.settingsAppliedResponse, chans.GetSettingsApplied()...)
+
+		// INTERFACE SEGREGATION: Optional History capability detection
+
+		if historyChan, hasHistory := chans.(interfaces.HistoryMessageChan); hasHistory {
+			klog.V(4).Infof("Handler supports History functionality - routing History messages\n")
+			router.historyConversationTextChan = append(router.historyConversationTextChan, historyChan.GetHistoryConversationText()...)
+			router.historyFunctionCallsChan = append(router.historyFunctionCallsChan, historyChan.GetHistoryFunctionCalls()...)
+		} else {
+			klog.V(4).Infof("Handler does not implement HistoryMessageChan - History messages will route to UnhandledMessage\n")
+		}
+		// Note: If handler doesn't implement HistoryMessageChan, History messages will
+		// be routed to UnhandledMessage, which is the expected fallback behavior.
 	}
 
 	return router
@@ -354,6 +369,33 @@ func (r *ChanRouter) processSettingsApplied(byMsg []byte) error {
 	return r.processGeneric(string(interfaces.TypeSettingsAppliedResponse), byMsg, action)
 }
 
+func (r *ChanRouter) processHistory(byMsg []byte) error {
+	// Try to parse as HistoryConversationText first
+	var convHistory interfaces.HistoryConversationText
+	if err := json.Unmarshal(byMsg, &convHistory); err == nil {
+		if convHistory.Role != "" && convHistory.Content != "" {
+			for _, ch := range r.historyConversationTextChan {
+				*ch <- &convHistory
+			}
+			return nil
+		}
+	}
+
+	// Try to parse as HistoryFunctionCalls
+	var funcHistory interfaces.HistoryFunctionCalls
+	if err := json.Unmarshal(byMsg, &funcHistory); err == nil {
+		if len(funcHistory.FunctionCalls) > 0 {
+			for _, ch := range r.historyFunctionCallsChan {
+				*ch <- &funcHistory
+			}
+			return nil
+		}
+	}
+
+	klog.V(1).Infof("processHistory: Unable to parse History message")
+	return ErrInvalidMessageType
+}
+
 // Message handles platform messages and routes them appropriately based on the MessageType
 func (r *ChanRouter) Message(byMsg []byte) error {
 	klog.V(6).Infof("router.Message ENTER\n")
@@ -393,6 +435,8 @@ func (r *ChanRouter) Message(byMsg []byte) error {
 		err = r.processKeepAlive(byMsg)
 	case interfaces.TypeSettingsAppliedResponse:
 		err = r.processSettingsApplied(byMsg)
+	case "History":
+		err = r.processHistory(byMsg)
 	default:
 		err = r.UnhandledMessage(byMsg)
 	}

pkg/api/agent/v1/websocket/chan_router.go

@@ -5,10 +5,8 @@
 // This package defines interfaces for the live API
 package interfacesv1
 
-/*
-Chan Interfaces
-*/
-// AgentMessageChan is a callback used to receive notifcations for platforms messages
+// AgentMessageChan is the core interface for receiving agent message notifications.
+// This interface should remain unchanged to maintain backwards compatibility.
 type AgentMessageChan interface {
 	GetBinary() []*chan *[]byte
 	GetOpen() []*chan *OpenResponse
@@ -26,3 +24,10 @@ type AgentMessageChan interface {
 	GetKeepAlive() []*chan *KeepAlive
 	GetSettingsApplied() []*chan *SettingsAppliedResponse
 }
+
+// HistoryMessageChan is an optional interface for receiving History message notifications.
+// Implement this interface in addition to AgentMessageChan to be non-breaking.
+type HistoryMessageChan interface {
+	GetHistoryConversationText() []*chan *HistoryConversationText
+	GetHistoryFunctionCalls() []*chan *HistoryFunctionCalls
+}

pkg/api/agent/v1/websocket/interfaces/interfaces.go

@@ -40,9 +40,10 @@ type InjectUserMessage struct {
 
 // FunctionCallResponse is the response from a function call
 type FunctionCallResponse struct {
-	Type           string `json:"type,omitempty"`
-	FunctionCallID string `json:"function_call_id,omitempty"`
-	Output         string `json:"output,omitempty"`
+	Type    string `json:"type,omitempty"`
+	ID      string `json:"id,omitempty"`      // Function call ID
+	Name    string `json:"name,omitempty"`    // Function name
+	Content string `json:"content,omitempty"` // Response content
 }
 
 // HistoryConversationText is the request to send conversation history
@@ -130,10 +131,8 @@ type AgentThinkingResponse struct {
 
 // FunctionCallRequestResponse is the response from a function call request
 type FunctionCallRequestResponse struct {
-	Type           string            `json:"type,omitempty"`
-	FunctionName   string            `json:"function_name,omitempty"`
-	FunctionCallID string            `json:"function_call_id,omitempty"`
-	Input          map[string]string `json:"input,omitempty"` // TODO: this is still undefined
+	Type      string         `json:"type,omitempty"`
+	Functions []FunctionCall `json:"functions,omitempty"`
 }
 
 // AgentStartedSpeakingResponse is the response from the Agent starting to speak. You will ONLY get this if `experimental` is set to true.

pkg/api/agent/v1/websocket/interfaces/types.go

@@ -32,6 +32,8 @@ type DefaultChanHandler struct {
 	closeChan                    chan *interfaces.CloseResponse
 	errorChan                    chan *interfaces.ErrorResponse
 	unhandledChan                chan *[]byte
+	historyConversationTextChan  chan *interfaces.HistoryConversationText
+	historyFunctionCallsChan     chan *interfaces.HistoryFunctionCalls
 }
 
 // ChanRouter routes events
@@ -54,4 +56,6 @@ type ChanRouter struct {
 	closeChan                    []*chan *interfaces.CloseResponse
 	errorChan                    []*chan *interfaces.ErrorResponse
 	unhandledChan                []*chan *[]byte
+	historyConversationTextChan  []*chan *interfaces.HistoryConversationText
+	historyFunctionCallsChan     []*chan *interfaces.HistoryFunctionCalls
 }

pkg/api/agent/v1/websocket/types.go

@@ -46,17 +46,10 @@ type Endpoint struct {
 	Headers map[string]string `json:"headers,omitempty"`
 	Method  string            `json:"method,omitempty"`
 }
-type Item struct {
-	Type        string `json:"type,omitempty"`
-	Description string `json:"description,omitempty"`
-}
-type Properties struct {
-	Item Item `json:"item,omitempty"`
-}
 type Parameters struct {
-	Type       string     `json:"type,omitempty"`
-	Properties Properties `json:"properties,omitempty"`
-	Required   []string   `json:"required,omitempty"`
+	Type       string                 `json:"type,omitempty"`
+	Properties map[string]interface{} `json:"properties,omitempty"`
+	Required   []string               `json:"required,omitempty"`
 }
 type Headers struct {
 	Key   string `json:"key,omitempty"`
@@ -66,7 +59,7 @@ type Functions struct {
 	Name        string     `json:"name,omitempty"`
 	Description string     `json:"description,omitempty"`
 	Parameters  Parameters `json:"parameters,omitempty"`
-	Endpoint    Endpoint   `json:"endpoint,omitempty"`
+	Endpoint    *Endpoint  `json:"endpoint,omitempty"` // Pointer allows nil/omitempty for client-side functions
 }
 type Listen struct {
 	Provider map[string]interface{} `json:"provider,omitempty"`

pkg/client/interfaces/v1/types-agent.go

@@ -1 +1 @@
-{"metadata":{"transaction_key":"deprecated","request_id":"4b9f7407-0dcf-4621-b4bc-5d9a7efcb8eb","sha256":"5324da68ede209a16ac69a38e8cd29cee4d754434a041166cda3a1f5e0b24566","created":"2025-07-24T18:58:58.305Z","duration":17.566313,"channels":1,"models":["1abfe86b-e047-4eed-858a-35e5625b41ee"],"model_info":{"1abfe86b-e047-4eed-858a-35e5625b41ee":{"name":"2-general-nova","version":"2024-01-06.5664","arch":"nova-2"}},"summary_info":{"model_uuid":"67875a7f-c9c4-48a0-aa55-5bdb8a91c34a"}},"results":{"channels":[{"alternatives":[{"transcript":"Yep. I said it before, and I'll say it again. Life moves pretty fast. You don't stop and look around once in a while, you could miss it.","confidence":0.99953604,"words":[{"word":"yep","start":5.6,"end":6.1,"confidence":0.9976603,"punctuated_word":"Yep."},{"word":"i","start":7.04,"end":7.2799997,"confidence":0.70802623,"punctuated_word":"I"},{"word":"said","start":7.2799997,"end":7.44,"confidence":0.965023,"punctuated_word":"said"},{"word":"it","start":7.44,"end":7.6,"confidence":0.99953604,"punctuated_word":"it"},{"word":"before","start":7.6,"end":7.9199996,"confidence":0.816449,"punctuated_word":"before,"},{"word":"and","start":7.9199996,"end":8.08,"confidence":0.9998956,"punctuated_word":"and"},{"word":"i'll","start":8.08,"end":8.24,"confidence":0.99988514,"punctuated_word":"I'll"},{"word":"say","start":8.24,"end":8.48,"confidence":0.999711,"punctuated_word":"say"},{"word":"it","start":8.48,"end":8.639999,"confidence":0.9998085,"punctuated_word":"it"},{"word":"again","start":8.639999,"end":9.139999,"confidence":0.95393705,"punctuated_word":"again."},{"word":"life","start":9.991312,"end":10.391313,"confidence":0.999337,"punctuated_word":"Life"},{"word":"moves","start":10.391313,"end":10.711312,"confidence":0.99979717,"punctuated_word":"moves"},{"word":"pretty","start":10.711312,"end":11.031313,"confidence":0.99983037,"punctuated_word":"pretty"},{"word":"fast","start":11.031313,"end":11.531313,"confidence":0.9997682,"punctuated_word":"fast."},{"word":"you","start":11.991312,"end":12.231313,"confidence":0.95979714,"punctuated_word":"You"},{"word":"don't","start":12.231313,"end":12.4713125,"confidence":0.9999173,"punctuated_word":"don't"},{"word":"stop","start":12.4713125,"end":12.711312,"confidence":0.9998498,"punctuated_word":"stop"},{"word":"and","start":12.711312,"end":12.871312,"confidence":0.99942267,"punctuated_word":"and"},{"word":"look","start":12.871312,"end":13.031313,"confidence":0.99988985,"punctuated_word":"look"},{"word":"around","start":13.031313,"end":13.351313,"confidence":0.999853,"punctuated_word":"around"},{"word":"once","start":13.351313,"end":13.591312,"confidence":0.99923956,"punctuated_word":"once"},{"word":"in","start":13.591312,"end":13.751312,"confidence":0.9984458,"punctuated_word":"in"},{"word":"a","start":13.751312,"end":13.831312,"confidence":0.98450977,"punctuated_word":"a"},{"word":"while","start":13.831312,"end":14.331312,"confidence":0.94350064,"punctuated_word":"while,"},{"word":"you","start":14.631312,"end":14.791312,"confidence":0.99865144,"punctuated_word":"you"},{"word":"could","start":14.791312,"end":14.951313,"confidence":0.99964106,"punctuated_word":"could"},{"word":"miss","start":14.951313,"end":15.191313,"confidence":0.9996731,"punctuated_word":"miss"},{"word":"it","start":15.191313,"end":15.691313,"confidence":0.9976532,"punctuated_word":"it."}]}]}],"summary":{"short":"Yep. I said it before, and I'll say it again. Life moves pretty fast. You don't stop and look around once in a while, you could miss it.","result":"success"}}}
+{"metadata":{"transaction_key":"deprecated","request_id":"014aadc7-9759-4524-aa53-5754b3d619b9","sha256":"5324da68ede209a16ac69a38e8cd29cee4d754434a041166cda3a1f5e0b24566","created":"2025-08-11T22:31:34.431Z","duration":17.566313,"channels":1,"models":["1abfe86b-e047-4eed-858a-35e5625b41ee"],"model_info":{"1abfe86b-e047-4eed-858a-35e5625b41ee":{"name":"2-general-nova","version":"2024-01-06.5664","arch":"nova-2"}},"summary_info":{"model_uuid":"67875a7f-c9c4-48a0-aa55-5bdb8a91c34a"}},"results":{"channels":[{"alternatives":[{"transcript":"Yep. I said it before, and I'll say it again. Life moves pretty fast. You don't stop and look around once in a while, you could miss it.","confidence":0.99953616,"words":[{"word":"yep","start":5.6,"end":6.1,"confidence":0.99766004,"punctuated_word":"Yep."},{"word":"i","start":7.04,"end":7.2799997,"confidence":0.7080212,"punctuated_word":"I"},{"word":"said","start":7.2799997,"end":7.44,"confidence":0.96501154,"punctuated_word":"said"},{"word":"it","start":7.44,"end":7.6,"confidence":0.99953616,"punctuated_word":"it"},{"word":"before","start":7.6,"end":7.9199996,"confidence":0.81644833,"punctuated_word":"before,"},{"word":"and","start":7.9199996,"end":8.08,"confidence":0.9998956,"punctuated_word":"and"},{"word":"i'll","start":8.08,"end":8.24,"confidence":0.99988514,"punctuated_word":"I'll"},{"word":"say","start":8.24,"end":8.48,"confidence":0.999711,"punctuated_word":"say"},{"word":"it","start":8.48,"end":8.639999,"confidence":0.9998085,"punctuated_word":"it"},{"word":"again","start":8.639999,"end":9.139999,"confidence":0.95393544,"punctuated_word":"again."},{"word":"life","start":9.991312,"end":10.391313,"confidence":0.999337,"punctuated_word":"Life"},{"word":"moves","start":10.391313,"end":10.711312,"confidence":0.99979717,"punctuated_word":"moves"},{"word":"pretty","start":10.711312,"end":11.031313,"confidence":0.99983037,"punctuated_word":"pretty"},{"word":"fast","start":11.031313,"end":11.531313,"confidence":0.9997682,"punctuated_word":"fast."},{"word":"you","start":11.991312,"end":12.231313,"confidence":0.9598434,"punctuated_word":"You"},{"word":"don't","start":12.231313,"end":12.4713125,"confidence":0.9999174,"punctuated_word":"don't"},{"word":"stop","start":12.4713125,"end":12.711312,"confidence":0.9998498,"punctuated_word":"stop"},{"word":"and","start":12.711312,"end":12.871312,"confidence":0.99942255,"punctuated_word":"and"},{"word":"look","start":12.871312,"end":13.031313,"confidence":0.99988985,"punctuated_word":"look"},{"word":"around","start":13.031313,"end":13.351313,"confidence":0.999853,"punctuated_word":"around"},{"word":"once","start":13.351313,"end":13.591312,"confidence":0.9992397,"punctuated_word":"once"},{"word":"in","start":13.591312,"end":13.751312,"confidence":0.99844617,"punctuated_word":"in"},{"word":"a","start":13.751312,"end":13.831312,"confidence":0.98451185,"punctuated_word":"a"},{"word":"while","start":13.831312,"end":14.331312,"confidence":0.94352007,"punctuated_word":"while,"},{"word":"you","start":14.631312,"end":14.791312,"confidence":0.99865156,"punctuated_word":"you"},{"word":"could","start":14.791312,"end":14.951313,"confidence":0.99964106,"punctuated_word":"could"},{"word":"miss","start":14.951313,"end":15.191313,"confidence":0.99967325,"punctuated_word":"miss"},{"word":"it","start":15.191313,"end":15.691313,"confidence":0.99765414,"punctuated_word":"it."}]}]}],"summary":{"short":"Yep. I said it before, and I'll say it again. Life moves pretty fast. You don't stop and look around once in a while, you could miss it.","result":"success"}}}