session

Documentation

Overview

Package session provides types to manage user sessions and their states.

Index

• Constants
• Variables
• type CreateRequest
• type CreateResponse
• type DeleteRequest
• type Event
  • func NewEvent(invocationID string) *Event
  • func (e *Event) IsFinalResponse() bool
• type EventActions
• type Events
• type GetRequest
• type GetResponse
• type ListRequest
• type ListResponse
• type ReadonlyState
• type Service
  • func InMemoryService() Service
• type Session
• type State

Constants

const (
	// KeyPrefixApp is the prefix for app-level state keys.
	// They are shared across all users and sessions for that application.
	KeyPrefixApp string = "app:"
	// KeyPrefixTemp is the prefix for temporary state keys.
	// Such entries are specific to the current invocation (the entire process
	// from an agent receiving user input to generating the final output for
	// that input. Discarded after the invocation completes.
	KeyPrefixTemp string = "temp:"
	// KeyPrefixUser is the prefix for user-level state keys.
	// They are tied to the user_id, shared across all sessions for that user
	// (within the same app_name).
	KeyPrefixUser string = "user:"
)

Prefixes for defining session's state scopes

Variables

var ErrStateKeyNotExist = errors.New("state key does not exist")

ErrStateKeyNotExist is the error thrown when key does not exist.

Types

type CreateRequest

type CreateRequest struct {
	AppName string
	UserID  string
	// SessionID is the client-provided ID of the session to create.
	// Optional: if not set, it will be autogenerated.
	SessionID string
	// State is the initial state of the session.
	State map[string]any
}

CreateRequest represents a request to create a session.

type CreateResponse

type CreateResponse struct {
	Session Session
}

CreateResponse represents a response for newly created session.

type DeleteRequest

type DeleteRequest struct {
	AppName   string
	UserID    string
	SessionID string
}

DeleteRequest represents a request to delete a session.

type Event

type Event struct {
	model.LLMResponse

	// Set by storage
	ID        string
	Timestamp time.Time

	// Set by agent.Context implementation.
	InvocationID string
	// The branch of the event.
	//
	// The format is like agent_1.agent_2.agent_3, where agent_1 is
	// the parent of agent_2, and agent_2 is the parent of agent_3.
	//
	// Branch is used when multiple sub-agent shouldn't see their peer agents'
	// conversation history.
	Branch string
	// Author is the name of the event's author
	Author string

	// The actions taken by the agent.
	Actions EventActions
	// Set of IDs of the long running function calls.
	// Agent client will know from this field about which function call is long running.
	// Only valid for function call event.
	LongRunningToolIDs []string
}

Event represents an interaction in a conversation between agents and users. It is used to store the content of the conversation, as well as the actions taken by the agents like function calls, etc.

func NewEvent

func NewEvent(invocationID string) *Event

NewEvent creates a new event defining now as the timestamp.

func (*Event) IsFinalResponse

func (e *Event) IsFinalResponse() bool

IsFinalResponse returns whether the event is the final response of an agent.

Note: when multiple agents participate in one invocation, there could be multiple events with IsFinalResponse() as True, for each participating agent.

type EventActions

type EventActions struct {
	// Set by agent.Context implementation.
	StateDelta map[string]any

	// Indicates that the event is updating an artifact. key is the filename,
	// value is the version.
	ArtifactDelta map[string]int64

	// If true, it won't call model to summarize function response.
	// Only valid for function response event.
	SkipSummarization bool
	// If set, the event transfers to the specified agent.
	TransferToAgent string
	// The agent is escalating to a higher level agent.
	Escalate bool
}

EventActions represent the actions attached to an event.

type Events

type Events interface {
	// All returns an iterator (iter.Seq) that yields all events
	// in the sequence, preserving their order.
	All() iter.Seq[*Event]
	// Len returns the total number of events in the sequence.
	Len() int
	// At returns the event at the specified index i.
	At(i int) *Event
}

Events define a standard interface for an Event list. It provides methods for iterating over the sequence and accessing individual events by their index.

type GetRequest

type GetRequest struct {
	AppName   string
	UserID    string
	SessionID string

	// NumRecentEvents returns at most NumRecentEvents most recent events.
	// Optional: if zero, the filter is not applied.
	NumRecentEvents int
	// After returns events with timestamp >= the given time.
	// Optional: if zero, the filter is not applied.
	After time.Time
}

GetRequest represents a request to get a session.

type GetResponse

type GetResponse struct {
	Session Session
}

GetResponse represents a response from [Service.Get].

type ListRequest

type ListRequest struct {
	AppName string
	UserID  string
}

ListRequest represents a request to list sessions.

type ListResponse

type ListResponse struct {
	Sessions []Session
}

ListResponse represents a response from [Service.List].

type ReadonlyState

type ReadonlyState interface {
	// Get retrieves the value associated with a given key.
	// It returns a ErrStateKeyNotExist error if the key does not exist.
	Get(string) (any, error)
	// All returns an iterator (iter.Seq2) that yields all key-value pairs
	// currently in the state. The order of iteration is not guaranteed.
	All() iter.Seq2[string, any]
}

ReadonlyState defines a standard interface for a key-value store. It provides basic methods for accessing, and iterating over key-value pairs.

type Service

type Service interface {
	Create(context.Context, *CreateRequest) (*CreateResponse, error)
	Get(context.Context, *GetRequest) (*GetResponse, error)
	List(context.Context, *ListRequest) (*ListResponse, error)
	Delete(context.Context, *DeleteRequest) error
	// AppendEvent is used to append an event to a session, and remove temporary state keys from the event.
	AppendEvent(context.Context, Session, *Event) error
}

Service is a session storage service.

It provides a set of methods for managing sessions and events.

func InMemoryService

func InMemoryService() Service

InMemoryService returns an in-memory implementation of the session service.

type Session

type Session interface {
	// ID returns the unique identifier of the session.
	ID() string
	// AppName returns name of the app.
	AppName() string
	// UserID returns the id of the user.
	UserID() string

	// State returns the state of the session.
	State() State
	// Events return the events of the session, e.g. user input, model response, function call/response, etc.
	Events() Events
	// LastUpdateTime returns the time of the last update.
	LastUpdateTime() time.Time
}

Session represents a series of interactions between a user and agents.

When a user starts interacting with your agent, session holds everything related to that one specific chat thread.

type State

type State interface {
	// Get retrieves the value associated with a given key.
	// It returns a ErrStateKeyNotExist error if the key does not exist.
	Get(string) (any, error)
	// Set assigns the given value to the given key, overwriting any
	// existing value. It returns an error if the underlying storage
	// operation fails.
	Set(string, any) error
	// All returns an iterator (iter.Seq2) that yields all key-value pairs
	// currently in the state. The order of iteration is not guaranteed.
	All() iter.Seq2[string, any]
}

State defines a standard interface for a key-value store. It provides basic methods for accessing, modifying, and iterating over key-value pairs.