invocation_context.go

Overview

This file defines the core implementation of the InvocationContext within the agent execution lifecycle. The InvocationContext encapsulates all relevant contextual information needed during a single invocation of an agent. It provides access to session state, memory, artifacts, agent metadata, user input, and invocation control flags. This context is essential to manage the flow and data for nested or parallel invocations, enabling agents to query and manipulate their runtime environment consistently.

The file primarily implements the InvocationContext struct and its constructor, along with accessor methods to retrieve or update invocation-related data. This supports lifecycle management such as uniquely identifying invocations (InvocationID) and signaling when an invocation ends (EndInvocation).

This implementation is a concrete realization of the concepts described in the Agent Invocation Context topic, serving as a foundational piece for agent execution within the broader AI Agent Framework.

Types and Functions

`InvocationContextParams`

A struct bundling all parameters required to initialize an InvocationContext. It holds references to:

Artifacts (agent.Artifacts): Interface for artifact management during invocation.
Memory (agent.Memory): Agent-scoped memory for persistent or session-specific data.
Session (session.Session): The user-agent conversation session.
Branch (string): Identifier for sub-agent invocation paths (used for workflow branching).
Agent (agent.Agent): The agent instance handling the current invocation.
UserContent (*genai.Content): The original user input content triggering the invocation.
RunConfig (*agent.RunConfig): Configuration parameters for the invocation runtime.
EndInvocation (bool): Flag indicating whether the invocation should be ended.

This struct provides a convenient container for passing all context dependencies when instantiating an invocation.

`NewInvocationContext`

func NewInvocationContext(ctx context.Context, params InvocationContextParams) agent.InvocationContext

Purpose:
Factory function that creates a new InvocationContext instance wrapping a standard Go context.Context with invocation-specific parameters.

Parameters:

ctx: The base context.Context to embed.
params: An InvocationContextParams struct containing all necessary invocation data.

Returns:

An agent.InvocationContext interface implemented by InvocationContext.

Details:

Generates a unique invocation ID prefixed with "e-" concatenated with a UUID string.
Stores all passed parameters internally for later access.

Usage example:

params := InvocationContextParams{
    Artifacts: artifactSvc,
    Memory: memorySvc,
    Session: sessionInst,
    Branch: "main.branch",
    Agent: myAgent,
    UserContent: userMsg,
    RunConfig: runCfg,
}
invCtx := NewInvocationContext(baseCtx, params)

`InvocationContext` struct

type InvocationContext struct {
    context.Context

    params       InvocationContextParams
    invocationID string
}

Embeds the standard Go context.Context interface.
Holds invocation parameters in params.
Maintains a unique invocationID string for tracing and logging.

Methods of `InvocationContext`

All methods provide access to state or control flags relevant during an agent invocation.

Method Name	Signature	Description
`Artifacts()`	`agent.Artifacts`	Returns the artifact service interface for managing files/blobs during the invocation.
`Agent()`	`agent.Agent`	Returns the agent instance handling this invocation.
`Branch()`	`string`	Returns the branch path string representing hierarchical sub-agent invocation context.
`InvocationID()`	`string`	Returns the unique invocation ID string assigned at creation.
`Memory()`	`agent.Memory`	Returns the memory interface scoped to this invocation (session or persistent).
`Session()`	`session.Session`	Returns the session object representing conversation and event history.
`UserContent()`	`*genai.Content`	Returns the original user input content that triggered this invocation.
`RunConfig()`	`*agent.RunConfig`	Returns the runtime configuration parameters for this invocation.
`EndInvocation()`	`void`	Sets the internal flag to mark the invocation as ended, signaling termination to the runner.
`Ended()`	`bool`	Returns whether the invocation has been marked as ended.

Method Details and Behavior

Artifacts(), Agent(), Branch(), Memory(), Session(), UserContent(), RunConfig()
These methods provide read-only accessors to the respective fields stored in params. They enable agent implementations and runner components to retrieve contextual information without mutating the state.
InvocationID()
Provides a unique string identifier prefixed by "e-" plus a UUID. This ID is useful for tracing invocation flow and correlating logs or telemetry.
EndInvocation() and Ended()
These control the lifecycle of the invocation. EndInvocation() sets a Boolean flag within params indicating that the current invocation should be terminated early by the runner or lifecycle manager. Ended() returns whether this flag is set. This mechanism facilitates controlled early exits from nested or parallel agent calls, supporting workflow branching and termination semantics.

Implementation Details

The file uses the github.com/google/uuid package to generate unique invocation IDs.
The InvocationContext embeds Go's standard context.Context to allow cancellation, deadlines, and value propagation alongside agent-specific data.
The design follows composition over inheritance, wrapping the base context and augmenting it with agent invocation-specific parameters.
The InvocationContextParams struct centralizes dependencies, making it easier to extend or modify invocation data without changing method signatures.
Invocation termination is implemented via a simple Boolean flag in parameters, ensuring safe concurrent reads yet simple mutation.

Interaction with Other Components

Agent Invocation Context ([80572])
This file implements the core context interface and concrete type described in the Agent Invocation Context subtopic, which defines lifecycle, session, memory, and artifact access during agent runs.
Agent Interface (agent.Agent)
The context exposes the current agent instance, enabling downstream components or sub-agents to query metadata or invoke agent methods.
Session Management ([80559])
Through the Session() accessor, this context integrates with the session subsystem, allowing agents to track conversation state, event history, and user interactions.
Memory Interface (agent.Memory)
Provides agents scoped memory for persistent context, enabling stateful behavior across invocations.
Artifact Management ([80557])
The Artifacts() method returns the artifact service interface, allowing agents to load, save, or version files and blobs related to the invocation.
Run Configuration (agent.RunConfig)
Exposes runtime parameters such as model settings, tool configurations, or environment flags influencing agent execution.
Invocation Control and Lifecycle ([80573])
The EndInvocation() and Ended() methods support lifecycle callbacks and runner logic to handle premature invocation termination.

Visual Diagram

classDiagram
class InvocationContext {
+Artifacts()
+Agent()
+Branch()
+InvocationID()
+Memory()
+Session()
+UserContent()
+RunConfig()
+EndInvocation()
+Ended()
}
InvocationContext o-- InvocationContextParams : has
InvocationContextParams : +Artifacts
InvocationContextParams : +Memory
InvocationContextParams : +Session
InvocationContextParams : +Branch
InvocationContextParams : +Agent
InvocationContextParams : +UserContent
InvocationContextParams : +RunConfig
InvocationContextParams : +EndInvocation

This class diagram illustrates the InvocationContext struct and its methods, showing its composition relationship to the InvocationContextParams struct that holds the underlying data references and flags.

invocation_context.go

Overview

Types and Functions

InvocationContextParams

NewInvocationContext

InvocationContext struct

Methods of InvocationContext