agentengine

package
v3.2.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package agentengine is the eventlog.Transcript backend on Vertex AI Agent Engine Sessions, written on aiplatform/apiv1beta1.SessionClient directly (docs/external-state-design.md decision 7: ADK's own session/vertexai client lets the service assign event IDs and drops UsageMetadata and FinishReason on ordinary events, which resume and the usage tracker read back).

What it stores, per decision 6: every SessionEvent carries the whole ADK event as JSON in raw_event, together with the seq this process assigned and the caller sidecar. The envelope fields (author, content as text parts, timestamp, branch, custom metadata) are populated too, for the console and Memory Bank, but on read raw_event is the record.

Session IDs are mapped where Agent Engine's charset requires it (decision 8; see mapID), and the original ID is kept in session state. One process is the writer for a session (decision 1), so once a session is loaded the in-memory copy is authoritative: Get and Since read it and cost no RPC. A tree is loaded whole on first touch (one ListSessions plus one ListEvents per member) so the next seq is known across every session in it.

Index

Constants

View Source
const DefaultSessionTTL = 720 * time.Hour

DefaultSessionTTL is the session expiry written when Config.SessionTTL is zero: 30 days. Agent Engine's minimum is 24 hours.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppendRetryError

type AppendRetryError struct {
	// Outcome is "persisted" (the retry was rejected too), "skipped"
	// (the shared budget was spent) or "abandoned" (ctx ended during
	// the backoff).
	Outcome string
	Err     error
}

AppendRetryError is how an append whose quota retry did not rescue it reaches the caller, mirroring models.RetryError: the outcome first, then the service's error, which Unwrap keeps reachable for status.Code and errors.Is.

func (*AppendRetryError) Error

func (e *AppendRetryError) Error() string

func (*AppendRetryError) GRPCStatus

func (e *AppendRetryError) GRPCStatus() *status.Status

GRPCStatus lets status.Code see the service's code through the wrapper, so a caller can still tell a quota failure apart.

func (*AppendRetryError) Unwrap

func (e *AppendRetryError) Unwrap() error

type Config

type Config struct {
	// ReasoningEngine is the full resource name,
	// projects/P/locations/L/reasoningEngines/N. The project and
	// location are read from it; the regional API endpoint
	// (L-aiplatform.googleapis.com) is derived from the location
	// unless ClientOptions carries its own option.WithEndpoint.
	ReasoningEngine string
	// SessionTTL is the expiry set on every session at creation and
	// refreshed on append once less than half of it remains. Zero
	// means DefaultSessionTTL.
	SessionTTL time.Duration
	// ClientOptions are passed to aiplatform.NewSessionClient after the
	// endpoint, so a caller's option wins. Tests use WithGRPCConn.
	ClientOptions []option.ClientOption
	// AppendRetryBackoff is the wait before the one retry a quota
	// rejection (ResourceExhausted) on AppendEvent gets, drawn from a
	// shared budget as the model-call retry does (#935). Zero means 2s;
	// negative disables the retry.
	AppendRetryBackoff time.Duration
}

Config selects the reasoning engine that holds the sessions.

func (Config) Validate

func (c Config) Validate() error

Validate checks the config without opening a connection.

type Transcript

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

Transcript is the Agent Engine backend. Construct with Open.

func Open

func Open(ctx context.Context, cfg Config) (*Transcript, error)

Open connects to Agent Engine and returns the backend. No RPC is made until a session is touched.

func (*Transcript) Close

func (t *Transcript) Close() error

Close implements eventlog.Transcript.

func (*Transcript) HighestSeq

func (t *Transcript) HighestSeq(ctx context.Context, appName, userID, root string) (int64, error)

HighestSeq implements eventlog.Transcript: the highest seq among the tree's current events, 0 when it has none.

func (*Transcript) Invalidate

func (t *Transcript) Invalidate(appName, userID, root string)

Invalidate implements eventlog.TranscriptInvalidator: every tree under root (root itself and roots derived from it, "<root>:digest" and the like) is reloaded from the store on its next touch. A lease-holding Handle calls it when it takes a session's lease, because another instance may have appended while this one did not hold it; serving the old cache would resume on a truncated history and reuse a seq.

func (*Transcript) Service

func (t *Transcript) Service() session.Service

Service implements eventlog.Transcript.

func (*Transcript) Since

func (t *Transcript) Since(ctx context.Context, fromSeq int64, opts ...eventlog.QueryOption) iter.Seq2[eventlog.Entry, error]

Since implements eventlog.Transcript. Reads are served from the loaded tree; the first call for a tree loads it.

func (*Transcript) Subscribe

func (t *Transcript) Subscribe(appName, userID, root string) (<-chan struct{}, func())

Subscribe implements eventlog.Transcript.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL