readonly_context.go

Overview

The readonly_context.go file defines a lightweight, read-only wrapper around an existing agent invocation context within the system. It provides safe, immutable access to core session and invocation metadata without permitting any state changes or side effects. This read-only context is primarily used in situations where an agent or component needs to inspect invocation details such as the session ID, user ID, branch, or user content, but must not modify any state or artifacts.

This file is part of the broader Agent Invocation Context subtopic, which manages the lifecycle and data scope of agent invocations. ReadonlyContext implements the agent.ReadonlyContext interface by delegating read-only method calls to its embedded InvocationContext. It enables clear separation between mutable contexts used during agent execution callbacks and immutable views that guarantee no side-effects during inspection or logging.

Types and Functions

ReadonlyContext struct

type ReadonlyContext struct {
    context.Context
    InvocationContext agent.InvocationContext
}

• Description:
  ReadonlyContext embeds a standard Go context.Context and holds a reference to an underlying agent.InvocationContext. It implements the agent.ReadonlyContext interface by forwarding read-only method calls to the embedded InvocationContext.

• Fields:

  • Context (context.Context): The base Go context for cancellation, deadlines, and request-scoped values.

  • InvocationContext (agent.InvocationContext): The underlying full invocation context providing session and invocation data.

NewReadonlyContext

func NewReadonlyContext(ctx agent.InvocationContext) agent.ReadonlyContext

• Description:
  Constructs and returns a new ReadonlyContext instance that wraps the given agent.InvocationContext. This allows caller code to safely expose only read-only access to invocation data.

• Parameters:

  • ctx (agent.InvocationContext): The original invocation context to wrap.

• Returns:

  • agent.ReadonlyContext: The new read-only wrapper context.

• Usage:

readonlyCtx := NewReadonlyContext(invocationCtx)
appName := readonlyCtx.AppName()

Methods on ReadonlyContext

Each method implements a corresponding member of the agent.ReadonlyContext interface by delegating to the underlying InvocationContext. All methods provide read-only access to session, invocation, or user content data.

Method Details

func (c *ReadonlyContext) AppName() string {
    return c.InvocationContext.Session().AppName()
}

• Returns the application name from the session.

func (c *ReadonlyContext) Branch() string {
    return c.InvocationContext.Branch()
}

• Returns the branch ID indicating the invocation's sub-agent lineage.

func (c *ReadonlyContext) SessionID() string {
    return c.InvocationContext.Session().ID()
}

• Returns the session's unique ID.

func (c *ReadonlyContext) UserID() string {
    return c.InvocationContext.Session().UserID()
}

• Returns the user ID associated with the session.

func (c *ReadonlyContext) AgentName() string {
    return c.InvocationContext.Agent().Name()
}

• Returns the agent name currently executing this invocation.

func (c *ReadonlyContext) ReadonlyState() session.ReadonlyState {
    return c.InvocationContext.Session().State()
}

• Returns an immutable snapshot of the session state.

func (c *ReadonlyContext) InvocationID() string {
    return c.InvocationContext.InvocationID()
}

• Returns the unique invocation identifier.

func (c *ReadonlyContext) UserContent() *genai.Content {
    return c.InvocationContext.UserContent()
}

• Returns the original user content that triggered the invocation.

Implementation Details

• The ReadonlyContext type is a simple adapter that enforces read-only access by exposing only getter methods and no mutators.

• It leverages Go embedding for context.Context to support standard context features like cancellation and deadlines transparently.

• The underlying InvocationContext is expected to hold full mutable state and lifecycle management, but ReadonlyContext only exposes its read-only interface.

• This design avoids duplicating session or invocation state data by delegation, reducing memory overhead and ensuring data consistency.

Interaction with Other Components

• Agent Invocation Context ([80572]):
  ReadonlyContext is a specific implementation of the read-only subset of the broader InvocationContext interface, designed for safe inspection during agent execution.

• Session Management ([80559]):
  Session data such as SessionID(), UserID(), and ReadonlyState() are accessed from the underlying Session object in InvocationContext.

• Agent Lifecycle and Callbacks ([80573]):
  ReadonlyContext may be passed to lifecycle callback handlers that require immutable views of invocation data.

• LLM Integration and Agents ([80562]):
  Agents executing LLM calls or tool invocations may use ReadonlyContext to access invocation metadata without risking state mutation.

Code Structure Diagram

classDiagram
class ReadonlyContext {
+AppName()
+Branch()
+SessionID()
+UserID()
+AgentName()
+ReadonlyState()
+InvocationID()
+UserContent()
}
ReadonlyContext o-- "1" agent.InvocationContext
ReadonlyContext o-- "1" context.Context

• ReadonlyContext composes agent.InvocationContext and context.Context.

• All public methods delegate to InvocationContext to retrieve read-only session and invocation data.

Usage Example

// Assume invocationCtx is an existing agent.InvocationContext instance
readonlyCtx := NewReadonlyContext(invocationCtx)

// Access read-only session and invocation metadata
fmt.Println("App Name:", readonlyCtx.AppName())
fmt.Println("Session ID:", readonlyCtx.SessionID())
fmt.Println("User ID:", readonlyCtx.UserID())
fmt.Println("Agent Name:", readonlyCtx.AgentName())

// Access user content triggering the invocation
userContent := readonlyCtx.UserContent()
if userContent != nil {
    fmt.Println("User input text:", userContent.Text)
}

This example shows how to create a ReadonlyContext to safely expose invocation data for logging, auditing, or non-mutating logic.

References

• For detailed context lifecycle management and mutable context interfaces, see Agent Invocation Context.

• For session state definitions and read-only snapshots, see Session Management.

• For agent lifecycle callback usage of read-only contexts, see Agent Lifecycle and Callbacks.

• For overall AI agent framework integration, see AI Agent Framework.

• For contextual use in LLM agent execution, see LLM Integration and Agents.

This file provides a fundamental utility for safely exposing agent invocation information in read-only form, ensuring separation of concerns and robust context management within the agent execution environment.