context.go

Overview

The context.go file defines the core interfaces representing the invocation context for AI agents within the system. This context encapsulates all relevant runtime data, state, and control mechanisms needed during the lifecycle of an agent invocation. It models the hierarchical and temporal boundaries of an agent call, including nested sub-agent invocations and multi-step processing within a single invocation.

The file's primary purpose is to provide standardized abstractions for:

• Managing the lifecycle of an agent invocation (start, intermediate steps, end).

• Accessing session state, user input, memory, and artifacts relevant to the current invocation.

• Controlling invocation flow via early termination.

• Supporting sub-agent branching and isolation of conversation histories.

• Enabling read-only or mutable views of invocation data during callbacks.

These interfaces are foundational for the AI Agent Framework, enabling agents to operate with full awareness of their execution environment and maintain consistency across complex workflows.

Interfaces and Their Details

1. InvocationContext

The InvocationContext interface extends Go's standard context.Context and represents the full mutable context of an agent invocation. It manages the scope and lifecycle of a single invocation, which can include multiple agent calls and steps.

Purpose

• Track the lifecycle of an invocation, from the initial user message through multiple agent calls until a final response or explicit termination.

• Provide accessors to critical components such as the active agent, session data, memory, artifacts, and runtime configuration.

• Support invocation control via methods to end the invocation early and query its termination state.

• Maintain a hierarchical "branch" string to represent nested or parallel sub-agent invocations, isolating their conversation histories.

Methods

Usage Example

func exampleUsage(ctx InvocationContext) {
    agent := ctx.Agent()
    session := ctx.Session()
    userMsg := ctx.UserContent()

    // Check if invocation ended
    if ctx.Ended() {
        return
    }

    // Access memory and artifacts
    memory := ctx.Memory()
    artifacts := ctx.Artifacts()

    // End invocation early if certain condition met
    if shouldStop() {
        ctx.EndInvocation()
    }
}

2. ReadonlyContext

ReadonlyContext is a restricted interface providing read-only access to essential invocation data. It is used when mutation of invocation state or artifacts is not allowed or not needed, such as during inspection or in safe callback phases.

Purpose

• Safely expose invocation metadata without mutable state.

• Provide identifiers and session-related information.

• Support read-only access to session state snapshots.

Methods

3. CallbackContext

CallbackContext extends ReadonlyContext by adding mutable access to session state and artifacts. It is passed to user-defined lifecycle callbacks that execute before or after the main agent run.

Purpose

• Provide callback handlers with access to mutable session state for updates.

• Allow lifecycle callbacks to save or load artifacts during agent execution.

• Enable inspection of invocation metadata while allowing controlled mutation.

Methods (in addition to those inherited from ReadonlyContext)

Important Implementation Details and Algorithms

• Invocation Lifecycle:
  The invocation starts with a user message (UserContent()) and ends either by the agent producing a final response or by the explicit call to EndInvocation(). The Ended() method allows agents or runners to check if processing should continue.

• Branching Model:
  Invocations may involve nested or parallel sub-agent calls. The Branch() string encodes this hierarchical path (e.g., "agent1.agent2.agent3") to isolate sub-agent conversations and memory, particularly important in parallel execution scenarios.

• Session and Memory Scope:
  The session represents the current conversation context, including persistent state and event history, while memory provides a user-scoped key-value store spanning multiple sessions.

• Artifacts Access:
  Artifacts represent session-bound files or blobs referenced or created during invocation. The context exposes artifact services for agents or callbacks to save and retrieve such data.

• Invocation Identification:
  Unique invocation IDs are generated per invocation to enable traceability and correlation across distributed logs or event streams.

• Read-Only vs Mutable Views:
  Splitting the context into ReadonlyContext and CallbackContext supports safe access patterns, ensuring that mutation only occurs in lifecycle callbacks or authorized phases.

Interaction with Other Parts of the System

• AI Agent Framework (AI Agent Framework)
  InvocationContext is the primary environment interface passed into agents during their execution (agent.Run(ctx InvocationContext)). It enables agents to access all relevant runtime data and control invocation flow.

• Session Management (Session Management)
  The session object accessed via Session() holds conversation history, state, and user metadata. State mutations during an invocation update this session.

• Artifact Management (Artifact Management)
  The Artifacts() accessor connects to artifact services that agents use to store or retrieve files or data blobs during invocation.

• Agent Lifecycle and Callbacks (Agent Lifecycle and Callbacks)
  The CallbackContext interface is utilized during lifecycle callbacks before or after the main agent run, allowing safe mutation of state and artifacts.

• Agent Execution Runner (Agent Execution Runner)
  The runner component coordinates invocation execution using this context interface to manage invocation lifecycle, branching, and termination.

• Agent Workflow Management (Agent Workflow Management)
  Branching (Branch()) supports parallel and sequential workflow agents by isolating sub-agent contexts and histories.

Diagram

classDiagram
class InvocationContext {
+Agent()
+Artifacts()
+Memory()
+Session()
+UserContent()
+RunConfig()
+InvocationID()
+Branch()
+EndInvocation()
+Ended()
}
class ReadonlyContext {
+UserContent()
+InvocationID()
+AgentName()
+ReadonlyState()
+UserID()
+AppName()
+SessionID()
+Branch()
}
class CallbackContext {
+Artifacts()
+State()
}
InvocationContext <|-- ReadonlyContext
InvocationContext <|-- CallbackContext
InvocationContext "1" --> "1" Agent
InvocationContext "1" --> "1" Session
InvocationContext "1" --> "1" Memory
InvocationContext "1" --> "1" Artifacts
InvocationContext "1" --> "1" RunConfig

This class diagram visualizes the relationships among the main interfaces defined in this file:

• InvocationContext is the base interface representing the full mutable invocation context.

• ReadonlyContext inherits from InvocationContext but restricts to read-only access.

• CallbackContext also inherits from InvocationContext and provides additional mutable state and artifact access for callbacks.

• The InvocationContext holds references to core runtime components such as Agent, Session, Memory, Artifacts, and runtime configuration (RunConfig).

Summary of Key Types in context.go

References

• For details about session and state management, see Session Management.

• For artifact service interfaces and implementations, see Artifact Management.

• For agent lifecycle callbacks that consume CallbackContext, see Agent Lifecycle and Callbacks.

• For the agent invocation lifecycle and usage of InvocationContext, see AI Agent Framework.

• For running agents and managing invocation flow, see Agent Execution Runner.