History

Conversation history enables agents to maintain context across multiple interactions. By preserving previous messages, agents can reference earlier exchanges and build upon prior context, facilitating natural, context-aware conversations.

Overview

When a conversation history manager is provided to an agent, it performs the following operations:

Loads Previous Messages: Automatically retrieves conversation history based on the thread ID
Saves Automatically: Persists new messages after each execution

Enabling Conversation History

To enable conversation history, create a history manager with hastekit.NewFileHistory and pass the created instance to the agent’s History field. While invoking the agent, optionally set Namespace to bucket the conversations by namespaces.

cm := hastekit.NewFileHistory("./conversations")
agent := hastekit.NewAgent(&hastekit.AgentConfig{
    Name:        "Hello world agent",
    LLM:         model,
    History:     cm,
})

handle, err := agent.Execute(context.Background(), &agents.AgentInput{
    Namespace: "default",
    Message: history.Message{
        Messages: []responses.InputMessageUnion{
            responses.UserMessage("Hello! My name is Alice"),
        },
    },
})
out, err := handle.Result()

Continuing the conversation

To continue the conversation, pass same thread ID while invoking the agent again.

// First invocation
threadID := uuid.NewString()
handle, err := agent.Execute(context.Background(), &agents.AgentInput{
    Namespace: "default",
    ThreadID:  threadID,
    Message: history.Message{
        Messages: []responses.InputMessageUnion{
            responses.UserMessage("Hello! My name is Alice"),
        },
    },
})
out, err := handle.Result()

// Second invocation
handle, err = agent.Execute(context.Background(), &agents.AgentInput{
    Namespace: "default",
    ThreadID:  threadID, // Pass the same thread ID to continue the conversation
    Message: history.Message{
        Messages: []responses.InputMessageUnion{
            responses.UserMessage("What's my name?"),
        },
    },
})
out, err = handle.Result()

Persistence

The conversation manager supports three persistence configurations for storing conversation history:

1. File Persistence

When the SDK client is initialized without an endpoint, messages are persisted as JSON files written to the disk (under ./conversations).

2. HasteKit Gateway Persistence

When the SDK client is initialized with an endpoint, the conversation manager automatically persists messages to the HasteKit’s Gateway server.

3. Custom Persistence

To implement custom persistence, implement the ConversationPersistenceAdapter interface:

type ConversationPersistenceAdapter interface {
	NewConversationID(ctx context.Context) string
	NewRunID(ctx context.Context) string
	LoadMessages(ctx context.Context, namespace string, threadID string, previousMessageID string) ([]history.ConversationMessage, error)
	SaveMessages(ctx context.Context, namespace, msgId, previousMsgId, threadID string, conversationId string, messages []history.Message, meta map[string]any) error
	SaveSummary(ctx context.Context, namespace string, summary history.Summary) error
}

Then pass your implementation to the conversation manager constructor:

cm := history.NewConversationManager(yourAdapter)

When you use hastekit.NewFileHistory("./conversations"), the SDK wires a file-backed adapter that persists messages as JSON on disk.

Message Filtering & Attribution

Each stored message bundle (messages.Message) carries a SenderID, which lets the conversation manager attribute turns to a specific participant in multi-participant conversations. You can transform a run’s message bundles before they are attributed and sent to the provider by supplying a MessageFilter via history.WithMessageFilter. A common use is rewriting each bundle’s SenderID from an opaque id into a human-friendly name.

type MessageFilter interface {
	Filter(ctx context.Context, msgs []messages.Message, agentID string) []messages.Message
}

cm := history.NewConversationManager(
	yourAdapter,
	history.WithMessageFilter(yourFilter),
)

The other available option is history.WithSummarizer, covered on the Summarization page.

Listing Threads

agent.History() returns the agent’s *history.CommonConversationManager. When its persistence adapter implements history.ThreadLister, you can enumerate stored threads. Pass an empty namespace ("") to list across all namespaces.

type ThreadLister interface {
	ListThreads(ctx context.Context, namespace string) ([]ThreadInfo, error)
}

if lister, ok := agent.History().ConversationPersistenceAdapter.(history.ThreadLister); ok {
	threads, err := lister.ListThreads(context.Background(), "")
	// ...
}

Complete Example

The following example demonstrates an agent with conversation history:

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/bytedance/sonic"
	"github.com/google/uuid"
	"github.com/hastekit/hastekit-sdk-go/pkg/agents"
	"github.com/hastekit/hastekit-sdk-go/pkg/agents/history"
	"github.com/hastekit/hastekit-sdk-go/pkg/gateway/llm/responses"
	hastekit "github.com/hastekit/hastekit-sdk-go"
)

func main() {
    client := hastekit.NewLLMClient([]hastekit.ProviderConfig{
        {
            ProviderName:  hastekit.ProviderOpenAI,
            BaseURL:       "",
            CustomHeaders: nil,
            ApiKeys: []*hastekit.APIKeyConfig{
                {
                    Name:   "Key 1",
                    APIKey: os.Getenv("OPENAI_API_KEY"),
                },
            },
        },
    })

	model := client.Model("OpenAI/gpt-4.1-mini")

	cm := hastekit.NewFileHistory("./conversations")
	agent := hastekit.NewAgent(&hastekit.AgentConfig{
		Name:        "Hello world agent",
		Instruction: hastekit.NewPrompt("You are helpful assistant."),
		LLM:         model,
		History:     cm,
	})

    threadID := uuid.NewString()

	handle, err := agent.Execute(context.Background(), &agents.AgentInput{
		Namespace: "default",
		ThreadID:  threadID,
		Message: history.Message{
            Messages: []responses.InputMessageUnion{
			    responses.UserMessage("Hello! My name is Alice"),
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	out, err := handle.Result()
	if err != nil {
		log.Fatal(err)
	}

	b, _ := sonic.Marshal(out)
	fmt.Println(string(b))

	// Agent itself is stateless - you can either re-create another agent or reuse the same agent instance, but ensure to pass the correct `ThreadID`
	agent2 := hastekit.NewAgent(&hastekit.AgentConfig{
		Name:        "Hello world agent",
		Instruction: hastekit.NewPrompt("You are helpful assistant."),
		LLM:         model,
		History:     cm,
	})

	handle, err = agent2.Execute(context.Background(), &agents.AgentInput{
		Namespace: "default",
		ThreadID:  threadID,
		Message: history.Message{
            Messages: []responses.InputMessageUnion{
			    responses.UserMessage("What's my name?"),
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	out, err = handle.Result()
	if err != nil {
		log.Fatal(err)
	}

	b, _ = sonic.Marshal(out)
	fmt.Println(string(b))
}

SDK

LLM Gateway

Agents

Workflows

Overview

Enabling Conversation History

Continuing the conversation

Persistence

1. File Persistence

2. HasteKit Gateway Persistence

3. Custom Persistence

Message Filtering & Attribution

Listing Threads

Complete Example

​Overview

​Enabling Conversation History

​Continuing the conversation

​Persistence

​1. File Persistence

​2. HasteKit Gateway Persistence

​3. Custom Persistence

​Message Filtering & Attribution

​Listing Threads

​Complete Example

Overview

Enabling Conversation History

Continuing the conversation

Persistence

1. File Persistence

2. HasteKit Gateway Persistence

3. Custom Persistence

Message Filtering & Attribution

Listing Threads

Complete Example