metadata.go

Overview

This file provides utility functions and data structures for managing and converting metadata related to agent invocation and event handling within the Agent-To-Agent (A2A) communication framework. It focuses on constructing consistent metadata keys, extracting invocation context information, and enriching event metadata with additional details required for telemetry, session tracking, and agent interaction.

Key responsibilities include:

• Defining a standardized prefixing scheme for metadata keys used in A2A events.

• Extracting user and session information from request contexts to build invocation metadata.

• Transforming session event data into enriched metadata maps.

• Managing action-related metadata flags for event handling.

This file plays a crucial role in bridging session and invocation context details with A2A event metadata, supporting downstream event processing and telemetry.

Functions and Types

ToA2AMetaKey

func ToA2AMetaKey(key string) string

• Purpose:
  Prefixes a given metadata key string with "adk_" to differentiate ADK-related values stored in metadata within A2A events.

• Parameters:

  • key (string): The base key name to prefix.

• Returns:

  • (string): The prefixed key, e.g., "adk_" + key.

• Usage Example:

  prefixedKey := ToA2AMetaKey("user_id") // returns "adk_user_id"
  

invocationMeta (struct)

type invocationMeta struct {
    userID    string
    sessionID string
    eventMeta map[string]any
}

• Purpose:
  Holds metadata extracted from the invocation context, including user ID, session ID, and a map of key-value pairs representing event metadata.

• Fields:

  • userID (string): Identifier for the user who initiated the invocation.

  • sessionID (string): Identifier for the session related to the invocation.

  • eventMeta (map[string]any): A map containing key-value pairs for event metadata, typically prefixed with "adk_".

toInvocationMeta

func toInvocationMeta(ctx context.Context, config ExecutorConfig, reqCtx *a2asrv.RequestContext) invocationMeta

• Purpose:
  Constructs an invocationMeta instance by extracting user and session information from the provided request context and configuration.

• Parameters:

  • ctx (context.Context): The Go context which may contain call-level user data.

  • config (ExecutorConfig): Configuration containing runtime settings such as application name.

  • reqCtx (*a2asrv.RequestContext): The request context from the A2A server, which includes context IDs.

• Returns:

  • invocationMeta: Struct populated with user ID, session ID, and a metadata map.

• Implementation Details:

  • The user ID defaults to "A2A_USER_" + reqCtx.ContextID.

  • If call context information is available and contains a user name, it overrides the default user ID.

  • Metadata map includes keys for application name, user ID, and session ID, all prefixed with "adk_".

  • This function is designed to integrate with the agent invocation lifecycle (Agent Invocation Context).

• Usage Example:

  meta := toInvocationMeta(ctx, executorConfig, reqCtx)
  fmt.Println(meta.userID, meta.sessionID, meta.eventMeta)
  

toEventMeta

func toEventMeta(meta invocationMeta, event *session.Event) (map[string]any, error)

• Purpose:
  Converts session event data combined with invocation metadata into a comprehensive metadata map for A2A events.

• Parameters:

  • meta (invocationMeta): Metadata from the invocation context.

  • event (*session.Event): The session event containing invocation details and LLM response.

• Returns:

  • map[string]any: A merged map with contextual metadata and event-specific details.

  • error: Any error encountered during conversion, especially during grounding metadata transformation.

• Implementation Details:

  • Starts by copying invocation metadata into a new map.

  • Adds fields like invocation_id, author, and branch if non-empty, all prefixed with "adk_".

  • Inspects the LLM response to add error codes and grounding metadata (converted through converters.ToMapStructure).

  • Leaves placeholders (TODO) for additional custom and usage metadata integration.

  • This function facilitates conversion between session events and A2A events as part of event processing (Event Conversion and Processing).

• Usage Example:

  eventMeta, err := toEventMeta(invMeta, sessionEvent)
  if err != nil {
      // handle error
  }
  // use eventMeta in A2A event
  

setActionsMeta

func setActionsMeta(meta map[string]any, actions session.EventActions) map[string]any

• Purpose:
  Updates or initializes a metadata map with flags related to event actions such as escalation or transfer to an agent.

• Parameters:

  • meta (map[string]any): Existing metadata map, can be nil.

  • actions (session.EventActions): Struct containing action flags (Escalate and TransferToAgent).

• Returns:

  • map[string]any: Updated metadata map with action flags set.

• Implementation Details:

  • If no actions are specified (neither escalation nor transfer), returns the original meta unchanged.

  • Initializes a new map if meta is nil and actions need to be set.

  • Sets predefined keys (metadataEscalateKey and metadataTransferToAgentKey) to indicate escalation or transfer actions.

  • Supports event routing or handling based on these metadata flags.

• Usage Example:

  updatedMeta := setActionsMeta(existingMeta, eventActions)
  

Important Implementation Details

• The file uses a naming convention prefix "adk_" to namespace all metadata keys related to the ADK system in A2A events, avoiding key collisions.

• The invocationMeta struct acts as a container combining user and session identifiers with a base metadata map, enabling reuse when annotating multiple events.

• User ID extraction prefers explicit user information from the call context if present; otherwise, it defaults to a constructed string based on the request context ID.

• The toEventMeta function carefully merges static invocation metadata with dynamic event data, including details from the LLM response such as errors and grounding data.

• The grounding metadata conversion leverages a utility function (converters.ToMapStructure) to ensure complex nested structures are serialized into maps compatible with metadata storage.

• Action metadata management supports signaling escalation or transferring control to another agent, facilitating complex agent workflows (Agent Workflow Management).

Interaction with Other System Components

• Interacts with the A2A server request context (a2asrv.RequestContext) to extract invocation identifiers and user information.

• Relies on session event structures (session.Event and session.EventActions) to enrich metadata with event lifecycle and action details (Session Management).

• Uses internal converters for metadata serialization (converters.ToMapStructure).

• Supports integration with the A2A protocol layer (Remote Agent Communication (A2A)) by preparing metadata maps expected in A2A events.

• Plays a role in the agent execution lifecycle by preparing metadata for telemetry, logging, and event tracking (Agent Invocation Context, Agent Lifecycle and Callbacks).

• Metadata keys set here (metadataEscalateKey, metadataTransferToAgentKey) are used elsewhere in event routing and agent selection logic (Agent Selection Logic).

File Structure Diagram

classDiagram
class invocationMeta {
- userID: string
- sessionID: string
- eventMeta: map[string]any
}
class ToA2AMetaKey {
<<function>>
}
class toInvocationMeta {
<<function>>
}
class toEventMeta {
<<function>>
}
class setActionsMeta {
<<function>>
}
invocationMeta <.. toInvocationMeta : returns
toInvocationMeta --> ToA2AMetaKey : uses
toEventMeta --> ToA2AMetaKey : uses
setActionsMeta ..> session.EventActions : reads

This diagram shows the primary data structure invocationMeta and the main functions operating on metadata. The dependency on the key-prefixing function ToA2AMetaKey is highlighted, illustrating how metadata keys are constructed consistently across functions. The relation to session.EventActions is indicated for action metadata management.