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
- type AppendRetryError
- type Config
- type Transcript
- func (t *Transcript) Close() error
- func (t *Transcript) HighestSeq(ctx context.Context, appName, userID, root string) (int64, error)
- func (t *Transcript) Invalidate(appName, userID, root string)
- func (t *Transcript) Service() session.Service
- func (t *Transcript) Since(ctx context.Context, fromSeq int64, opts ...eventlog.QueryOption) iter.Seq2[eventlog.Entry, error]
- func (t *Transcript) Subscribe(appName, userID, root string) (<-chan struct{}, func())
Constants ¶
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.
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) HighestSeq ¶
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.