Agent Invocation Context

Purpose

The Agent Invocation Context subtopic addresses the need to encapsulate all relevant contextual information and state management during an agent's invocation lifecycle within the broader AI Agent Framework. This context acts as a comprehensive environment that governs how an agent processes an invocation—from the initial user input, through multiple agent calls and steps, to the final response or transfer to another agent.

This subtopic specifically solves the challenge of managing complex, nested, and possibly concurrent agent executions by providing interfaces and implementations that unify session data, memory, artifacts, invocation metadata, and lifecycle control. It also enables consistent access to immutable and mutable state, and supports callback integration during agent execution.

By defining these context interfaces and concrete implementations, the system ensures agents operate with a consistent view of the current session, memory, and artifacts, while also enabling lifecycle controls such as early termination or branching for parallel agents. This complements other subtopics like Agent Lifecycle and Callbacks by providing the contextual backbone they rely upon.

Functionality

The core functionality revolves around the InvocationContext interface, which models the lifecycle and data scope of a single agent invocation. Key aspects include:

• Invocation Lifecycle Management:
  An invocation begins with the user message and runs until a final response is generated or explicitly ended. It can encompass multiple nested agent calls and steps (e.g., multiple LLM calls or tool invocations). The context tracks whether the invocation has ended via EndInvocation() and Ended() methods.

• Data Accessors for Agent Execution:
  The context provides accessors for:

  • The active Agent() handling the invocation.

  • The current Session() object representing the conversation state.

  • The Memory() scoped to the user session, providing long-term context.

  • The Artifacts() service to load or save files and binary data used within the invocation.

  • The original UserContent() that triggered the invocation.

  • The RunConfig() which holds runtime parameters for the invocation.

  • An InvocationID() for uniquely identifying the invocation instance.

  • A Branch() string representing hierarchical sub-agent invocation paths, important for parallel sub-agent isolation.

• Read-Only and Callback Contexts:
  To support different execution phases, the subtopic defines:

  • ReadonlyContext: A read-only view of invocation data, ideal for safe inspection without mutation.

  • CallbackContext: Extends ReadonlyContext and adds mutable state and artifact saving capabilities, used during agent lifecycle callbacks.

• Implementation Details:
  The concrete InvocationContext implementation wraps a standard Go context.Context and holds references to session, memory, artifacts, and other invocation parameters. It generates a unique invocation ID for traceability and supports branching for nested or parallel agent calls.

• Artifact and State Change Tracking:
  The CallbackContext implementation tracks state deltas and artifact version changes during execution, enabling fine-grained updates to session state and artifact metadata that are committed after the invocation completes.

Code Snippet Illustration

Creating a new invocation context involves initializing it with session, memory, artifacts, and agent references:

params := InvocationContextParams{
    Artifacts: artifactService,
    Memory:    memoryService,
    Session:   sessionInstance,
    Branch:    "agent_1.agent_2",
    Agent:     currentAgent,
    UserContent: userContent,
    RunConfig: runConfig,
}
invocationCtx := context.NewInvocationContext(baseCtx, params)

Within the invocation, the context can be queried or updated as follows:

if !invocationCtx.Ended() {
    // Access session and memory
    userID := invocationCtx.Session().UserID()
    mem := invocationCtx.Memory()

    // End the invocation early if needed
    invocationCtx.EndInvocation()
}

The callback context wraps the invocation context to provide mutable state and artifact save tracking:

cbCtx := context.NewCallbackContext(invocationCtx)
cbCtx.State().Set("key", "value")
cbCtx.Artifacts().Save(ctx, "file.txt", contentPart)

Integration

The Agent Invocation Context is tightly integrated with multiple components in the agent ecosystem:

• Parent Topic - AI Agent Framework:
  The invocation context provides the runtime environment supporting agent lifecycle management and invocation handled by the core agent interfaces in AI Agent Framework.

• Session Management:
  It directly interacts with the Session Management subsystem by exposing the current session state and enabling state mutations during agent execution.

• Artifact Management:
  Via the Artifacts() accessor, it integrates with the Artifact Management services to allow agents to read and write persistent or in-memory artifacts during invocation.

• Agent Lifecycle and Callbacks:
  The CallbackContext interface and its implementation facilitate lifecycle hooks, enabling callbacks to inspect or mutate state and artifacts during agent runs.

• Agent Execution Runner:
  The runner component (Agent Execution Runner) uses the invocation context to coordinate the execution flow, keeping track of invocation IDs, branching, and termination signals.

• Workflow Agents:
  The Branch() concept supports complex agent workflows like parallel agent execution (Agent Workflow Management), where sub-agents must maintain isolated contexts.

This subtopic thus forms the foundational context layer that enables consistent, stateful, and manageable agent invocations, supporting complex agent orchestration and tooling integrations.

Diagram

classDiagram
class InvocationContext {
+Agent() Agent
+Session() Session
+Memory() Memory
+Artifacts() Artifacts
+UserContent() Content
+RunConfig() RunConfig
+InvocationID() string
+Branch() string
+EndInvocation()
+Ended() bool
}
class ReadonlyContext {
+AgentName() string
+SessionID() string
+UserID() string
+AppName() string
+InvocationID() string
+Branch() string
+UserContent() Content
+ReadonlyState() ReadonlyState
}
class CallbackContext {
+State() State
+Artifacts() Artifacts
}
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 illustrates the relationship between the main context interfaces (InvocationContext, ReadonlyContext, and CallbackContext) and their key data accessors and lifecycle methods, capturing how invocation state is exposed and controlled during an agent's execution.