voice

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2026 License: Apache-2.0 Imports: 42 Imported by: 0

Documentation

Overview

Package voice implements LiveKit's agent-session state machine and media pipeline.

Index

Constants

View Source 
const (
	DefaultAMDHumanSpeechThreshold    = 2500 * time.Millisecond
	DefaultAMDHumanSilenceThreshold   = 500 * time.Millisecond
	DefaultAMDMachineSilenceThreshold = 1500 * time.Millisecond
	DefaultAMDNoSpeechTimeout         = 10 * time.Second
	DefaultAMDDetectionTimeout        = 20 * time.Second
	DefaultAMDMaxEndpointingDelay     = 3 * time.Second
	DefaultAMDTrackPublicationTimeout = 5 * time.Second
	DefaultAMDInterruptTimeout        = 5 * time.Second
	DefaultAMDCloseTimeout            = 5 * time.Second
	DefaultAMDMaxExtensions           = 3
	DefaultAMDMaxExtension            = 10 * time.Second
	DefaultAMDLLMModel                = "google/gemini-3.1-flash-lite"
	DefaultAMDSTTModel                = "cartesia/ink-whisper"
)
View Source 
const (
	ConsoleWireSampleRate          = 48_000
	ConsoleAgentSampleRate         = 24_000
	DefaultConsoleAudioQueueSize   = 64
	DefaultConsoleMaxFrameDuration = 2 * time.Second
	DefaultConsoleOperationTimeout = 5 * time.Second
	DefaultConsoleSessionDirectory = "console-recordings"
)
View Source 
const (
	DefaultEventQueueCapacity      = 128
	DefaultEventSubscriberCapacity = 32
)
View Source 
const (
	DefaultKeytermDetectionTimeout = 10 * time.Second
	DefaultKeytermDetectionModel   = "google/gemma-4-31b-it"
	KeytermPendingTTL              = 3
	MaxKeytermTranscriptMessages   = 12
)
View Source 
const (
	DefaultRemoteRequestTimeout  = 60 * time.Second
	DefaultRemoteReadyTimeout    = 5 * time.Second
	DefaultRemoteRetryInterval   = 500 * time.Millisecond
	DefaultRemotePendingRequests = 128
	DefaultRemoteEventCapacity   = 64
)
View Source 
const (
	DefaultSessionHostQueueCapacity        = 128
	DefaultSessionHostRequestConcurrency   = 8
	DefaultSessionHostShutdownDrainTimeout = 5 * time.Second
)
View Source 
const (
	SessionMessagesTopic         = "lk.agent.session"
	DefaultSessionMaxMessageSize = 1 << 20
	DefaultRoomSessionQueueSize  = 32
	DefaultTCPDialTimeout        = 10 * time.Second
)
View Source 
const (
	DefaultRunOutputRetries     = 2
	DefaultRunSettleDelay       = 5 * time.Millisecond
	DefaultRunEventCapacity     = 256
	DefaultRunRetryInstructions = "" /* 126-byte string literal not displayed */
)
View Source 
const (
	DefaultMaxToolSteps              = 3
	DefaultUserAwayTimeout           = 15 * time.Second
	DefaultTTSReadIdleTimeout        = 10 * time.Second
	DefaultForwardAudioIdleTimeout   = 10 * time.Second
	DefaultSessionShutdownTimeout    = 5 * time.Second
	DefaultSpeechQueueCapacity       = 64
	DefaultGenerationQueueCapacity   = 16
	DefaultGenerationConcurrency     = 2
	DefaultHandoffQueueCapacity      = 4
	DefaultRecognitionQueueCapacity  = 32
	DefaultSessionEventQueueCapacity = DefaultEventQueueCapacity
)
View Source 
const (
	SpeechPriorityLow    = 0
	SpeechPriorityNormal = 5
	SpeechPriorityHigh   = 10

	ReplyTaskCancelTimeout = 2 * time.Second
	InterruptionTimeout    = 5 * time.Second
)
View Source 
const (
	DefaultToolConcurrency         = 8
	DefaultToolBatchLimit          = 64
	DefaultToolDrainTimeout        = 5 * time.Second
	DefaultToolUpdateQueueCapacity = 64

	UpdateTemplate                = "" /* 157-byte string literal not displayed */
	DuplicateRejectTemplate       = "" /* 151-byte string literal not displayed */
	DuplicateConfirmTemplate      = "" /* 221-byte string literal not displayed */
	ReplyInstructionsAtTail       = "" /* 161-byte string literal not displayed */
	ReplyInstructionsMaybeCovered = "" /* 381-byte string literal not displayed */
)
View Source 
const AMDPrompt = `` /* 1438-byte string literal not displayed */

AMDPrompt is the benchmarked classifier prompt from agents-js 1.7.1 and the Python AMD classifier. Its examples intentionally remain verbatim.

View Source 
const DefaultKeytermDetectionInstructions = `You maintain STT keyterms that bias a recognizer toward the correct spelling of distinctive words (names, places, companies, products, technical terms). Each turn, adjust them with one record_keyterms call.

A WRONG spelling biases the recognizer for the rest of the call with no recovery, so precision beats coverage: apply only a spelling you can CORROBORATE, and when unsure change nothing.

USER lines are raw STT — often wrong, and the same error recurs, so repetition is NOT proof a spelling is right. ASSISTANT lines are the agent's own writing: trust the agent's confident use of its OWN names (brands, staff, locations) and confirm those promptly — but an assistant merely echoing the user's sounds, or hedging about a spelling, does NOT corroborate.

CONFIRM a pending term only when corroborated by one of:
  1. a letter-by-letter spell-out the assistant then accepts WITHOUT reservation — confirm exactly those letters, appending nothing;
  2. the assistant's own confident use of that exact distinctive spelling;
  3. an explicit user correction ("no, not X — it's Y").
Recurrence alone never confirms.

HEDGE RULE: if after a spell-out or name read-back the assistant signals the letters may be off ("for now", "with that caveat", "may have that slightly off", "did I catch that?", "to be confirmed", "I don't want to guess", "double-check"), the spelling is unreliable — keep the term PENDING and never confirm it, EVEN IF the user replies "yes". Only a cleanly accepted spell-out confirms.

Never apply: a user-line word that sounds like a known term (it's that term misheard); a distinctive name glued to an ordinary word ("Blue Haven Hotel" — keep the bare name pending); an odd phrase only the user says and the assistant never adopts; a fragment left by an interruption; ordinary words or fillers.

Report only CHANGES; never re-list an applied term.
  - ` + "`pending`" + `: a distinctive term seen but not yet corroborated;
  - ` + "`confirm`" + `: a pending term that just met the bar above;
  - ` + "`remove`" + `: only a spelling the user just corrected away. Applied terms are otherwise sticky.
If nothing meets the bar this turn, change nothing.`
View Source 
const (
	DefaultRecognitionMaxBufferedFrames = 6000
)
View Source 
const DefaultRunContextFillerCapacity = 8
View Source 
const DefaultRunContextUpdateCapacity = 64

Variables

View Source 
var (
	ErrAgentAlreadyRunning  = errors.New("voice agent already has a running activity")
	ErrAgentNotRunning      = errors.New("voice agent is not running")
	ErrAgentActivityChanged = errors.New("voice agent activity changed during update")
)
View Source 
var (
	ErrAgentTaskAlreadyStarted  = errors.New("voice agent task has already started")
	ErrAgentTaskAlreadyComplete = errors.New("voice agent task is already complete")
	ErrAgentTaskNotComplete     = errors.New("voice agent task is not complete")
)
View Source 
var (
	ErrAMDClosed         = errors.New("voice AMD is closed")
	ErrAMDAlreadyRunning = errors.New("voice AMD execute is already running")
	ErrAMDNoLLM          = errors.New("voice AMD has no LLM available")
	ErrAMDInvalidOptions = errors.New("voice AMD options are invalid")
	ErrAMDNoAudioSource  = errors.New("voice AMD dedicated STT has no audio source")
)
View Source 
var (
	ErrRecognitionStarted = errors.New("audio recognition is already started")
	ErrRecognitionClosed  = errors.New("audio recognition is closed")
)
View Source 
var (
	ErrConsoleIOClosed          = errors.New("voice console IO is closed")
	ErrConsoleIOAlreadyAcquired = errors.New("voice console IO was already acquired by another session")
)
View Source 
var (
	DefaultEndpointingOptions   = EndpointingOptions{Mode: EndpointingFixed, MinDelay: 500 * time.Millisecond, MaxDelay: 3 * time.Second, Alpha: 0.9}
	StreamingEndpointingOptions = EndpointingOptions{Mode: EndpointingFixed, MinDelay: 300 * time.Millisecond, MaxDelay: 2500 * time.Millisecond, Alpha: 0.9}
)
View Source 
var (
	ErrRemoteSessionClosed      = errors.New("voice remote session is closed")
	ErrRemoteSessionNotStarted  = errors.New("voice remote session is not started")
	ErrRemoteRequestTimeout     = errors.New("voice remote session request timed out")
	ErrRemoteRequestLimit       = errors.New("voice remote session pending request limit reached")
	ErrRemoteEventOverflow      = errors.New("voice remote session event subscriber overflow")
	ErrUnexpectedRemoteResponse = errors.New("voice remote session received an unexpected response type")
)
View Source 
var (
	ErrSessionHostClosed       = errors.New("voice session host is closed")
	ErrSessionHostNotStarted   = errors.New("voice session host is not started")
	ErrSessionHostQueueFull    = errors.New("voice session host outgoing queue is full")
	ErrSessionHostRequestLimit = errors.New("voice session host request concurrency limit reached")
	ErrSessionHostAlreadyBound = errors.New("voice session host is already bound to another session")
)
View Source 
var (
	ErrSessionTransportClosed = errors.New("voice session transport is closed")
	ErrSessionFrameTooLarge   = errors.New("voice session transport frame is too large")
	ErrSessionQueueFull       = errors.New("voice session transport queue is full")
)
View Source 
var (
	ErrNestedRun               = errors.New("voice nested runs are not supported")
	ErrUnexpectedModelBehavior = errors.New("voice unexpected model behavior")
)
View Source 
var (
	ErrRunContextDetached       = errors.New("voice run context executor is detached")
	ErrRunContextUpdateOverflow = errors.New("voice run context update capacity exceeded")
)
View Source 
var (
	ErrSessionNotStarted     = errors.New("voice agent session is not started")
	ErrSessionClosing        = errors.New("voice agent session is closing")
	ErrSessionClosed         = errors.New("voice agent session is closed")
	ErrSessionAlreadyStarted = errors.New("voice agent session is already started")
	ErrNoSpeech              = errors.New("voice agent session has no speech to interrupt")
)
View Source 
var (
	ErrSpeechNotDone          = errors.New("speech handle is not done")
	ErrInterruptionsDisabled  = errors.New("speech handle does not allow interruptions")
	ErrNoActiveGeneration     = errors.New("speech handle has no active generation")
	ErrInvalidGenerationIndex = errors.New("speech generation index is invalid")
)
View Source 
var (
	ErrToolExecutorClosed    = errors.New("voice tool executor is closed")
	ErrToolBatchTooLarge     = errors.New("voice tool call batch exceeds configured limit")
	ErrToolTaskNotFound      = errors.New("voice tool task not found")
	ErrToolNotCancellable    = errors.New("voice tool call is not cancellable")
	ErrToolCancellationHeld  = errors.New("voice tool call cancellation is disabled by its speech")
	ErrToolUpdatesBacklogged = errors.New("voice async tool update queue is full")
)
View Source 
var CancelTaskTool = llm.MustTool(llm.FunctionToolOptions[cancelTaskInput, string]{
	Name:        "lk_agents_cancel_task",
	Description: "Cancel a running tool call by call_id.",
	Parameters:  json.RawMessage(`{"type":"object","properties":{"call_id":{"type":"string"}},"required":["call_id"],"additionalProperties":false}`),
	Execute: func(ctx context.Context, input cancelTaskInput, options llm.ToolOptions) (string, error) {
		if options.Context == nil {
			return "", &llm.ToolError{Message: "cancel-task tool requires a RunContext"}
		}
		session, ok := options.Context.Session.(taskToolSession)
		if !ok || session == nil {
			return "", &llm.ToolError{Message: "cancel-task tool requires an AgentSession"}
		}
		if err := session.CancelTool(ctx, input.CallID); err != nil {
			message := err.Error()
			switch {
			case errors.Is(err, ErrToolTaskNotFound):
				message = fmt.Sprintf("Task %s not found", input.CallID)
			case errors.Is(err, ErrToolCancellationHeld):
				message = fmt.Sprintf("Tool call %s is not cancellable because interruptions are disallowed", input.CallID)
			case errors.Is(err, ErrToolNotCancellable):
				message = fmt.Sprintf("Tool call %s is not cancellable", input.CallID)
			}
			return "", &llm.ToolError{Message: message}
		}
		return fmt.Sprintf("Task %s cancelled successfully.", input.CallID), nil
	},
})
View Source 
var DefaultInputDetails = InputDetails{Modality: InputModalityAudio}
View Source 
var DefaultPreemptiveGenerationOptions = PreemptiveGenerationOptions{
	Enabled: true, PreemptiveTTS: false, MaxSpeechDuration: 10 * time.Second, MaxRetries: 3,
}
View Source 
var ErrEventCallbackPanic = errors.New("voice event callback panicked")
View Source 
var (
	ErrKeytermDetectorClosed = errors.New("voice keyterm detector is closed")
)
View Source 
var ErrSpeechQueueClosed = errors.New("speech queue closed")
View Source 
var ErrUnexpectedPlaybackFinished = errors.New("playback finished without a pending segment")
View Source 
var GetRunningTasksTool = llm.MustTool(llm.FunctionToolOptions[struct{}, []*llm.FunctionCall]{
	Name:        "lk_agents_get_running_tasks",
	Description: "Get the list of running tool calls that are cancellable.",
	Execute: func(_ context.Context, _ struct{}, options llm.ToolOptions) ([]*llm.FunctionCall, error) {
		if options.Context == nil {
			return nil, &llm.ToolError{Message: "running-task tool requires a RunContext"}
		}
		session, ok := options.Context.Session.(taskToolSession)
		if !ok || session == nil {
			return nil, &llm.ToolError{Message: "running-task tool requires an AgentSession"}
		}
		return session.cancellableRunningToolCalls(), nil
	},
})

GetRunningTasksTool and CancelTaskTool are automatically advertised whenever an activity contains at least one cancellable tool. They remain exported for callers that want to include them explicitly in a constrained tool context.

Functions

func BindAgentsConsoleJob 

func BindAgentsConsoleJob[UserData any](console *AgentsConsole, job *agents.JobContext[UserData], onSimulationEnd agents.SimulationEndFunc[UserData]) error

BindAgentsConsoleJob supplies the fake console job and simulation callback to the session host without making AgentsConsole itself generic.

func FormatKeytermDetectionInput 

func FormatKeytermDetectionInput(chat *llm.ChatContext, current []KeytermState) (string, bool)

FormatKeytermDetectionInput renders at most the newest twelve transcript messages, then restores chronological order. It excludes blank lines inside turns so blank lines unambiguously delimit turns.

func IsStopResponse 

func IsStopResponse(err error) bool

func RunStructured 

func RunStructured[Output, UserData any](ctx context.Context, session *AgentSession[UserData], options StructuredRunOptions[Output]) (*voicetest.RunResult[Output], error)

RunStructured is the typed Go counterpart of run({outputType}). The current AgentTask result is validated after speech/tool completion; only a missing result is re-prompted.

func SessionReportToJSON 

func SessionReportToJSON(report *SessionReport) (map[string]any, error)

SessionReportToJSON emits the pinned agents-js/Python-compatible report shape used by LiveKit Cloud observability.

func SetDefaultAgentsConsole 

func SetDefaultAgentsConsole(console *AgentsConsole) func()

SetDefaultAgentsConsole installs process-local console state and returns an idempotent restore function. It performs no IO and is safe for nested tests.

func TaskManagementTools 

func TaskManagementTools() []llm.Tool

TaskManagementTools returns a fresh slice containing the built-in task tools.

func ToSnakeCaseDeep 

func ToSnakeCaseDeep(value any) (any, error)

ToSnakeCaseDeep recursively converts JSON-visible camelCase fields to the Python wire names. Provider-owned keys inside an "extra" object are kept verbatim. The special chat-call field "args" becomes "arguments".

func WaitForIdleAndHoldValue 

func WaitForIdleAndHoldValue[UserData, Value any](ctx context.Context, session *AgentSession[UserData], fn func(context.Context, *Agent[UserData]) (Value, error)) (result Value, err error)

WaitForIdleAndHoldValue is the generic result-bearing form. Go methods cannot introduce their own type parameters, so this helper preserves the generic DX without reflection or any-typed return values.

func WithFillerValue 

func WithFillerValue[UserData, Value any](ctx context.Context, run *RunContext[UserData], source FillerSource, options RunContextFillerOptions, fn func(context.Context) (Value, error)) (result Value, err error)

func WithForegroundValue 

func WithForegroundValue[UserData, Value any](ctx context.Context, run *RunContext[UserData], fn func(context.Context, *Agent[UserData]) (Value, error)) (result Value, err error)

WithForegroundValue is the result-bearing form of RunContext.Foreground. Go methods cannot introduce a new result type parameter, so this helper preserves the TypeScript/Python generic callback result without reflection.

func WithFunctionCallContext 

func WithFunctionCallContext(ctx context.Context, handle *SpeechHandle, name string, nonBlocking bool) context.Context

WithFunctionCallContext marks a blocking tool execution for circular-wait detection. Tool runners should wrap user callbacks with this context.

Types

type AMD 

type AMD struct {
	// contains filtered or unexported fields
}

AMD is a reusable detector. Runs are sequential; Close is permanent and closes only inference models constructed from model strings or auto-selection.

func MustAMD 

func MustAMD[UserData any](session *AgentSession[UserData], options AMDOptions) *AMD

MustAMD is the configuration-time convenience counterpart of NewAMD.

func MustAMDWithSession 

func MustAMDWithSession(session AMDSessionAdapter, options AMDOptions) *AMD

MustAMDWithSession panics only for invalid static configuration.

func NewAMD 

func NewAMD[UserData any](session *AgentSession[UserData], options AMDOptions) (*AMD, error)

NewAMD binds AMD to a concrete AgentSession without requiring session or activity source changes.

func NewAMDWithSession 

func NewAMDWithSession(session AMDSessionAdapter, options AMDOptions) (*AMD, error)

func (*AMD) AClose 

func (a *AMD) AClose(ctx context.Context) error

AClose is the migration alias for agents-js aclose().

func (*AMD) Active 

func (a *AMD) Active() bool

func (*AMD) Close 

func (a *AMD) Close(ctx context.Context) error

Close permanently cancels an active run and releases AMD-owned models. It is idempotent; caller-supplied LLM/STT instances remain caller-owned.

func (*AMD) Closed 

func (a *AMD) Closed() bool

func (*AMD) Execute 

func (a *AMD) Execute(ctx context.Context) (AMDPredictionEvent, error)

Execute starts one run and waits for its one-shot prediction.

func (*AMD) LastPrediction 

func (a *AMD) LastPrediction() (AMDPredictionEvent, bool)

func (*AMD) Listening 

func (a *AMD) Listening() bool

func (*AMD) OnEndOfTurn 

func (a *AMD) OnEndOfTurn(ctx context.Context, _ RecognizedTurn) (bool, error)

OnEndOfTurn opens the end-of-turn gate and reports whether a completed machine verdict has taken ownership of this turn's reply.

func (*AMD) OnError 

func (a *AMD) OnError(fn func(AMDErrorEvent)) func()

func (*AMD) OnLLMMetrics 

func (a *AMD) OnLLMMetrics(fn func(metrics.LLM)) func()

func (*AMD) OnMetrics 

func (a *AMD) OnMetrics(fn func(AMDMetrics)) func()

func (*AMD) OnPrediction 

func (a *AMD) OnPrediction(fn func(AMDPredictionEvent)) func()

func (*AMD) OnSTTMetrics 

func (a *AMD) OnSTTMetrics(fn func(metrics.STT)) func()

func (*AMD) OnSessionClosed 

func (a *AMD) OnSessionClosed(ctx context.Context) error

OnSessionClosed forces the pinned uncertain/session_closed fallback.

func (*AMD) OnTranscript 

func (a *AMD) OnTranscript(ctx context.Context, text string) error

OnTranscript consumes a final transcript from the session STT.

func (*AMD) OnTranscriptFrom 

func (a *AMD) OnTranscriptFrom(ctx context.Context, text string, source AMDTranscriptSource) error

func (*AMD) OnUserSpeechEnded 

func (a *AMD) OnUserSpeechEnded(ctx context.Context, silenceDuration time.Duration) error

OnUserSpeechEnded forwards a VAD end boundary. silenceDuration is the trailing silence already elapsed when VAD declared end-of-speech.

func (*AMD) OnUserSpeechStarted 

func (a *AMD) OnUserSpeechStarted(ctx context.Context) error

OnUserSpeechStarted forwards a VAD start boundary into the two-gate classifier.

func (*AMD) Start 

func (a *AMD) Start(parent context.Context) (*AMDExecution, error)

Start begins detection and returns immediately, matching the Promise-style concurrency used to start AMD before dialing a SIP participant.

type AMDAudioSource 

type AMDAudioSource interface {
	SubscribeAMD(context.Context) (AMDAudioSubscription, error)
}

type AMDAudioSourceFunc 

type AMDAudioSourceFunc func(context.Context) (AMDAudioSubscription, error)

func (AMDAudioSourceFunc) SubscribeAMD 

func (f AMDAudioSourceFunc) SubscribeAMD(ctx context.Context) (AMDAudioSubscription, error)

type AMDAudioSubscription 

type AMDAudioSubscription interface {
	Recv(context.Context) (agents.AudioFrame, error)
	Close() error
}

AMDAudioSubscription is an independently closable branch of participant audio. RoomIO's primary AudioInput is single-consumer, so adapters must tee frames rather than return that primary reader directly.

type AMDCategory 

type AMDCategory string

AMDCategory is the pinned agents-js 1.7.1 answering-machine verdict. 

const (
	AMDCategoryHuman              AMDCategory = "human"
	AMDCategoryMachineIVR         AMDCategory = "machine-ivr"
	AMDCategoryMachineVM          AMDCategory = "machine-vm"
	AMDCategoryMachineUnavailable AMDCategory = "machine-unavailable"
	AMDCategoryUncertain          AMDCategory = "uncertain"
)

type AMDErrorEvent 

type AMDErrorEvent struct {
	Timestamp time.Time
	Operation string
	Err       error
}

type AMDExecution 

type AMDExecution struct {
	// contains filtered or unexported fields
}

AMDExecution is a one-shot result handle analogous to the Promise returned by agents-js execute(). Wait does not cancel the run; the context passed to Start owns execution, while Wait's context only bounds that wait.

func (*AMDExecution) Cancel 

func (e *AMDExecution) Cancel(cause error)

Cancel stops this execution without closing the reusable detector.

func (*AMDExecution) Done 

func (e *AMDExecution) Done() <-chan struct{}

func (*AMDExecution) Wait 

func (e *AMDExecution) Wait(ctx context.Context) (AMDPredictionEvent, error)

type AMDListeningGate 

type AMDListeningGate interface {
	WaitForAudio(context.Context, string) error
}

AMDListeningGate is the RTC/RoomIO seam. Implementations wait until the selected participant has subscribed audio and, for SIP, callStatus=active. Returning an error settles the run as uncertain/participant_missing.

type AMDListeningGateFunc 

type AMDListeningGateFunc func(context.Context, string) error

func (AMDListeningGateFunc) WaitForAudio 

func (f AMDListeningGateFunc) WaitForAudio(ctx context.Context, identity string) error

type AMDMetrics 

type AMDMetrics struct {
	Timestamp      time.Time
	Duration       time.Duration
	Category       AMDCategory
	Reason         string
	IsMachine      bool
	SpeechDuration time.Duration
	Delay          time.Duration
	Transcript     string
}

AMDMetrics is the allocation-light lifecycle metric emitted with a verdict. Model-specific token/audio metrics remain available via OnLLMMetrics and OnSTTMetrics.

type AMDOptionError 

type AMDOptionError struct {
	Field string
	Err   error
}

AMDOptionError identifies a rejected option while remaining compatible with errors.Is(err, ErrAMDInvalidOptions).

func (*AMDOptionError) Error 

func (e *AMDOptionError) Error() string

func (*AMDOptionError) Unwrap 

func (e *AMDOptionError) Unwrap() []error

type AMDOptions 

type AMDOptions struct {
	LLM      llm.LLM
	LLMModel string
	STT      stt.STT
	STTModel string

	InterruptOnMachine           *bool
	NoSpeechTimeout              *time.Duration
	DetectionTimeout             *time.Duration
	HumanSpeechThreshold         *time.Duration
	HumanSilenceThreshold        *time.Duration
	MachineSilenceThreshold      *time.Duration
	WaitUntilFinished            *bool
	MaxEndpointingDelay          *time.Duration
	Prompt                       *string
	ParticipantIdentity          string
	SuppressCompatibilityWarning bool

	ListeningGate           AMDListeningGate
	TrackPublicationTimeout *time.Duration
	AudioSource             AMDAudioSource
	Interrupt               func(context.Context, AMDPredictionEvent) error
	InterruptTimeout        time.Duration
	CloseTimeout            time.Duration
	EventCapacity           int
	OnError                 func(AMDErrorEvent)
}

AMDOptions preserves the agents-js option semantics. Pointer scalar fields distinguish omission from an intentional zero/false value.

type AMDPanicError 

type AMDPanicError struct {
	Operation string
	Value     any
	Stack     []byte
}

AMDPanicError converts extension callback/provider panics into ordinary, inspectable errors rather than allowing a media or lifecycle goroutine to die.

func (*AMDPanicError) Error 

func (e *AMDPanicError) Error() string

type AMDPredictionEvent 

type AMDPredictionEvent struct {
	EventBase
	Category         AMDCategory `json:"category"`
	Transcript       string      `json:"transcript"`
	Reason           string      `json:"reason"`
	RawResponse      string      `json:"rawResponse"`
	IsMachine        bool        `json:"isMachine"`
	SpeechDurationMS int64       `json:"speechDurationMs"`
	DelayMS          int64       `json:"delayMs"`
}

AMDPredictionEvent is emitted once for every successful Execute run. Durations retain the exact millisecond wire names used by agents-js.

func (AMDPredictionEvent) Delay 

func (e AMDPredictionEvent) Delay() time.Duration

func (AMDPredictionEvent) SpeechDuration 

func (e AMDPredictionEvent) SpeechDuration() time.Duration

type AMDSessionAdapter 

type AMDSessionAdapter struct {
	PauseReplyAuthorization  func() error
	ResumeReplyAuthorization func() error
	Subscribe                func(EventSubscriptionOptions) (*EventSubscription, error)
	CurrentLLM               func() llm.LLM
	MaxEndpointingDelay      func() time.Duration
	Interrupt                func(context.Context, bool) error
	PublishPrediction        func(context.Context, AMDPredictionEvent) error
	Bind                     func(*AMD)
}

AMDSessionAdapter is the narrow test/remote-session seam. Subscribe may be nil when the application drives the recognition hooks manually. CurrentLLM is consulted only when neither an explicit LLM nor Cloud auto-selection is available.

func AdaptAMDSession 

func AdaptAMDSession[UserData any](session *AgentSession[UserData]) AMDSessionAdapter

AdaptAMDSession exposes only the lifecycle/model hooks AMD needs. It also powers AgentSession.AMD without adding per-session memory when AMD is unused.

type AMDTranscriptSource 

type AMDTranscriptSource string

AMDTranscriptSource prevents the session STT and a dedicated AMD STT from double-feeding the classifier. 

const (
	AMDTranscriptSourceSessionSTT   AMDTranscriptSource = "stt"
	AMDTranscriptSourceDedicatedSTT AMDTranscriptSource = "amd_stt"
)

type ActivityPanicError 

type ActivityPanicError struct {
	Operation string
	Value     any
	Stack     []byte
}

func (*ActivityPanicError) Error 

func (e *ActivityPanicError) Error() string

type Agent 

type Agent[UserData any] struct {
	// contains filtered or unexported fields
}

func MustAgent 

func MustAgent[UserData any](options AgentOptions[UserData]) *Agent[UserData]

func NewAgent 

func NewAgent[UserData any](options AgentOptions[UserData]) (*Agent[UserData], error)

func (*Agent[UserData]) ChatContext 

func (a *Agent[UserData]) ChatContext() *llm.ChatContext

func (*Agent[UserData]) ExpressiveOverride 

func (a *Agent[UserData]) ExpressiveOverride() agents.Override[ExpressiveOptions]

func (*Agent[UserData]) ID 

func (a *Agent[UserData]) ID() string

func (*Agent[UserData]) Instructions 

func (a *Agent[UserData]) Instructions() llm.Instructions

func (*Agent[UserData]) LLMOverride 

func (a *Agent[UserData]) LLMOverride() agents.Override[llm.LLM]

func (*Agent[UserData]) MinConsecutiveSpeechDelay 

func (a *Agent[UserData]) MinConsecutiveSpeechDelay() *time.Duration

func (*Agent[UserData]) RealtimeOverride 

func (a *Agent[UserData]) RealtimeOverride() agents.Override[llm.RealtimeModel]

func (*Agent[UserData]) STTOverride 

func (a *Agent[UserData]) STTOverride() agents.Override[stt.STT]

func (*Agent[UserData]) Session 

func (a *Agent[UserData]) Session() (AgentSessionAccess[UserData], error)

func (*Agent[UserData]) TTSOverride 

func (a *Agent[UserData]) TTSOverride() agents.Override[tts.TTS]

func (*Agent[UserData]) ToolContext 

func (a *Agent[UserData]) ToolContext() *llm.Context

func (*Agent[UserData]) TurnHandling 

func (a *Agent[UserData]) TurnHandling() *TurnHandlingOptions

func (*Agent[UserData]) UpdateChatContext 

func (a *Agent[UserData]) UpdateChatContext(ctx context.Context, chat *llm.ChatContext) error

func (*Agent[UserData]) UpdateInstructions 

func (a *Agent[UserData]) UpdateInstructions(ctx context.Context, instructions llm.Instructions) error

func (*Agent[UserData]) UpdateOptions 

func (a *Agent[UserData]) UpdateOptions(ctx context.Context, update AgentUpdateOptions) error

func (*Agent[UserData]) UpdateTools 

func (a *Agent[UserData]) UpdateTools(ctx context.Context, tools *llm.Context) error

func (*Agent[UserData]) UseTTSAlignedTranscript 

func (a *Agent[UserData]) UseTTSAlignedTranscript() *bool

func (*Agent[UserData]) VADOverride 

func (a *Agent[UserData]) VADOverride() agents.Override[vad.VAD]

type AgentContext 

type AgentContext[UserData any] struct {
	// contains filtered or unexported fields
}

func (*AgentContext[UserData]) Agent 

func (c *AgentContext[UserData]) Agent() *Agent[UserData]

func (*AgentContext[UserData]) ChatContext 

func (c *AgentContext[UserData]) ChatContext() *llm.ChatContext

func (*AgentContext[UserData]) ID 

func (c *AgentContext[UserData]) ID() string

func (*AgentContext[UserData]) Instructions 

func (c *AgentContext[UserData]) Instructions() llm.Instructions

func (*AgentContext[UserData]) Session 

func (c *AgentContext[UserData]) Session() (AgentSessionAccess[UserData], error)

func (*AgentContext[UserData]) ToolContext 

func (c *AgentContext[UserData]) ToolContext() *llm.Context

type AgentFalseInterruptionEvent 

type AgentFalseInterruptionEvent struct {
	EventBase
	Resumed bool `json:"resumed"`
}

type AgentHooks 

type AgentHooks[UserData any] struct {
	OnEnter                 func(context.Context, *AgentContext[UserData]) error
	OnExit                  func(context.Context, *AgentContext[UserData]) error
	OnUserTurnCompleted     func(context.Context, *AgentContext[UserData], *llm.ChatContext, *llm.ChatMessage) error
	OnUserTurnExceeded      func(context.Context, *AgentContext[UserData], UserTurnExceededEvent) error
	STTNode                 func(context.Context, *AgentContext[UserData], stream.Reader[agents.AudioFrame], ModelSettings) (stream.Reader[STTNodeItem], error)
	LLMNode                 func(context.Context, *AgentContext[UserData], *llm.ChatContext, *llm.Context, ModelSettings) (stream.Reader[LLMNodeItem], error)
	TTSNode                 func(context.Context, *AgentContext[UserData], stream.Reader[string], ModelSettings) (stream.Reader[agents.AudioFrame], error)
	RealtimeAudioOutputNode func(context.Context, *AgentContext[UserData], stream.Reader[agents.AudioFrame], ModelSettings) (stream.Reader[agents.AudioFrame], error)
	TranscriptionNode       func(context.Context, *AgentContext[UserData], stream.Reader[TranscriptionNodeItem], ModelSettings) (stream.Reader[TranscriptionNodeItem], error)
}

type AgentInput 

type AgentInput struct {
	// contains filtered or unexported fields
}

func NewAgentInput 

func NewAgentInput(onChanged func(), onEnabled func(bool)) *AgentInput

func (*AgentInput) Audio 

func (i *AgentInput) Audio() AudioInput

func (*AgentInput) AudioEnabled 

func (i *AgentInput) AudioEnabled() bool

func (*AgentInput) SetAudio 

func (i *AgentInput) SetAudio(audio AudioInput)

func (*AgentInput) SetAudioEnabled 

func (i *AgentInput) SetAudioEnabled(enabled bool)

type AgentOptions 

type AgentOptions[UserData any] struct {
	ID           string
	Instructions llm.Instructions
	ChatContext  *llm.ChatContext
	Tools        *llm.Context
	STT          agents.Override[stt.STT]
	VAD          agents.Override[vad.VAD]
	LLM          agents.Override[llm.LLM]
	Realtime     agents.Override[llm.RealtimeModel]
	TTS          agents.Override[tts.TTS]
	Expressive   agents.Override[ExpressiveOptions]
	TurnHandling *TurnHandlingOptions
	ToolHandling ToolHandlingOptions

	MinConsecutiveSpeechDelay *time.Duration
	UseTTSAlignedTranscript   *bool
	Hooks                     AgentHooks[UserData]
}

type AgentOutput 

type AgentOutput struct {
	// contains filtered or unexported fields
}

func NewAgentOutput 

func NewAgentOutput(onAudioChanged, onTextChanged func()) *AgentOutput

func (*AgentOutput) Audio 

func (o *AgentOutput) Audio() AudioOutput

func (*AgentOutput) AudioEnabled 

func (o *AgentOutput) AudioEnabled() bool

func (*AgentOutput) SetAudio 

func (o *AgentOutput) SetAudio(audio AudioOutput)

func (*AgentOutput) SetAudioEnabled 

func (o *AgentOutput) SetAudioEnabled(enabled bool)

func (*AgentOutput) SetTranscription 

func (o *AgentOutput) SetTranscription(text TextOutput)

func (*AgentOutput) SetTranscriptionEnabled 

func (o *AgentOutput) SetTranscriptionEnabled(enabled bool)

func (*AgentOutput) Transcription 

func (o *AgentOutput) Transcription() TextOutput

func (*AgentOutput) TranscriptionEnabled 

func (o *AgentOutput) TranscriptionEnabled() bool

type AgentSession 

type AgentSession[UserData any] struct {
	// contains filtered or unexported fields
}

AgentSession is the context-first Go equivalent of the Python/TypeScript AgentSession. It owns activities, streams, queues and events, but not model instances supplied in AgentSessionOptions.

func NewAgentSession 

func NewAgentSession[UserData any](options AgentSessionOptions[UserData]) (*AgentSession[UserData], error)

func (*AgentSession[UserData]) AMD 

func (s *AgentSession[UserData]) AMD() *AMD

AMD returns the detector most recently constructed for this session, or nil. The registry entry is removed by AMD.Close and therefore does not retain a closed session.

func (*AgentSession[UserData]) Agent 

func (s *AgentSession[UserData]) Agent() *Agent[UserData]

func (*AgentSession[UserData]) AgentState 

func (s *AgentSession[UserData]) AgentState() AgentState

func (*AgentSession[UserData]) CancelTool 

func (s *AgentSession[UserData]) CancelTool(ctx context.Context, callID string) error

func (*AgentSession[UserData]) ChatContext 

func (s *AgentSession[UserData]) ChatContext() *llm.ChatContext

func (*AgentSession[UserData]) ClearUserTurn 

func (s *AgentSession[UserData]) ClearUserTurn(ctx context.Context) error

func (*AgentSession[UserData]) Close 

func (s *AgentSession[UserData]) Close(ctx context.Context, options ...CloseOptions) error

func (*AgentSession[UserData]) Closing 

func (s *AgentSession[UserData]) Closing() bool

func (*AgentSession[UserData]) CommitUserTurn 

func (s *AgentSession[UserData]) CommitUserTurn(ctx context.Context) error

func (*AgentSession[UserData]) Drain 

func (s *AgentSession[UserData]) Drain(ctx context.Context) error

Drain stops accepting new work and waits for all already accepted speech. It is idempotent; call Close afterwards to release streams and subscriptions.

func (*AgentSession[UserData]) GenerateReply 

func (s *AgentSession[UserData]) GenerateReply(ctx context.Context, options GenerateReplyOptions) (*SpeechHandle, error)

func (*AgentSession[UserData]) Input 

func (s *AgentSession[UserData]) Input() *AgentInput

func (*AgentSession[UserData]) Interrupt 

func (s *AgentSession[UserData]) Interrupt(ctx context.Context, force bool) error

func (*AgentSession[UserData]) KeytermDetector 

func (s *AgentSession[UserData]) KeytermDetector() *KeytermDetector

KeytermDetector returns the session-scoped detector. Its confirmed state is retained across agent handoffs; callers may update static terms at runtime.

func (*AgentSession[UserData]) OnEvent 

func (s *AgentSession[UserData]) OnEvent(fn func(Event), options EventSubscriptionOptions) (func(), error)

func (*AgentSession[UserData]) Output 

func (s *AgentSession[UserData]) Output() *AgentOutput

func (*AgentSession[UserData]) PauseReplyAuthorization 

func (s *AgentSession[UserData]) PauseReplyAuthorization() error

func (*AgentSession[UserData]) ReportOptions 

func (s *AgentSession[UserData]) ReportOptions(recording RecordingOptions) ReportSessionOptions

ReportOptions returns the immutable session configuration used by the cross-SDK SessionReport contract. Recording is supplied by the job/session registration layer because it can inherit dispatch policy and be demoted for a secondary session.

func (*AgentSession[UserData]) ResumeReplyAuthorization 

func (s *AgentSession[UserData]) ResumeReplyAuthorization() error

func (*AgentSession[UserData]) Run 

func (s *AgentSession[UserData]) Run(ctx context.Context, options RunOptions) (*voicetest.RunResult[any], error)

Run starts one deterministic test turn and records messages, function calls, function outputs, and handoffs in creation order. It is safe without a room.

func (*AgentSession[UserData]) RunningTools 

func (s *AgentSession[UserData]) RunningTools() []RunningTool

RunningTools returns every user callback that has not settled, including a cancelled callback that has ignored its context. The built-in task-list tool intentionally exposes only live cancellable entries.

func (*AgentSession[UserData]) Say 

func (s *AgentSession[UserData]) Say(ctx context.Context, text string, options SayOptions) (*SpeechHandle, error)

func (*AgentSession[UserData]) SayStream 

func (s *AgentSession[UserData]) SayStream(ctx context.Context, text stream.Reader[string], options SayOptions) (*SpeechHandle, error)

func (*AgentSession[UserData]) Start 

func (s *AgentSession[UserData]) Start(ctx context.Context, agent *Agent[UserData]) (resultErr error)

func (*AgentSession[UserData]) Started 

func (s *AgentSession[UserData]) Started() bool

func (*AgentSession[UserData]) Subscribe 

func (s *AgentSession[UserData]) Subscribe(options EventSubscriptionOptions) (*EventSubscription, error)

func (*AgentSession[UserData]) ToolHandling 

func (s *AgentSession[UserData]) ToolHandling() ToolHandlingOptions

func (*AgentSession[UserData]) UpdateAgent 

func (s *AgentSession[UserData]) UpdateAgent(ctx context.Context, agent *Agent[UserData]) error

func (*AgentSession[UserData]) Usage 

func (s *AgentSession[UserData]) Usage() AgentSessionUsage

func (*AgentSession[UserData]) UserData 

func (s *AgentSession[UserData]) UserData() *UserData

func (*AgentSession[UserData]) UserState 

func (s *AgentSession[UserData]) UserState() UserState

func (*AgentSession[UserData]) WaitForIdle 

func (s *AgentSession[UserData]) WaitForIdle(ctx context.Context, options ...WaitForIdleOptions) (*Agent[UserData], error)

WaitForIdle waits without polling until the selected sides of the active conversation are inactive. Activity handoffs are retried transparently.

func (*AgentSession[UserData]) WaitForIdleAndHold 

func (s *AgentSession[UserData]) WaitForIdleAndHold(ctx context.Context, fn func(context.Context, *Agent[UserData]) error) error

WaitForIdleAndHold runs fn while other idle waiters are held behind an event-driven barrier. The derived callback context makes nested holds on the same session reentrant.

type AgentSessionAccess 

type AgentSessionAccess[UserData any] interface {
	UserData() *UserData
	ChatContext() *llm.ChatContext
	Say(context.Context, string, SayOptions) (*SpeechHandle, error)
	SayStream(context.Context, stream.Reader[string], SayOptions) (*SpeechHandle, error)
	GenerateReply(context.Context, GenerateReplyOptions) (*SpeechHandle, error)
	Interrupt(context.Context, bool) error
}

AgentSessionAccess is the hook-safe subset of AgentSession. Context is first on every operation that can block, and text streams have a separate typed method instead of a dynamic string/stream union.

type AgentSessionOptions 

type AgentSessionOptions[UserData any] struct {
	STT stt.STT
	VAD vad.VAD
	// VADSelection is the explicit inherit/use/disable form of VAD. Its zero
	// value auto-provisions a lazy inference.VAD when VAD is nil. Use
	// agents.Disable[vad.VAD]() to opt out. VAD and a non-inherited selection
	// are mutually exclusive.
	VADSelection agents.Override[vad.VAD]
	LLM          llm.LLM
	// Realtime is mutually exclusive with LLM. Agent-level tri-state
	// overrides may select a different Chat or realtime model per handoff.
	Realtime llm.RealtimeModel
	TTS      tts.TTS
	// Model-string alternatives mirror the TypeScript/Python inference
	// shorthand (for example "openai/gpt-4.1-mini"). A concrete model and its
	// model string are mutually exclusive. Models resolved here are session-owned.
	STTModel string
	LLMModel string
	TTSModel string

	UserData UserData
	Tools    *llm.Context

	ConnectOptions agents.SessionConnectOptions
	TurnHandling   *TurnHandlingOptions
	Keyterms       KeytermsOptions
	ToolHandling   ToolHandlingOptions
	Expressive     agents.Override[ExpressiveOptions]

	MaxToolSteps            int
	UserAwayTimeout         *time.Duration
	DisableUserAwayTimeout  bool
	TranscriptionTimeout    *time.Duration
	TTSReadIdleTimeout      time.Duration
	ForwardAudioIdleTimeout time.Duration
	ShutdownTimeout         time.Duration
	UseTTSAlignedTranscript *bool

	SpeechQueueCapacity      int
	GenerationQueueCapacity  int
	GenerationConcurrency    int
	RecognitionQueueCapacity int
	EventQueueCapacity       int

	// ParentContext owns the session lifetime. A nil context uses Background;
	// Start's context only bounds start-up and never accidentally owns a running
	// session after Start returns.
	ParentContext context.Context
}

AgentSessionOptions configures one reusable model set and its bounded voice pipeline. Model implementations are caller-owned and are never closed by the session; activity streams created from them are always closed.

type AgentSessionUsage 

type AgentSessionUsage struct {
	ModelUsage []metrics.ModelUsage `json:"modelUsage"`
}

type AgentState 

type AgentState string
const (
	AgentStateInitializing AgentState = "initializing"
	AgentStateIdle         AgentState = "idle"
	AgentStateListening    AgentState = "listening"
	AgentStateThinking     AgentState = "thinking"
	AgentStateSpeaking     AgentState = "speaking"
)

type AgentStateChangedEvent 

type AgentStateChangedEvent struct {
	EventBase
	OldState AgentState `json:"oldState"`
	NewState AgentState `json:"newState"`
}

func NewAgentStateChangedEvent 

func NewAgentStateChangedEvent(oldState, newState AgentState, createdAt time.Time) AgentStateChangedEvent

type AgentTask 

type AgentTask[Result, UserData any] struct {
	*Agent[UserData]
	// contains filtered or unexported fields
}

AgentTask is an Agent that produces exactly one typed result. Run is intentionally one-shot, matching Python/TypeScript foreground handoff semantics; Wait may be called repeatedly by independent observers.

func MustAgentTask 

func MustAgentTask[Result, UserData any](options AgentTaskOptions[UserData]) *AgentTask[Result, UserData]

func NewAgentTask 

func NewAgentTask[Result, UserData any](options AgentTaskOptions[UserData]) (*AgentTask[Result, UserData], error)

func (*AgentTask[Result, UserData]) Complete 

func (t *AgentTask[Result, UserData]) Complete(result Result) error

func (*AgentTask[Result, UserData]) Done 

func (t *AgentTask[Result, UserData]) Done() bool

func (*AgentTask[Result, UserData]) Fail 

func (t *AgentTask[Result, UserData]) Fail(err error) error

func (*AgentTask[Result, UserData]) OnDone 

func (t *AgentTask[Result, UserData]) OnDone(callback func(*AgentTask[Result, UserData])) func()

func (*AgentTask[Result, UserData]) PreserveFunctionCallHistory 

func (t *AgentTask[Result, UserData]) PreserveFunctionCallHistory() bool

func (*AgentTask[Result, UserData]) Result 

func (t *AgentTask[Result, UserData]) Result() (Result, error)

func (*AgentTask[Result, UserData]) Run 

func (t *AgentTask[Result, UserData]) Run(ctx context.Context) (Result, error)

func (*AgentTask[Result, UserData]) Wait 

func (t *AgentTask[Result, UserData]) Wait(ctx context.Context) (Result, error)

type AgentTaskOptions 

type AgentTaskOptions[UserData any] struct {
	AgentOptions                AgentOptions[UserData]
	PreserveFunctionCallHistory bool
}

type AgentUpdateOptions 

type AgentUpdateOptions struct {
	STT        *agents.Override[stt.STT]
	VAD        *agents.Override[vad.VAD]
	LLM        *agents.Override[llm.LLM]
	Realtime   *agents.Override[llm.RealtimeModel]
	TTS        *agents.Override[tts.TTS]
	Expressive *agents.Override[ExpressiveOptions]
}

type AgentsConsole 

type AgentsConsole struct {
	// contains filtered or unexported fields
}

AgentsConsole carries console transport/IO from the CLI runner into the AgentSession constructed by the user's entrypoint. Initialization is lazy; normal workers pay only one atomic load in AgentSession.Start.

func DefaultAgentsConsole 

func DefaultAgentsConsole() *AgentsConsole

func NewAgentsConsole 

func NewAgentsConsole(options AgentsConsoleOptions) (*AgentsConsole, error)

func (*AgentsConsole) Close 

func (c *AgentsConsole) Close(ctx context.Context) error

func (*AgentsConsole) CloseRecording 

func (c *AgentsConsole) CloseRecording(ctx context.Context) error

CloseRecording finalizes the optional console recorder without closing the console transport. It is concurrent, idempotent, and uses an internal cleanup deadline so a caller timeout cannot strand the recorder workers.

func (*AgentsConsole) Enabled 

func (c *AgentsConsole) Enabled() bool

func (*AgentsConsole) IOAcquired 

func (c *AgentsConsole) IOAcquired() bool

func (*AgentsConsole) Record 

func (c *AgentsConsole) Record() bool

func (*AgentsConsole) RecordingInfo 

func (c *AgentsConsole) RecordingInfo() ConsoleRecordingInfo

RecordingInfo returns recorder metadata without transferring ownership.

func (*AgentsConsole) SessionDirectory 

func (c *AgentsConsole) SessionDirectory() string

func (*AgentsConsole) SetRecordingIO 

func (c *AgentsConsole) SetRecordingIO(input AudioInput, output AudioOutput, recording ConsoleRecording) error

SetRecordingIO installs ownership-neutral decorators around the TCP audio bridges. It must be called before an AgentSession acquires the console.

type AgentsConsoleOptions 

type AgentsConsoleOptions struct {
	Enabled          bool
	Record           bool
	Transport        SessionTransport
	AudioInput       *TCPAudioInput
	AudioOutput      *TCPAudioOutput
	SessionDirectory string
}

type AsyncToolOptions 

type AsyncToolOptions = llm.AsyncToolOptions

type Attachable 

type Attachable interface {
	SetAttached(bool)
	OnAttached()
	OnDetached()
}

type AudioInput 

type AudioInput interface {
	stream.Reader[agents.AudioFrame]
	Attachable
	Close() error
}

type AudioOutput 

type AudioOutput interface {
	CaptureFrame(context.Context, agents.AudioFrame) error
	Flush(context.Context) error
	ClearBuffer(context.Context) error
	WaitForPlayout(context.Context) (PlaybackFinishedEvent, error)
	Pause(context.Context) error
	Resume(context.Context) error
	CanPause() bool
	SampleRate() int
	Attachable
	OnPlaybackStarted(func(PlaybackStartedEvent)) func()
	OnPlaybackFinished(func(PlaybackFinishedEvent)) func()
	PendingPlayoutSegments() uint64
	CapturedPlayoutSegments() uint64
}

type AudioOutputCapabilities 

type AudioOutputCapabilities struct {
	Pause bool
}

type AudioOutputOptions 

type AudioOutputOptions struct {
	SampleRate   int
	Capabilities AudioOutputCapabilities
	Next         AudioOutput
	Capture      func(context.Context, agents.AudioFrame) error
	Flush        func(context.Context) error
	ClearBuffer  func(context.Context) error
	Pause        func(context.Context) error
	Resume       func(context.Context) error
	Attached     func()
	Detached     func()
}

type AudioRecognition 

type AudioRecognition struct {
	// contains filtered or unexported fields
}

AudioRecognition serializes VAD, STT, endpointing and manual commits through one bounded actor. Provider readers never mutate turn state directly.

func NewAudioRecognition 

func NewAudioRecognition(parent context.Context, options AudioRecognitionOptions) (*AudioRecognition, error)

func (*AudioRecognition) AgentSpeechEnded 

func (r *AudioRecognition) AgentSpeechEnded(ctx context.Context, at time.Time) error

AgentSpeechEnded closes an adaptive overlap interval and resets the detector for the next audible agent segment.

func (*AudioRecognition) AgentSpeechStarted 

func (r *AudioRecognition) AgentSpeechStarted(ctx context.Context, at time.Time) error

AgentSpeechStarted marks audible agent playout for adaptive overlap classification. It is serialized with recognition state and is a no-op when adaptive interruption is not active.

func (*AudioRecognition) Busy 

func (r *AudioRecognition) Busy() bool

Busy reports whether a user turn is open, including pending EOT/adaptive decisions after VAD has returned to listening.

func (*AudioRecognition) Clear 

func (r *AudioRecognition) Clear(ctx context.Context) error

func (*AudioRecognition) Close 

func (r *AudioRecognition) Close(ctx context.Context) error

func (*AudioRecognition) Commit 

func (r *AudioRecognition) Commit(ctx context.Context) error

func (*AudioRecognition) DisableAdaptiveInterruption 

func (r *AudioRecognition) DisableAdaptiveInterruption(ctx context.Context) error

DisableAdaptiveInterruption atomically falls back to the VAD interruption gate after an unrecoverable adaptive-detector error.

func (*AudioRecognition) Start 

func (r *AudioRecognition) Start(source stream.Reader[agents.AudioFrame]) error

type AudioRecognitionCallbacks 

type AudioRecognitionCallbacks struct {
	OnStartOfSpeech     func(time.Time)
	OnEndOfSpeech       func(time.Time)
	OnInterimTranscript func(stt.SpeechEvent)
	OnFinalTranscript   func(stt.SpeechEvent)
	// OnCommitAudio fires once for each input epoch before transcript commit.
	// Realtime models without server turn detection use it to commit the
	// provider audio even when local STT has not produced text yet.
	OnCommitAudio       func()
	OnCommitAudioResult func() error
	OnCommit            func(RecognizedTurn)
	// OnCommitDecision is the voice-runtime hook. Returning false suppresses
	// reply generation (for example StopResponse from OnUserTurnCompleted).
	OnCommitDecision       func(RecognizedTurn) bool
	OnCommitComplete       func(bool)
	OnInterruption         func(time.Duration, int)
	OnUserTurnExceeded     func(RecognizedTurn)
	OnTranscriptionTimeout func(time.Duration, time.Time)
	OnEOTPrediction        func(inference.TurnDetectionEvent, float64, time.Duration)
	OnOverlappingSpeech    func(inference.OverlappingSpeechEvent)
	OnBackchannel          func(RecognizedTurn)
	OnActivityChanged      func()
	OnError                func(error, any)
}

type AudioRecognitionOptions 

type AudioRecognitionOptions struct {
	STT                  stt.STT
	VAD                  vad.VAD
	TurnDetector         *inference.TurnDetector
	InterruptionDetector *inference.AdaptiveInterruptionDetector

	STTNode func(context.Context, stream.Reader[agents.AudioFrame]) (stream.Reader[STTNodeItem], error)
	// AudioSink receives each validated frame from the single input pump. It is
	// used to feed a realtime session without teeing or duplicating goroutines.
	AudioSink func(context.Context, agents.AudioFrame) error

	TurnDetection        TurnDetectionMode
	Endpointing          Endpointing
	Interruption         InterruptionOptions
	UserTurnLimit        UserTurnLimitOptions
	ConnectOptions       agents.APIConnectOptions
	TranscriptionTimeout *time.Duration
	QueueCapacity        int
	MaxBufferedFrames    int
	Callbacks            AudioRecognitionCallbacks
}

type BackchannelBoundary 

type BackchannelBoundary struct {
	Start time.Duration
	End   time.Duration
}

type BaseAudioInput 

type BaseAudioInput struct {
	// contains filtered or unexported fields
}

BaseAudioInput combines dynamically attached bounded frame sources.

func NewBaseAudioInput 

func NewBaseAudioInput(parent context.Context, capacity int, onError func(string, error)) *BaseAudioInput

func (*BaseAudioInput) Add 

func (i *BaseAudioInput) Add(source stream.Reader[agents.AudioFrame]) (string, error)

func (*BaseAudioInput) Attached 

func (i *BaseAudioInput) Attached() bool

func (*BaseAudioInput) Close 

func (i *BaseAudioInput) Close() error

func (*BaseAudioInput) OnAttached 

func (*BaseAudioInput) OnAttached()

func (*BaseAudioInput) OnDetached 

func (*BaseAudioInput) OnDetached()

func (*BaseAudioInput) Recv 

func (i *BaseAudioInput) Recv(ctx context.Context) (agents.AudioFrame, error)

func (*BaseAudioInput) Remove 

func (i *BaseAudioInput) Remove(id string)

func (*BaseAudioInput) SetAttached 

func (i *BaseAudioInput) SetAttached(attached bool)

type CloseEvent 

type CloseEvent struct {
	EventBase
	Err    error       `json:"-"`
	Reason CloseReason `json:"reason"`
}

func NewCloseEvent 

func NewCloseEvent(reason CloseReason, err error, createdAt time.Time) CloseEvent

type CloseOptions 

type CloseOptions struct {
	Reason CloseReason
	Err    error
	// Drain lets already accepted speech finish. The default interrupts all
	// speech before teardown.
	Drain bool
}

type CloseReason 

type CloseReason string
const (
	CloseReasonError                   CloseReason = "error"
	CloseReasonJobShutdown             CloseReason = "job_shutdown"
	CloseReasonParticipantDisconnected CloseReason = "participant_disconnected"
	CloseReasonUserInitiated           CloseReason = "user_initiated"
)

type ConsoleRecording 

type ConsoleRecording interface{ Close(context.Context) error }

ConsoleRecording owns optional audio decorators installed for --record. RecorderIO satisfies this interface without creating a voice import cycle.

type ConsoleRecordingInfo 

type ConsoleRecordingInfo struct {
	OutputPath string
	StartedAt  time.Time
	HasStarted bool
}

ConsoleRecordingInfo is a best-effort metadata snapshot exposed by a console recorder. Custom ConsoleRecording implementations may omit either field.

type ConversationItemAddedEvent 

type ConversationItemAddedEvent struct {
	EventBase
	Item llm.ChatItem `json:"item"`
}

type DebugMessageEvent 

type DebugMessageEvent struct {
	EventBase
	Payload map[string]any `json:"payload"`
}

type DetectKeytermsOptions 

type DetectKeytermsOptions struct {
	Instructions    string
	CurrentKeyterms []KeytermState
}

type DynamicEndpointing 

type DynamicEndpointing struct {
	// contains filtered or unexported fields
}

func NewDynamicEndpointing 

func NewDynamicEndpointing(options EndpointingOptions) (*DynamicEndpointing, error)

func (*DynamicEndpointing) BetweenUtteranceDelay 

func (e *DynamicEndpointing) BetweenUtteranceDelay() time.Duration

func (*DynamicEndpointing) MaxDelay 

func (e *DynamicEndpointing) MaxDelay() time.Duration

func (*DynamicEndpointing) MinDelay 

func (e *DynamicEndpointing) MinDelay() time.Duration

func (*DynamicEndpointing) OnEndOfAgentSpeech 

func (e *DynamicEndpointing) OnEndOfAgentSpeech(ended time.Time)

func (*DynamicEndpointing) OnEndOfSpeech 

func (e *DynamicEndpointing) OnEndOfSpeech(ended time.Time, shouldIgnore bool)

func (*DynamicEndpointing) OnStartOfAgentSpeech 

func (e *DynamicEndpointing) OnStartOfAgentSpeech(started time.Time)

func (*DynamicEndpointing) OnStartOfSpeech 

func (e *DynamicEndpointing) OnStartOfSpeech(started time.Time, overlapping bool)

func (*DynamicEndpointing) Overlapping 

func (e *DynamicEndpointing) Overlapping() bool

func (*DynamicEndpointing) Update 

func (e *DynamicEndpointing) Update(update EndpointingUpdate) error

type EOTPredictionEvent 

type EOTPredictionEvent struct {
	EventBase
	Probability       float64       `json:"probability"`
	Threshold         float64       `json:"threshold"`
	InferenceDuration time.Duration `json:"-"`
	Delay             time.Duration `json:"-"`
}

func (EOTPredictionEvent) MarshalJSON 

func (e EOTPredictionEvent) MarshalJSON() ([]byte, error)

type Endpointing 

type Endpointing interface {
	MinDelay() time.Duration
	MaxDelay() time.Duration
	Overlapping() bool
	OnStartOfSpeech(time.Time, bool)
	OnEndOfSpeech(time.Time, bool)
	OnStartOfAgentSpeech(time.Time)
	OnEndOfAgentSpeech(time.Time)
	Update(EndpointingUpdate) error
}

func NewEndpointing 

func NewEndpointing(options EndpointingOptions) (Endpointing, error)

type EndpointingMode 

type EndpointingMode string
const (
	EndpointingFixed   EndpointingMode = "fixed"
	EndpointingDynamic EndpointingMode = "dynamic"
)

type EndpointingOptions 

type EndpointingOptions struct {
	Mode     EndpointingMode
	MinDelay time.Duration
	MaxDelay time.Duration
	Alpha    float64
}

type EndpointingUpdate 

type EndpointingUpdate struct {
	MinDelay *time.Duration
	MaxDelay *time.Duration
	Alpha    *float64
}

type ErrorEvent 

type ErrorEvent struct {
	EventBase
	Err    error `json:"-"`
	Source any   `json:"-"`
}

func NewErrorEvent 

func NewErrorEvent(err error, source any, createdAt time.Time) ErrorEvent

type Event 

type Event interface {
	Type() EventType
	Time() time.Time
}

type EventBase 

type EventBase struct {
	Kind      EventType      `json:"type"`
	CreatedAt EventTimestamp `json:"createdAt"`
}

func (EventBase) Time 

func (e EventBase) Time() time.Time

func (EventBase) Type 

func (e EventBase) Type() EventType

type EventBus 

type EventBus struct {
	// contains filtered or unexported fields
}

EventBus serializes all session events through one bounded dispatcher. It owns a single goroutine regardless of the number of stream subscribers; callback subscriptions add one isolated pump apiece.

func NewEventBus 

func NewEventBus(parent context.Context, options EventBusOptions) *EventBus

func (*EventBus) Close 

func (b *EventBus) Close() error

func (*EventBus) OnEvent 

func (b *EventBus) OnEvent(fn func(Event), options EventSubscriptionOptions) (func(), error)

OnEvent runs fn in registration order for its own subscription, never on a producer or dispatcher goroutine. The returned function is idempotent.

func (*EventBus) Publish 

func (b *EventBus) Publish(ctx context.Context, event Event) error

Publish enqueues an event in global session order and applies bounded backpressure. It never invokes user code on the caller's goroutine.

func (*EventBus) PublishAndWait 

func (b *EventBus) PublishAndWait(ctx context.Context, event Event) error

PublishAndWait applies backpressure until event has been dispatched to every active subscriber queue. It is used for terminal/control events that must be visible before the producer closes the bus; callbacks still run on their isolated subscription goroutines.

func (*EventBus) Subscribe 

func (b *EventBus) Subscribe(options EventSubscriptionOptions) (*EventSubscription, error)

func (*EventBus) TryPublish 

func (b *EventBus) TryPublish(event Event) bool

TryPublish is intended for metrics producers that must not block. It returns false when the global queue is full or the bus is closed.

type EventBusOptions 

type EventBusOptions struct {
	QueueCapacity int
	// OnCallbackError runs on the affected callback's pump goroutine.
	OnCallbackError func(error)
}

type EventCallbackError 

type EventCallbackError struct {
	Panic any
	Stack []byte
}

EventCallbackError reports a recovered callback panic. A user callback can therefore never take down a media or session goroutine.

func (*EventCallbackError) Error 

func (e *EventCallbackError) Error() string

func (*EventCallbackError) Unwrap 

func (e *EventCallbackError) Unwrap() error

type EventSubscription 

type EventSubscription struct {
	// contains filtered or unexported fields
}

EventSubscription is an explicitly closable, bounded event stream.

func (*EventSubscription) Close 

func (s *EventSubscription) Close() error

func (*EventSubscription) Dropped 

func (s *EventSubscription) Dropped() uint64

func (*EventSubscription) Recv 

func (s *EventSubscription) Recv(ctx context.Context) (Event, error)

type EventSubscriptionOptions 

type EventSubscriptionOptions struct {
	Capacity int
	// DropTelemetry permits dropping only coalescible telemetry events when
	// this subscriber is full. Conversation, state, speech, error, and close
	// events always apply backpressure and remain lossless.
	DropTelemetry bool
}

type EventTimestamp 

type EventTimestamp time.Time

EventTimestamp preserves the epoch-millisecond wire contract while exposing a time.Time conversion to Go callers.

func NewEventTimestamp 

func NewEventTimestamp(value time.Time) EventTimestamp

func (EventTimestamp) MarshalJSON 

func (t EventTimestamp) MarshalJSON() ([]byte, error)

func (EventTimestamp) Time 

func (t EventTimestamp) Time() time.Time

func (*EventTimestamp) UnmarshalJSON 

func (t *EventTimestamp) UnmarshalJSON(data []byte) error

type EventType 

type EventType string
const (
	EventUserInputTranscribed     EventType = "user_input_transcribed"
	EventUserTranscriptionTimeout EventType = "user_transcription_timeout"
	EventAgentStateChanged        EventType = "agent_state_changed"
	EventUserStateChanged         EventType = "user_state_changed"
	EventConversationItemAdded    EventType = "conversation_item_added"
	EventFunctionToolsExecuted    EventType = "function_tools_executed"
	EventMetricsCollected         EventType = "metrics_collected"
	EventSessionUsageUpdated      EventType = "session_usage_updated"
	EventDebugMessage             EventType = "debug_message"
	EventSpeechCreated            EventType = "speech_created"
	EventAgentFalseInterruption   EventType = "agent_false_interruption"
	EventOverlappingSpeech        EventType = "overlapping_speech"
	EventEOTPrediction            EventType = "eot_prediction"
	EventError                    EventType = "error"
	EventClose                    EventType = "close"
)
const EventAMDPrediction EventType = "amd_prediction"

type ExpressiveOptions 

type ExpressiveOptions struct {
	SpeechSteering          *tts.SpeechSteeringOptions
	TTSInstructionsTemplate *llm.Instructions
	TTSInstructionsAppend   string
}

type FillerContent 

type FillerContent struct {
	Text   string
	Handle *SpeechHandle
}

FillerContent is one lazily selected filler step. Exactly one of Text or Handle may be set; the zero value intentionally skips the step.

type FillerSource 

type FillerSource func(context.Context, int) (FillerContent, error)

func TextFiller 

func TextFiller(text string) FillerSource

type FinalizeSimulationError 

type FinalizeSimulationError struct {
	Message     string
	UserVerdict *agentpb.SessionResponse_FinalizeSimulationResponse_SimulationVerdict
}

func (*FinalizeSimulationError) Error 

func (e *FinalizeSimulationError) Error() string

type FinalizeSimulationOptions 

type FinalizeSimulationOptions struct {
	ProvisionalSuccess bool
	ProvisionalReason  string
	Timeout            time.Duration
}

type FixedEndpointing 

type FixedEndpointing struct {
	// contains filtered or unexported fields
}

func (*FixedEndpointing) MaxDelay 

func (e *FixedEndpointing) MaxDelay() time.Duration

func (*FixedEndpointing) MinDelay 

func (e *FixedEndpointing) MinDelay() time.Duration

func (*FixedEndpointing) OnEndOfAgentSpeech 

func (*FixedEndpointing) OnEndOfAgentSpeech(time.Time)

func (*FixedEndpointing) OnEndOfSpeech 

func (e *FixedEndpointing) OnEndOfSpeech(_ time.Time, _ bool)

func (*FixedEndpointing) OnStartOfAgentSpeech 

func (*FixedEndpointing) OnStartOfAgentSpeech(time.Time)

func (*FixedEndpointing) OnStartOfSpeech 

func (e *FixedEndpointing) OnStartOfSpeech(_ time.Time, overlapping bool)

func (*FixedEndpointing) Overlapping 

func (e *FixedEndpointing) Overlapping() bool

func (*FixedEndpointing) Update 

func (e *FixedEndpointing) Update(update EndpointingUpdate) error

type FrozenReportEvent 

type FrozenReportEvent struct {
	// contains filtered or unexported fields
}

FrozenReportEvent is an immutable, ownership-safe event snapshot for a SessionReport. It retains only the canonical report wire form, so live model, speech, audio, and tool objects cannot be retained accidentally by a long-running session recorder.

func FreezeReportEvent 

func FreezeReportEvent(event Event) (*FrozenReportEvent, error)

FreezeReportEvent converts an event to the canonical, snake_case report wire contract and severs every reference to its source object graph. Metrics and usage events are valid inputs even though SessionReportToJSON intentionally omits them for cross-SDK parity.

func (*FrozenReportEvent) EncodedSize 

func (e *FrozenReportEvent) EncodedSize() int

EncodedSize is the exact number of retained canonical JSON bytes.

func (*FrozenReportEvent) MarshalJSON 

func (e *FrozenReportEvent) MarshalJSON() ([]byte, error)

func (*FrozenReportEvent) Time 

func (e *FrozenReportEvent) Time() time.Time

func (*FrozenReportEvent) Type 

func (e *FrozenReportEvent) Type() EventType

type FunctionToolsExecutedEvent 

type FunctionToolsExecutedEvent struct {
	EventBase
	FunctionCalls       []*llm.FunctionCall       `json:"functionCalls"`
	FunctionCallOutputs []*llm.FunctionCallOutput `json:"functionCallOutputs"`
}

func (FunctionToolsExecutedEvent) Pairs 

func (e FunctionToolsExecutedEvent) Pairs() [][2]llm.ChatItem

type GenerateReplyOptions 

type GenerateReplyOptions struct {
	UserInput          string
	UserMessage        *llm.ChatMessage
	ChatContext        *llm.ChatContext
	Instructions       *llm.Instructions
	ToolChoice         llm.ToolChoice
	AllowInterruptions *bool
	InputModality      InputModality
}

func (GenerateReplyOptions) Validate 

func (o GenerateReplyOptions) Validate() error

type InputDetails 

type InputDetails struct {
	Modality InputModality
}

type InputModality 

type InputModality string
const (
	InputModalityAudio InputModality = "audio"
	InputModalityText  InputModality = "text"
)

type InterruptionMode 

type InterruptionMode string
const (
	InterruptionAdaptive InterruptionMode = "adaptive"
	InterruptionVAD      InterruptionMode = "vad"
)

type InterruptionOptions 

type InterruptionOptions struct {
	Enabled bool
	Mode    InterruptionMode
	// Detector optionally supplies a caller-owned adaptive detector. When nil,
	// adaptive mode lazily constructs the production inference detector.
	Detector                      *inference.AdaptiveInterruptionDetector
	DiscardAudioIfUninterruptible bool
	MinDuration                   time.Duration
	MinWords                      int
	FalseInterruptionTimeout      *time.Duration
	ResumeFalseInterruption       bool
	BackchannelBoundary           *BackchannelBoundary
}

func DefaultInterruptionOptions 

func DefaultInterruptionOptions() InterruptionOptions

func (InterruptionOptions) Validate 

func (o InterruptionOptions) Validate() error

type KeytermDetectionOptions 

type KeytermDetectionOptions struct {
	Enabled      bool
	LLM          llm.LLM
	LLMModel     string
	TurnInterval int
	MaxKeyterms  *int
	Instructions string
	Timeout      time.Duration
}

KeytermDetectionOptions mirrors the TypeScript/Python keyterm detector while keeping model selection unambiguous in Go. LLM and LLMModel are mutually exclusive. A zero Timeout selects DefaultKeytermDetectionTimeout.

type KeytermDetectionResult 

type KeytermDetectionResult struct {
	Pending []string
	Confirm []string
	Remove  []string
}

KeytermDetectionResult contains changes requested by record_keyterms.

func DetectKeyterms 

func DetectKeyterms(ctx context.Context, model llm.LLM, chat *llm.ChatContext, options DetectKeytermsOptions) (KeytermDetectionResult, error)

DetectKeyterms forces one record_keyterms tool call and parses its changes.

func ParseKeytermToolCalls 

func ParseKeytermToolCalls(calls []*llm.FunctionCall) KeytermDetectionResult

type KeytermDetector 

type KeytermDetector struct {
	// contains filtered or unexported fields
}

KeytermDetector owns keyterm state for a whole session. Start and Pause bind individual agent activities while confirmed state survives handoffs.

func NewKeytermDetector 

func NewKeytermDetector(options KeytermsOptions) (*KeytermDetector, error)

func (*KeytermDetector) Close 

func (d *KeytermDetector) Close(ctx context.Context) error

Close permanently stops detection and closes a lazily-created inference LLM. Caller-provided LLM instances remain caller-owned.

func (*KeytermDetector) DetectedKeyterms 

func (d *KeytermDetector) DetectedKeyterms() []string

func (*KeytermDetector) Keyterms 

func (d *KeytermDetector) Keyterms() []string

func (*KeytermDetector) OnMetrics 

func (d *KeytermDetector) OnMetrics(fn func(metrics.LLM)) func()

func (*KeytermDetector) Pause 

func (d *KeytermDetector) Pause(ctx context.Context) error

Pause detaches the current activity without discarding detected state.

func (*KeytermDetector) PendingKeyterms 

func (d *KeytermDetector) PendingKeyterms() []string

func (*KeytermDetector) RunOnce 

func (d *KeytermDetector) RunOnce(ctx context.Context, chat *llm.ChatContext) error

RunOnce executes one extraction pass and applies confirmed state atomically.

func (*KeytermDetector) SetStaticKeyterms 

func (d *KeytermDetector) SetStaticKeyterms(terms []string) error

func (*KeytermDetector) Start 

func (d *KeytermDetector) Start(parent context.Context, session KeytermDetectorSession, speech stt.STT) error

Start binds the current activity. Only one activity can be active; callers must Pause the previous activity first. Detection is skipped when disabled or when the recognizer cannot consume keyterms.

func (*KeytermDetector) StaticKeyterms 

func (d *KeytermDetector) StaticKeyterms() []string

func (*KeytermDetector) SwapSTT 

func (d *KeytermDetector) SwapSTT(speech stt.STT) error

SwapSTT binds the current effective set to a recognizer. Rebinding the same instance is a no-op; a new keyterm-capable instance receives an empty set too, clearing state left by a prior session.

type KeytermDetectorSession 

type KeytermDetectorSession interface {
	ChatContext() *llm.ChatContext
	OnEvent(func(Event), EventSubscriptionOptions) (func(), error)
}

KeytermDetectorSession is intentionally small so AgentSession and test harnesses can both drive the detector without adapters.

type KeytermState 

type KeytermState struct {
	Term    string
	Applied bool
}

KeytermState is supplied to the extraction prompt. Applied entries bias the recognizer; candidates remain pending until a later pass confirms them.

type KeytermsOptions 

type KeytermsOptions struct {
	Keyterms         []string
	KeytermDetection KeytermDetectionOptions
}

KeytermsOptions configures static STT biasing and optional background extraction. Its zero value leaves both features disabled.

type LLMNodeItem 

type LLMNodeItem struct {
	Chunk *llm.ChatChunk
	Text  string
	Flush bool
}

func LLMChunkItem 

func LLMChunkItem(chunk llm.ChatChunk) LLMNodeItem

func LLMFlushItem 

func LLMFlushItem() LLMNodeItem

func LLMTextItem 

func LLMTextItem(text string) LLMNodeItem

type ManagedAudioOutput 

type ManagedAudioOutput struct {
	// contains filtered or unexported fields
}

ManagedAudioOutput is the production helper for custom sinks. It owns segment accounting and forwards through an optional output chain.

func NewManagedAudioOutput 

func NewManagedAudioOutput(options AudioOutputOptions) (*ManagedAudioOutput, error)

func (*ManagedAudioOutput) CanPause 

func (o *ManagedAudioOutput) CanPause() bool

func (*ManagedAudioOutput) CaptureFrame 

func (o *ManagedAudioOutput) CaptureFrame(ctx context.Context, frame agents.AudioFrame) error

func (*ManagedAudioOutput) CapturedPlayoutSegments 

func (o *ManagedAudioOutput) CapturedPlayoutSegments() uint64

func (*ManagedAudioOutput) ClearBuffer 

func (o *ManagedAudioOutput) ClearBuffer(ctx context.Context) error

func (*ManagedAudioOutput) Close 

func (o *ManagedAudioOutput) Close()

func (*ManagedAudioOutput) Flush 

func (o *ManagedAudioOutput) Flush(ctx context.Context) error

func (*ManagedAudioOutput) NotifyPlaybackFinished 

func (o *ManagedAudioOutput) NotifyPlaybackFinished(event PlaybackFinishedEvent) error

func (*ManagedAudioOutput) NotifyPlaybackStarted 

func (o *ManagedAudioOutput) NotifyPlaybackStarted(createdAt time.Time)

func (*ManagedAudioOutput) OnAttached 

func (o *ManagedAudioOutput) OnAttached()

func (*ManagedAudioOutput) OnDetached 

func (o *ManagedAudioOutput) OnDetached()

func (*ManagedAudioOutput) OnPlaybackFinished 

func (o *ManagedAudioOutput) OnPlaybackFinished(fn func(PlaybackFinishedEvent)) func()

func (*ManagedAudioOutput) OnPlaybackStarted 

func (o *ManagedAudioOutput) OnPlaybackStarted(fn func(PlaybackStartedEvent)) func()

func (*ManagedAudioOutput) Pause 

func (o *ManagedAudioOutput) Pause(ctx context.Context) error

func (*ManagedAudioOutput) PendingPlayoutSegments 

func (o *ManagedAudioOutput) PendingPlayoutSegments() uint64

func (*ManagedAudioOutput) Resume 

func (o *ManagedAudioOutput) Resume(ctx context.Context) error

func (*ManagedAudioOutput) SampleRate 

func (o *ManagedAudioOutput) SampleRate() int

func (*ManagedAudioOutput) SetAttached 

func (o *ManagedAudioOutput) SetAttached(attached bool)

func (*ManagedAudioOutput) WaitForPlayout 

func (o *ManagedAudioOutput) WaitForPlayout(ctx context.Context) (PlaybackFinishedEvent, error)

type ManagedTextOutput 

type ManagedTextOutput struct {
	// contains filtered or unexported fields
}

func NewManagedTextOutput 

func NewManagedTextOutput(options TextOutputOptions) *ManagedTextOutput

func (*ManagedTextOutput) CaptureText 

func (o *ManagedTextOutput) CaptureText(ctx context.Context, text agents.TimedString) error

func (*ManagedTextOutput) Flush 

func (o *ManagedTextOutput) Flush(ctx context.Context) error

func (*ManagedTextOutput) OnAttached 

func (o *ManagedTextOutput) OnAttached()

func (*ManagedTextOutput) OnDetached 

func (o *ManagedTextOutput) OnDetached()

func (*ManagedTextOutput) SetAttached 

func (o *ManagedTextOutput) SetAttached(attached bool)

type MetricsCollectedEvent 

type MetricsCollectedEvent struct {
	EventBase
	Metrics metrics.Metric `json:"metrics"`
}

type ModelSettings 

type ModelSettings struct {
	ToolChoice llm.ToolChoice
}

type OverlappingSpeechEvent 

type OverlappingSpeechEvent struct {
	EventBase
	DetectedAt         time.Time     `json:"-"`
	Interruption       bool          `json:"isInterruption"`
	AgentEnded         *bool         `json:"agentEnded,omitempty"`
	TotalDuration      time.Duration `json:"-"`
	PredictionDuration time.Duration `json:"-"`
	DetectionDelay     time.Duration `json:"-"`
	OverlapStartedAt   *time.Time    `json:"-"`
	SpeechInput        []int16       `json:"-"`
	Probabilities      []float64     `json:"probabilities,omitempty"`
	Probability        float64       `json:"probability"`
	NumRequests        int           `json:"numRequests"`
}

type PlaybackFinishedEvent 

type PlaybackFinishedEvent struct {
	PlaybackPosition       time.Duration `json:"playback_position"`
	Interrupted            bool          `json:"interrupted"`
	SynchronizedTranscript *string       `json:"synchronized_transcript,omitempty"`
}

type PlaybackStartedEvent 

type PlaybackStartedEvent struct {
	CreatedAt time.Time `json:"created_at"`
}

type PreemptiveGenerationOptions 

type PreemptiveGenerationOptions struct {
	Enabled           bool
	PreemptiveTTS     bool
	MaxSpeechDuration time.Duration
	MaxRetries        int
}

func (PreemptiveGenerationOptions) Validate 

func (o PreemptiveGenerationOptions) Validate() error

type RecognizedTurn 

type RecognizedTurn struct {
	Transcript     string
	Language       agents.LanguageCode
	SpeakerID      string
	Confidence     float64
	SpeechStarted  time.Time
	SpeechEnded    time.Time
	SpeechDuration time.Duration
}

type RecordingOptions 

type RecordingOptions struct {
	Audio      bool `json:"audio"`
	Traces     bool `json:"traces"`
	Logs       bool `json:"logs"`
	Transcript bool `json:"transcript"`
	Redaction  bool `json:"redaction"`
}

RecordingOptions is the fully resolved, granular recording policy shared by reports and telemetry. Use DefaultRecordingOptions or DisabledRecordingOptions rather than relying on the zero value when constructing a policy directly.

func DefaultRecordingOptions 

func DefaultRecordingOptions() RecordingOptions

func DisabledRecordingOptions 

func DisabledRecordingOptions() RecordingOptions

func ResolveRecordingOptions 

func ResolveRecordingOptions(update RecordingOptionsUpdate) RecordingOptions

func (RecordingOptions) Enabled 

func (o RecordingOptions) Enabled() bool

type RecordingOptionsUpdate 

type RecordingOptionsUpdate struct {
	Audio      *bool
	Traces     *bool
	Logs       *bool
	Transcript *bool
	Redaction  *bool
}

RecordingOptionsUpdate mirrors the sparse TypeScript/Python recording object. Omitted fields inherit the all-on policy.

type RemoteEventSubscription 

type RemoteEventSubscription struct {
	// contains filtered or unexported fields
}

func (*RemoteEventSubscription) Close 

func (s *RemoteEventSubscription) Close() error

func (*RemoteEventSubscription) Recv 

func (s *RemoteEventSubscription) Recv(ctx context.Context) (RemoteSessionEvent, error)

type RemoteSession 

type RemoteSession struct {
	// contains filtered or unexported fields
}

RemoteSession is the context-first Go client for the LiveKit AgentSession protobuf. Pending RPCs and event subscribers are explicitly bounded.

func NewRemoteSession 

func NewRemoteSession(transport SessionTransport, options ...RemoteSessionOptions) (*RemoteSession, error)

func NewRemoteSessionFromRoom 

func NewRemoteSessionFromRoom(room *lksdk.Room, remoteIdentity string, options ...RemoteSessionOptions) (*RemoteSession, error)

NewRemoteSessionFromRoom is the Go migration equivalent of Python's RemoteSession.from_room. For dynamic participant linking, construct a RoomSessionTransport with RemoteIdentity and pass it to NewRemoteSession.

func (*RemoteSession) AClose 

func (s *RemoteSession) AClose(ctx context.Context) error

AClose is the migration alias for Python/agents-js aclose().

func (*RemoteSession) Close 

func (s *RemoteSession) Close(ctx context.Context) error

func (*RemoteSession) FetchAgentInfo 

func (s *RemoteSession) FetchAgentInfo(ctx context.Context) (*agentpb.SessionResponse_GetAgentInfoResponse, error)

func (*RemoteSession) FetchChatHistory 

func (s *RemoteSession) FetchChatHistory(ctx context.Context) (*agentpb.SessionResponse_GetChatHistoryResponse, error)

func (*RemoteSession) FetchFrameworkInfo 

func (s *RemoteSession) FetchFrameworkInfo(ctx context.Context) (*agentpb.SessionResponse_GetFrameworkInfoResponse, error)

func (*RemoteSession) FetchRTCStats 

func (s *RemoteSession) FetchRTCStats(ctx context.Context) (*agentpb.SessionResponse_GetRTCStatsResponse, error)

func (*RemoteSession) FetchSessionState 

func (s *RemoteSession) FetchSessionState(ctx context.Context) (*agentpb.SessionResponse_GetSessionStateResponse, error)

func (*RemoteSession) FetchSessionUsage 

func (s *RemoteSession) FetchSessionUsage(ctx context.Context) (*agentpb.SessionResponse_GetSessionUsageResponse, error)

func (*RemoteSession) FinalizeSimulation 

func (s *RemoteSession) FinalizeSimulation(ctx context.Context, options FinalizeSimulationOptions) (*agentpb.SessionResponse_FinalizeSimulationResponse, error)

func (*RemoteSession) GetAgentInfo 

func (s *RemoteSession) GetAgentInfo(ctx context.Context) (*agentpb.SessionResponse_GetAgentInfoResponse, error)

func (*RemoteSession) GetChatHistory 

func (s *RemoteSession) GetChatHistory(ctx context.Context) (*agentpb.SessionResponse_GetChatHistoryResponse, error)

func (*RemoteSession) GetFrameworkInfo 

func (s *RemoteSession) GetFrameworkInfo(ctx context.Context) (*agentpb.SessionResponse_GetFrameworkInfoResponse, error)

func (*RemoteSession) GetRTCStats 

func (s *RemoteSession) GetRTCStats(ctx context.Context) (*agentpb.SessionResponse_GetRTCStatsResponse, error)

func (*RemoteSession) GetSessionState 

func (s *RemoteSession) GetSessionState(ctx context.Context) (*agentpb.SessionResponse_GetSessionStateResponse, error)

func (*RemoteSession) GetSessionUsage 

func (s *RemoteSession) GetSessionUsage(ctx context.Context) (*agentpb.SessionResponse_GetSessionUsageResponse, error)

func (*RemoteSession) OnEvent 

func (s *RemoteSession) OnEvent(callback func(RemoteSessionEvent), capacity ...int) (func(), error)

func (*RemoteSession) Ping 

func (s *RemoteSession) Ping(ctx context.Context) error

func (*RemoteSession) Run 

func (s *RemoteSession) Run(ctx context.Context, text string, timeout ...time.Duration) (*agentpb.SessionResponse_RunInputResponse, error)

func (*RemoteSession) SendMessage 

func (s *RemoteSession) SendMessage(ctx context.Context, text string, timeout ...time.Duration) (*agentpb.SessionResponse_RunInputResponse, error)

func (*RemoteSession) Start 

func (s *RemoteSession) Start(ctx context.Context) error

func (*RemoteSession) Started 

func (s *RemoteSession) Started() bool

func (*RemoteSession) SubscribeEvents 

func (s *RemoteSession) SubscribeEvents(capacity ...int) (*RemoteEventSubscription, error)

func (*RemoteSession) UpdateIO 

func (s *RemoteSession) UpdateIO(ctx context.Context, options RemoteUpdateIOOptions) (*agentpb.SessionResponse_UpdateIOResponse, error)

func (*RemoteSession) WaitForReady 

func (s *RemoteSession) WaitForReady(ctx context.Context, retryInterval time.Duration) error

type RemoteSessionEvent 

type RemoteSessionEvent struct {
	Type      RemoteSessionEventType
	CreatedAt time.Time
	Event     *agentpb.AgentSessionEvent
	Value     proto.Message
}

type RemoteSessionEventType 

type RemoteSessionEventType string
const (
	RemoteEventAgentFalseInterruption RemoteSessionEventType = "agent_false_interruption"
	RemoteEventAgentStateChanged      RemoteSessionEventType = "agent_state_changed"
	RemoteEventUserStateChanged       RemoteSessionEventType = "user_state_changed"
	RemoteEventConversationItemAdded  RemoteSessionEventType = "conversation_item_added"
	RemoteEventUserInputTranscribed   RemoteSessionEventType = "user_input_transcribed"
	RemoteEventFunctionToolsStarted   RemoteSessionEventType = "function_tools_started"
	RemoteEventFunctionToolsExecuted  RemoteSessionEventType = "function_tools_executed"
	RemoteEventToolExecutionUpdated   RemoteSessionEventType = "tool_execution_updated"
	RemoteEventOverlappingSpeech      RemoteSessionEventType = "overlapping_speech"
	RemoteEventAMDPrediction          RemoteSessionEventType = "amd_prediction"
	RemoteEventEOTPrediction          RemoteSessionEventType = "eot_prediction"
	RemoteEventSessionUsage           RemoteSessionEventType = "session_usage"
	RemoteEventDebugMessage           RemoteSessionEventType = "debug_message"
	RemoteEventError                  RemoteSessionEventType = "error"
)

type RemoteSessionOptions 

type RemoteSessionOptions struct {
	ParentContext      context.Context
	RequestTimeout     time.Duration
	MaxPendingRequests int
	EventCapacity      int
}

type RemoteSessionRequestError 

type RemoteSessionRequestError struct {
	RequestID string
	Err       error
}

func (*RemoteSessionRequestError) Error 

func (e *RemoteSessionRequestError) Error() string

func (*RemoteSessionRequestError) Unwrap 

func (e *RemoteSessionRequestError) Unwrap() error

type RemoteUpdateIOOptions 

type RemoteUpdateIOOptions struct {
	InputAudioEnabled          *bool
	InputVideoEnabled          *bool
	OutputAudioEnabled         *bool
	OutputVideoEnabled         *bool
	OutputTranscriptionEnabled *bool
	Timeout                    time.Duration
}

type ReportSessionOptions 

type ReportSessionOptions struct {
	Interruption         InterruptionOptions
	Endpointing          EndpointingOptions
	MaxToolSteps         int
	UserAwayTimeout      *time.Duration
	PreemptiveGeneration PreemptiveGenerationOptions
	Recording            RecordingOptions
}

ReportSessionOptions is the subset of AgentSession options carried in the cross-SDK session report wire contract.

func ReportSessionOptionsFromAgent 

func ReportSessionOptionsFromAgent[UserData any](options AgentSessionOptions[UserData], recording RecordingOptions) ReportSessionOptions

ReportSessionOptionsFromAgent converts public session options without starting models, allocating RTC resources, or changing ownership.

type ResolvedKeytermDetectionOptions 

type ResolvedKeytermDetectionOptions struct {
	Enabled      bool
	LLM          llm.LLM
	LLMModel     string
	TurnInterval int
	MaxKeyterms  *int
	Instructions string
	Timeout      time.Duration
}

func ResolveKeytermDetectionOptions 

func ResolveKeytermDetectionOptions(options KeytermDetectionOptions) (ResolvedKeytermDetectionOptions, error)

ResolveKeytermDetectionOptions validates and defaults detection options.

type ResolvedKeytermsOptions 

type ResolvedKeytermsOptions struct {
	Keyterms         []string
	KeytermDetection ResolvedKeytermDetectionOptions
}

func ResolveKeytermsOptions 

func ResolveKeytermsOptions(options KeytermsOptions) (ResolvedKeytermsOptions, error)

type RoomSessionTransport 

type RoomSessionTransport struct {
	// contains filtered or unexported fields
}

RoomSessionTransport uses LiveKit byte streams. The server SDK's reader and writer are not context-aware and buffer a stream internally; declared stream sizes and this transport's bounded reader queue provide the limits available with server-sdk-go v2.18.1.

func NewRoomSessionTransport 

func NewRoomSessionTransport(options RoomSessionTransportOptions) (*RoomSessionTransport, error)

func (*RoomSessionTransport) Close 

func (t *RoomSessionTransport) Close(context.Context) error

func (*RoomSessionTransport) Recv 

func (t *RoomSessionTransport) Recv(ctx context.Context) (*agentpb.AgentSessionMessage, error)

func (*RoomSessionTransport) SendMessage 

func (t *RoomSessionTransport) SendMessage(ctx context.Context, message *agentpb.AgentSessionMessage) error

func (*RoomSessionTransport) Start 

func (t *RoomSessionTransport) Start(ctx context.Context) error

type RoomSessionTransportOptions 

type RoomSessionTransportOptions struct {
	Room              *lksdk.Room
	RemoteIdentity    func() string
	QueueCapacity     int
	MaxMessageSize    uint32
	Topic             string
	Destination       func() []string
	SuppressSizeCheck bool
}

type RunContext 

type RunContext[UserData any] struct {
	// contains filtered or unexported fields
}

RunContext is the typed voice facade behind llm.ToolOptions.Context. Its executor attachment is intentionally replace-proof and is detached when the underlying task ends or is cancelled.

func AsRunContext 

func AsRunContext[UserData any](context *llm.RunContext) (*RunContext[UserData], bool)

AsRunContext recovers the typed voice facade supplied to a function tool. It avoids reflection and makes user-data access type-safe at the tool boundary.

func NewRunContext 

func NewRunContext[UserData any](session *AgentSession[UserData], handle *SpeechHandle, call *llm.FunctionCall) (*RunContext[UserData], error)

func (*RunContext[UserData]) DisallowInterruptions 

func (r *RunContext[UserData]) DisallowInterruptions() error

func (*RunContext[UserData]) Filler 

func (r *RunContext[UserData]) Filler(ctx context.Context, source FillerSource, options RunContextFillerOptions, fn func(context.Context) error) error

func (*RunContext[UserData]) Foreground 

func (r *RunContext[UserData]) Foreground(ctx context.Context, fn func(context.Context, *Agent[UserData]) error) error

func (*RunContext[UserData]) FunctionCall 

func (r *RunContext[UserData]) FunctionCall() *llm.FunctionCall

func (*RunContext[UserData]) LLMContext 

func (r *RunContext[UserData]) LLMContext() *llm.RunContext

func (*RunContext[UserData]) Session 

func (r *RunContext[UserData]) Session() *AgentSession[UserData]

func (*RunContext[UserData]) SpeechHandle 

func (r *RunContext[UserData]) SpeechHandle() *SpeechHandle

func (*RunContext[UserData]) ToolCurrentSpeechHandle 

func (r *RunContext[UserData]) ToolCurrentSpeechHandle() any

func (*RunContext[UserData]) ToolDisallowInterruptions 

func (r *RunContext[UserData]) ToolDisallowInterruptions() error

func (*RunContext[UserData]) ToolFiller 

func (r *RunContext[UserData]) ToolFiller(ctx context.Context, source any, options llm.RunContextFillerOptions, fn func(context.Context) error) error

func (*RunContext[UserData]) ToolForeground 

func (r *RunContext[UserData]) ToolForeground(ctx context.Context, fn func(context.Context, any) error) error

func (*RunContext[UserData]) ToolUpdate 

func (r *RunContext[UserData]) ToolUpdate(ctx context.Context, message any, options llm.RunContextUpdateOptions) error

func (*RunContext[UserData]) ToolWaitForPlayout 

func (r *RunContext[UserData]) ToolWaitForPlayout(ctx context.Context) error

func (*RunContext[UserData]) Update 

func (r *RunContext[UserData]) Update(ctx context.Context, message any, options ...RunContextUpdateOptions) error

func (*RunContext[UserData]) Updates 

func (r *RunContext[UserData]) Updates() []ToolUpdate

func (*RunContext[UserData]) UserData 

func (r *RunContext[UserData]) UserData() *UserData

func (*RunContext[UserData]) WaitForPlayout 

func (r *RunContext[UserData]) WaitForPlayout(context.Context) error

type RunContextFillerOptions 

type RunContextFillerOptions = llm.RunContextFillerOptions

type RunContextUpdateOptions 

type RunContextUpdateOptions = llm.RunContextUpdateOptions

type RunOptions 

type RunOptions struct {
	UserInput     string
	InputModality InputModality
	Output        *RunOutputOptions
	EventCapacity int
	SettleDelay   time.Duration
}

type RunOutputOptions 

type RunOutputOptions struct {
	// MaxRetriesSet distinguishes an intentional zero from the default of two.
	MaxRetriesSet     bool
	MaxRetries        int
	RetryInstructions string
}

type RunningTool 

type RunningTool struct {
	CallID      string    `json:"call_id"`
	Name        string    `json:"name"`
	Arguments   string    `json:"arguments"`
	StartedAt   time.Time `json:"started_at"`
	Cancellable bool      `json:"cancellable"`
	NonBlocking bool      `json:"non_blocking"`
}

type STTNodeItem 

type STTNodeItem struct {
	Event *stt.SpeechEvent
	Text  string
}

func STTEventItem 

func STTEventItem(event stt.SpeechEvent) STTNodeItem

func STTTextItem 

func STTTextItem(text string) STTNodeItem

type SayOptions 

type SayOptions struct {
	Audio              stream.Reader[agents.AudioFrame]
	AllowInterruptions *bool
	AddToChatContext   *bool
}

type SessionHost 

type SessionHost[UserData any] struct {
	// contains filtered or unexported fields
}

SessionHost exposes an AgentSession over the LiveKit AgentSession protobuf. It uses one ordered bounded writer and a fixed request semaphore, so event bursts and remote callers cannot create an unbounded number of goroutines.

func NewSessionHost 

func NewSessionHost[UserData any](transport SessionTransport, options ...SessionHostOptions[UserData]) (*SessionHost[UserData], error)

func (*SessionHost[UserData]) AClose 

func (h *SessionHost[UserData]) AClose(ctx context.Context) error

func (*SessionHost[UserData]) Close 

func (h *SessionHost[UserData]) Close(ctx context.Context) error

func (*SessionHost[UserData]) RegisterSession 

func (h *SessionHost[UserData]) RegisterSession(session *AgentSession[UserData]) error

RegisterSession binds the host exactly once. Registering the same session is idempotent; replacing a bound session is rejected to preserve event order.

func (*SessionHost[UserData]) Start 

func (h *SessionHost[UserData]) Start(ctx context.Context) error

func (*SessionHost[UserData]) Started 

func (h *SessionHost[UserData]) Started() bool

type SessionHostOptions 

type SessionHostOptions[UserData any] struct {
	ParentContext         context.Context
	AudioInput            *TCPAudioInput
	AudioOutput           *TCPAudioOutput
	JobContext            *agents.JobContext[UserData]
	OnSimulationEnd       agents.SimulationEndFunc[UserData]
	QueueCapacity         int
	MaxConcurrentRequests int
	RequestTimeout        time.Duration
	ShutdownDrainTimeout  time.Duration
	OnError               func(error)
	OnTransportClosed     func(error)
	// ExternalTransport leaves final transport shutdown to the caller. Console
	// mode uses this so a failed AgentSession.Start can retry one connection.
	ExternalTransport bool
}

type SessionReport 

type SessionReport struct {
	JobID                   string
	RoomID                  string
	Room                    string
	Options                 ReportSessionOptions
	Events                  []Event
	ChatHistory             *llm.ChatContext
	EnableRecording         bool
	StartedAt               time.Time
	Timestamp               time.Time
	AudioRecordingPath      string
	AudioRecordingStartedAt *time.Time
	Duration                time.Duration
	ModelUsage              []metrics.ModelUsage
}

func CreateSessionReport 

func CreateSessionReport(options SessionReportOptions) *SessionReport

func (*SessionReport) MarshalJSON 

func (r *SessionReport) MarshalJSON() ([]byte, error)

type SessionReportOptions 

type SessionReportOptions struct {
	JobID                   string
	RoomID                  string
	Room                    string
	Options                 ReportSessionOptions
	Events                  []Event
	ChatHistory             *llm.ChatContext
	EnableRecording         bool
	StartedAt               time.Time
	Timestamp               time.Time
	AudioRecordingPath      string
	AudioRecordingStartedAt *time.Time
	ModelUsage              []metrics.ModelUsage
}

type SessionTransport 

type SessionTransport interface {
	Start(context.Context) error
	SendMessage(context.Context, *agentpb.AgentSessionMessage) error
	Recv(context.Context) (*agentpb.AgentSessionMessage, error)
	Close(context.Context) error
}

SessionTransport carries the current LiveKit AgentSession protobuf. Recv has exactly one consumer; SendMessage is safe for concurrent callers and retains complete protobuf-frame ordering.

type SessionUsageUpdatedEvent 

type SessionUsageUpdatedEvent struct {
	EventBase
	Usage AgentSessionUsage `json:"usage"`
}

type SpeechCreatedEvent 

type SpeechCreatedEvent struct {
	EventBase
	UserInitiated bool          `json:"userInitiated"`
	Source        SpeechSource  `json:"source"`
	SpeechHandle  *SpeechHandle `json:"-"`
}

func NewSpeechCreatedEvent 

func NewSpeechCreatedEvent(handle *SpeechHandle, source SpeechSource, userInitiated bool, createdAt time.Time) SpeechCreatedEvent

type SpeechHandle 

type SpeechHandle struct {
	// contains filtered or unexported fields
}

func NewSpeechHandle 

func NewSpeechHandle(options SpeechHandleOptions) *SpeechHandle

func (*SpeechHandle) AddChatItems 

func (h *SpeechHandle) AddChatItems(items ...llm.ChatItem)

func (*SpeechHandle) AddDoneCallback 

func (h *SpeechHandle) AddDoneCallback(callback func(*SpeechHandle)) func()

func (*SpeechHandle) AddItemCallback 

func (h *SpeechHandle) AddItemCallback(callback func(llm.ChatItem)) func()

func (*SpeechHandle) AllowInterruptions 

func (h *SpeechHandle) AllowInterruptions() bool

func (*SpeechHandle) AuthorizeGeneration 

func (h *SpeechHandle) AuthorizeGeneration() int

func (*SpeechHandle) ChatItems 

func (h *SpeechHandle) ChatItems() []llm.ChatItem

func (*SpeechHandle) ClearAuthorization 

func (h *SpeechHandle) ClearAuthorization()

func (*SpeechHandle) Done 

func (h *SpeechHandle) Done() bool

func (*SpeechHandle) Error 

func (h *SpeechHandle) Error() error

func (*SpeechHandle) HoldInterruptions 

func (h *SpeechHandle) HoldInterruptions() func()

HoldInterruptions temporarily protects this handle. The returned release function is idempotent and supports nested holds.

func (*SpeechHandle) ID 

func (h *SpeechHandle) ID() string

func (*SpeechHandle) IncrementSteps 

func (h *SpeechHandle) IncrementSteps() int

func (*SpeechHandle) InputDetails 

func (h *SpeechHandle) InputDetails() InputDetails

func (*SpeechHandle) Interrupt 

func (h *SpeechHandle) Interrupt(force bool) error

func (*SpeechHandle) InterruptSignal 

func (h *SpeechHandle) InterruptSignal() <-chan struct{}

func (*SpeechHandle) Interrupted 

func (h *SpeechHandle) Interrupted() bool

func (*SpeechHandle) MarkDone 

func (h *SpeechHandle) MarkDone(err error)

func (*SpeechHandle) MarkGenerationDone 

func (h *SpeechHandle) MarkGenerationDone() error

func (*SpeechHandle) MarkScheduled 

func (h *SpeechHandle) MarkScheduled()

func (*SpeechHandle) NumSteps 

func (h *SpeechHandle) NumSteps() int

func (*SpeechHandle) OwnContext 

func (h *SpeechHandle) OwnContext(parent context.Context) (context.Context, func())

OwnContext registers a child operation which the interruption watchdog can force-cancel. The unregister function should be deferred by its owner.

func (*SpeechHandle) Parent 

func (h *SpeechHandle) Parent() *SpeechHandle

func (*SpeechHandle) Scheduled 

func (h *SpeechHandle) Scheduled() bool

func (*SpeechHandle) SetAllowInterruptions 

func (h *SpeechHandle) SetAllowInterruptions(allow bool) error

func (*SpeechHandle) StepIndex 

func (h *SpeechHandle) StepIndex() int

func (*SpeechHandle) Wait 

func (h *SpeechHandle) Wait(ctx context.Context) error

func (*SpeechHandle) WaitForAuthorization 

func (h *SpeechHandle) WaitForAuthorization(ctx context.Context) error

func (*SpeechHandle) WaitForGeneration 

func (h *SpeechHandle) WaitForGeneration(ctx context.Context, index int) error

func (*SpeechHandle) WaitForPlayout 

func (h *SpeechHandle) WaitForPlayout(ctx context.Context) error

func (*SpeechHandle) WaitForScheduled 

func (h *SpeechHandle) WaitForScheduled(ctx context.Context) error

type SpeechHandleCircularWaitError 

type SpeechHandleCircularWaitError struct {
	FunctionName string
}

func (*SpeechHandleCircularWaitError) Error 

func (e *SpeechHandleCircularWaitError) Error() string

type SpeechHandleOptions 

type SpeechHandleOptions struct {
	AllowInterruptions bool
	// AllowInterruptionsSet distinguishes an explicit false from the default true.
	AllowInterruptionsSet bool
	StepIndex             int
	InputDetails          InputDetails
	Parent                *SpeechHandle
	// InterruptTimeout exists for deterministic tests and specialized runtimes.
	// Zero uses the cross-SDK five-second watchdog.
	InterruptTimeout time.Duration
}

type SpeechQueue 

type SpeechQueue struct {
	// contains filtered or unexported fields
}

SpeechQueue is a stable, bounded max-priority queue. It exposes no channel, so callers cannot bypass queue ordering or close ownership.

func NewSpeechQueue 

func NewSpeechQueue(capacity int) *SpeechQueue

func (*SpeechQueue) Close 

func (q *SpeechQueue) Close()

func (*SpeechQueue) Len 

func (q *SpeechQueue) Len() int

func (*SpeechQueue) Ordered 

func (q *SpeechQueue) Ordered() []*SpeechHandle

Ordered returns a playout-order snapshot. Heap-array order is intentionally never exposed because it is not a valid interruption traversal order.

func (*SpeechQueue) Pop 

func (q *SpeechQueue) Pop(ctx context.Context) (*SpeechHandle, error)

func (*SpeechQueue) Push 

func (q *SpeechQueue) Push(ctx context.Context, handle *SpeechHandle, priority int) error

type SpeechSource 

type SpeechSource string
const (
	SpeechSourceSay           SpeechSource = "say"
	SpeechSourceGenerateReply SpeechSource = "generate_reply"
	SpeechSourceToolResponse  SpeechSource = "tool_response"
)

type StopResponse 

type StopResponse struct{}

func (StopResponse) Error 

func (StopResponse) Error() string

type StructuredRunOptions 

type StructuredRunOptions[Output any] struct {
	RunOptions
	// Validate may coerce a task result. Nil performs a strict Go type check.
	Validate func(any) (Output, error)
}

type TCPAudioInput 

type TCPAudioInput struct {
	// contains filtered or unexported fields
}

TCPAudioInput is a bounded 48 kHz broker-to-24 kHz agent audio bridge.

func NewTCPAudioInput 

func NewTCPAudioInput(capacity ...int) (*TCPAudioInput, error)

func NewTcpAudioInput 

func NewTcpAudioInput(capacity ...int) (*TCPAudioInput, error)

NewTcpAudioInput preserves the agents-js spelling.

func (*TCPAudioInput) Close 

func (i *TCPAudioInput) Close() error

func (*TCPAudioInput) OnAttached 

func (i *TCPAudioInput) OnAttached()

func (*TCPAudioInput) OnDetached 

func (i *TCPAudioInput) OnDetached()

func (*TCPAudioInput) PushFrame 

func (i *TCPAudioInput) PushFrame(ctx context.Context, value *agentpb.AgentSessionMessage_ConsoleIO_AudioFrame) error

func (*TCPAudioInput) Recv 

func (i *TCPAudioInput) Recv(ctx context.Context) (agents.AudioFrame, error)

func (*TCPAudioInput) SetAttached 

func (i *TCPAudioInput) SetAttached(value bool)

func (*TCPAudioInput) TryPushFrame 

func (i *TCPAudioInput) TryPushFrame(value *agentpb.AgentSessionMessage_ConsoleIO_AudioFrame) error

type TCPAudioOutput 

type TCPAudioOutput struct {
	// contains filtered or unexported fields
}

TCPAudioOutput is a 24 kHz agent-to-48 kHz broker bridge with one bounded playout handshake in flight. A new segment cannot overtake the previous flush, and ClearBuffer deterministically releases every waiter.

func NewTCPAudioOutput 

func NewTCPAudioOutput(transport SessionTransport) (*TCPAudioOutput, error)

func NewTcpAudioOutput 

func NewTcpAudioOutput(transport SessionTransport) (*TCPAudioOutput, error)

func (*TCPAudioOutput) CanPause 

func (o *TCPAudioOutput) CanPause() bool

func (*TCPAudioOutput) CaptureFrame 

func (o *TCPAudioOutput) CaptureFrame(ctx context.Context, frame agents.AudioFrame) error

func (*TCPAudioOutput) CapturedPlayoutSegments 

func (o *TCPAudioOutput) CapturedPlayoutSegments() uint64

func (*TCPAudioOutput) ClearBuffer 

func (o *TCPAudioOutput) ClearBuffer(ctx context.Context) error

func (*TCPAudioOutput) Close 

func (o *TCPAudioOutput) Close(ctx context.Context) error

func (*TCPAudioOutput) Flush 

func (o *TCPAudioOutput) Flush(ctx context.Context) error

func (*TCPAudioOutput) NotifyPlayoutFinished 

func (o *TCPAudioOutput) NotifyPlayoutFinished() error

func (*TCPAudioOutput) OnAttached 

func (o *TCPAudioOutput) OnAttached()

func (*TCPAudioOutput) OnDetached 

func (o *TCPAudioOutput) OnDetached()

func (*TCPAudioOutput) OnPlaybackFinished 

func (o *TCPAudioOutput) OnPlaybackFinished(fn func(PlaybackFinishedEvent)) func()

func (*TCPAudioOutput) OnPlaybackStarted 

func (o *TCPAudioOutput) OnPlaybackStarted(fn func(PlaybackStartedEvent)) func()

func (*TCPAudioOutput) Pause 

func (o *TCPAudioOutput) Pause(ctx context.Context) error

func (*TCPAudioOutput) PendingPlayoutSegments 

func (o *TCPAudioOutput) PendingPlayoutSegments() uint64

func (*TCPAudioOutput) Resume 

func (o *TCPAudioOutput) Resume(ctx context.Context) error

func (*TCPAudioOutput) SampleRate 

func (o *TCPAudioOutput) SampleRate() int

func (*TCPAudioOutput) SetAttached 

func (o *TCPAudioOutput) SetAttached(value bool)

func (*TCPAudioOutput) WaitForPlayout 

func (o *TCPAudioOutput) WaitForPlayout(ctx context.Context) (PlaybackFinishedEvent, error)

type TCPSessionTransport 

type TCPSessionTransport struct {
	// contains filtered or unexported fields
}

TCPSessionTransport uses the broker-compatible four-byte, big-endian length prefix. The wire has no authentication or TLS handshake; callers should bind it to loopback or place it behind an authenticated tunnel.

func NewTCPSessionTransport 

func NewTCPSessionTransport(host string, port int) (*TCPSessionTransport, error)

func NewTCPSessionTransportWithOptions 

func NewTCPSessionTransportWithOptions(options TCPSessionTransportOptions) (*TCPSessionTransport, error)

func NewTcpSessionTransport 

func NewTcpSessionTransport(host string, port int) (*TCPSessionTransport, error)

NewTcpSessionTransport preserves the spelling used by agents-js.

func (*TCPSessionTransport) Close 

func (t *TCPSessionTransport) Close(context.Context) error

func (*TCPSessionTransport) Closed 

func (t *TCPSessionTransport) Closed() bool

func (*TCPSessionTransport) Recv 

func (t *TCPSessionTransport) Recv(ctx context.Context) (*agentpb.AgentSessionMessage, error)

func (*TCPSessionTransport) SendMessage 

func (t *TCPSessionTransport) SendMessage(ctx context.Context, message *agentpb.AgentSessionMessage) error

func (*TCPSessionTransport) Start 

func (t *TCPSessionTransport) Start(ctx context.Context) error

type TCPSessionTransportOptions 

type TCPSessionTransportOptions struct {
	Host           string
	Port           int
	DialTimeout    time.Duration
	MaxMessageSize uint32
	Dialer         *net.Dialer
}

type TcpAudioInput 

type TcpAudioInput = TCPAudioInput

TcpAudioInput is the mechanical-migration spelling used by agents-js and Python. New Go code should use TCPAudioInput.

type TcpAudioOutput 

type TcpAudioOutput = TCPAudioOutput

TcpAudioOutput is the mechanical-migration spelling used by agents-js and Python. New Go code should use TCPAudioOutput.

type TcpSessionTransport 

type TcpSessionTransport = TCPSessionTransport

TcpSessionTransport is the mechanical-migration spelling used by agents-js and Python. New Go code should use TCPSessionTransport.

type TcpSessionTransportOptions 

type TcpSessionTransportOptions = TCPSessionTransportOptions

TcpSessionTransportOptions is the mechanical-migration spelling used by agents-js and Python. New Go code should use TCPSessionTransportOptions.

type TextOutput 

type TextOutput interface {
	CaptureText(context.Context, agents.TimedString) error
	Flush(context.Context) error
	Attachable
}

type TextOutputOptions 

type TextOutputOptions struct {
	Next     TextOutput
	Capture  func(context.Context, agents.TimedString) error
	Flush    func(context.Context) error
	Attached func()
	Detached func()
}

type ToolExecutionOptions 

type ToolExecutionOptions struct{ SpeechHandle *SpeechHandle }

type ToolExecutionResult 

type ToolExecutionResult struct {
	Call        *llm.FunctionCall
	Output      *llm.FunctionCallOutput
	Value       any
	Err         error
	NonBlocking bool
}

type ToolExecutor 

type ToolExecutor struct {
	// contains filtered or unexported fields
}

ToolExecutor owns one duplicate/concurrency scope. ParentContext determines whether detached tasks survive a handoff (session AsyncToolset) or end with an activity (ordinary and agent-scoped executors).

func NewToolExecutor 

func NewToolExecutor(options ToolExecutorOptions) (*ToolExecutor, error)

func (*ToolExecutor) Cancel 

func (e *ToolExecutor) Cancel(callID string) error

func (*ToolExecutor) Close 

func (e *ToolExecutor) Close(ctx context.Context) error

func (*ToolExecutor) Drain 

func (e *ToolExecutor) Drain(ctx context.Context) error

func (*ToolExecutor) Execute 

func (e *ToolExecutor) Execute(ctx context.Context, calls []*llm.FunctionCall, tools *llm.Context, options ...ToolExecutionOptions) ([]ToolExecutionResult, error)

func (*ToolExecutor) Running 

func (e *ToolExecutor) Running() []RunningTool

func (*ToolExecutor) SetToolOptions 

func (e *ToolExecutor) SetToolOptions(options *AsyncToolOptions)

func (*ToolExecutor) WaitForReplies 

func (e *ToolExecutor) WaitForReplies(ctx context.Context) error

type ToolExecutorOptions 

type ToolExecutorOptions struct {
	MaxConcurrency        int
	MaxCallsPerBatch      int
	DrainTimeout          time.Duration
	PendingUpdateCapacity int
	ParentContext         context.Context
	Session               any
	UserData              any
	ToolHandling          *AsyncToolOptions
	Runtime               toolExecutorSession
	Registry              *toolTaskRegistry
	RunContextFactory     func(*SpeechHandle, *llm.FunctionCall) (*llm.RunContext, error)
}

type ToolHandlingOptions 

type ToolHandlingOptions struct {
	Async *AsyncToolOptions
}

type ToolUpdate 

type ToolUpdate struct {
	Call   *llm.FunctionCall
	Output *llm.FunctionCallOutput
	// Value retains the pre-encoding structured value. Deferred delivery uses
	// Output, while the first progress update keeps ordinary tool return DX.
	Value any
}

type TranscriptionNodeItem 

type TranscriptionNodeItem struct {
	Text  string
	Timed *agents.TimedString
}

func TranscriptionTextItem 

func TranscriptionTextItem(text string) TranscriptionNodeItem

func TranscriptionTimedItem 

func TranscriptionTimedItem(value agents.TimedString) TranscriptionNodeItem

type TurnDetection 

type TurnDetection interface {
	// contains filtered or unexported methods
}

TurnDetection selects either one of the built-in turn-boundary strategies or a concrete streaming audio end-of-turn detector. The interface is sealed so invalid implementations cannot enter a running session; use UseTurnDetector for inference.TurnDetector instances.

type TurnDetectionMode 

type TurnDetectionMode string
const (
	TurnDetectionSTT         TurnDetectionMode = "stt"
	TurnDetectionVAD         TurnDetectionMode = "vad"
	TurnDetectionRealtimeLLM TurnDetectionMode = "realtime_llm"
	TurnDetectionManual      TurnDetectionMode = "manual"
)

type TurnDetectionUpdate 

type TurnDetectionUpdate = agents.Override[TurnDetection]

TurnDetectionUpdate preserves omitted, explicit disable, a concrete mode, and a concrete streaming detector.

func UseTurnDetectionMode 

func UseTurnDetectionMode(mode TurnDetectionMode) TurnDetectionUpdate

UseTurnDetectionMode creates a concrete mode override. The zero value of TurnDetectionUpdate inherits the session setting and agents.Disable opts out explicitly.

func UseTurnDetector 

func UseTurnDetector(detector *inference.TurnDetector) TurnDetectionUpdate

UseTurnDetector selects a caller-owned streaming audio turn detector.

type TurnHandlingOptions 

type TurnHandlingOptions struct {
	TurnDetection        TurnDetectionUpdate
	Endpointing          EndpointingOptions
	Interruption         InterruptionOptions
	PreemptiveGeneration PreemptiveGenerationOptions
	UserTurnLimit        UserTurnLimitOptions
}

func DefaultTurnHandlingOptions 

func DefaultTurnHandlingOptions(streamingDetector bool) TurnHandlingOptions

func (TurnHandlingOptions) Validate 

func (o TurnHandlingOptions) Validate() error

type UnexpectedModelBehaviorError 

type UnexpectedModelBehaviorError struct {
	Message string
	Cause   error
}

UnexpectedModelBehaviorError reports a missing or invalid structured test output after the configured retries have been exhausted.

func (*UnexpectedModelBehaviorError) Error 

func (e *UnexpectedModelBehaviorError) Error() string

func (*UnexpectedModelBehaviorError) Unwrap 

func (e *UnexpectedModelBehaviorError) Unwrap() []error

type UserInputTranscribedEvent 

type UserInputTranscribedEvent struct {
	EventBase
	Transcript string               `json:"transcript"`
	Final      bool                 `json:"isFinal"`
	ItemID     *string              `json:"itemId"`
	SpeakerID  *string              `json:"speakerId"`
	Language   *agents.LanguageCode `json:"language"`
}

type UserState 

type UserState string
const (
	UserStateSpeaking  UserState = "speaking"
	UserStateListening UserState = "listening"
	UserStateAway      UserState = "away"
)

type UserStateChangedEvent 

type UserStateChangedEvent struct {
	EventBase
	OldState UserState `json:"oldState"`
	NewState UserState `json:"newState"`
}

func NewUserStateChangedEvent 

func NewUserStateChangedEvent(oldState, newState UserState, createdAt time.Time) UserStateChangedEvent

type UserTranscriptionTimeoutEvent 

type UserTranscriptionTimeoutEvent struct {
	EventBase
	SpeechDuration     time.Duration `json:"-"`
	VADSpeechStartedAt time.Time     `json:"-"`
}

func (UserTranscriptionTimeoutEvent) MarshalJSON 

func (e UserTranscriptionTimeoutEvent) MarshalJSON() ([]byte, error)

type UserTurnAccumulator 

type UserTurnAccumulator struct {
	// contains filtered or unexported fields
}

func (*UserTurnAccumulator) Add 

func (a *UserTurnAccumulator) Add(now time.Time, transcript string, wordCount int)

func (*UserTurnAccumulator) Exceeded 

func (a *UserTurnAccumulator) Exceeded(now time.Time, options UserTurnLimitOptions) bool

func (*UserTurnAccumulator) Reset 

func (a *UserTurnAccumulator) Reset()

func (*UserTurnAccumulator) Snapshot 

func (a *UserTurnAccumulator) Snapshot(now time.Time) (string, int, time.Duration)

type UserTurnExceededEvent 

type UserTurnExceededEvent struct {
	EventBase
	Transcript            string        `json:"transcript"`
	AccumulatedTranscript string        `json:"accumulatedTranscript"`
	AccumulatedWordCount  int           `json:"accumulatedWordCount"`
	Duration              time.Duration `json:"-"`
}

type UserTurnLimitOptions 

type UserTurnLimitOptions struct {
	MaxWords    *int
	MaxDuration *time.Duration
}

func (UserTurnLimitOptions) Validate 

func (o UserTurnLimitOptions) Validate() error

type WaitForIdleOptions 

type WaitForIdleOptions struct {
	WaitForAgent *bool
	WaitForUser  *bool
}

WaitForIdleOptions controls which side of the conversation must be idle. Nil fields default to true, matching the Python/TypeScript SDKs.

Source Files

View all Source files

Directories

Path Synopsis
Package avatar implements provider-independent LiveKit avatar sessions and bounded PCM transports.
 Package avatar implements provider-independent LiveKit avatar sessions and bounded PCM transports.
roomioadapter
Package roomioadapter connects avatar readiness waits to a roomio RTCBridge.
 Package roomioadapter connects avatar readiness waits to a roomio RTCBridge.
Package backgroundaudio provides the background-audio player shipped by the LiveKit Agents TypeScript SDK, adapted to context-first Go APIs.
 Package backgroundaudio provides the background-audio player shipped by the LiveKit Agents TypeScript SDK, adapted to context-first Go APIs.
Package livekit binds a voice.AgentSession to the current job's LiveKit room, recording, observability, report, and primary-session lifecycle.
 Package livekit binds a voice.AgentSession to the current job's LiveKit room, recording, observability, report, and primary-session lifecycle.
Package recorderio records the user input and agent output sides of a voice session into a synchronized stereo Ogg/Opus file.
 Package recorderio records the user input and agent output sides of a voice session into a synchronized stereo Ogg/Opus file.
Package voicetest provides deterministic model doubles and assertion helpers for voice-agent tests.
 Package voicetest provides deterministic model doubles and assertion helpers for voice-agent tests.
Package transcription provides streaming transcript synchronization and text transforms for voice sessions.
 Package transcription provides streaming transcript synchronization and text transforms for voice sessions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.