events.go

Overview

This file provides core utilities for converting between two event models in the system:

• The internal ADK session events (session.Event), which represent interactions within an agent session.

• The external A2A protocol events/messages (a2a.Event, a2a.Message), which enable communication between distributed agents over the Agent-To-Agent (A2A) protocol.

The primary purpose of this file is to implement bidirectional translation between these formats, enabling session events generated locally to be sent as A2A messages to remote agents, and A2A events received from remote agents to be converted back into session events for local consumption.

Additionally, this file manages custom metadata keys related to task and context IDs, propagates action flags (like escalation or transfer requests), and identifies long-running tool invocations embedded in event parts.

This functionality is essential for enabling distributed multi-agent workflows, remote agent invocation, and streaming incremental event updates.

Key Entities and Functions

Constants and Metadata Keys

• customMetaTaskIDKey and customMetaContextIDKey: Strings used as keys in session event custom metadata to store the A2A task ID and context ID associated with the event.

• metadataEscalateKey and metadataTransferToAgentKey: Keys used in A2A message metadata to indicate escalation or transfer actions.

These keys use helper functions ToADKMetaKey and ToA2AMetaKey to apply consistent prefixes, ensuring differentiation of A2A-related metadata within session events.

NewRemoteAgentEvent(ctx agent.InvocationContext) *session.Event

Creates a new session.Event authored by the agent running within the provided invocation context.

• Parameters:

  • ctx: The agent invocation context providing the current invocation ID, agent name, and branch.

• Returns:
  A pointer to a new session.Event with:

  • InvocationID set to ctx.InvocationID().

  • Author set to the agent's name (ctx.Agent().Name()).

  • Branch set to the current branch (ctx.Branch()).

Usage Example:

event := NewRemoteAgentEvent(ctx)

This function is used as a factory method for creating events consistently attributed to the current agent invocation.

EventToMessage(event *session.Event) (*a2a.Message, error)

Converts an ADK session event to an A2A protocol message for sending to remote agents.

• Parameters:

  • event: The ADK session event to convert.

• Returns:

  • Pointer to an a2a.Message representing the event.

  • Error if conversion fails.

• Details:

  • Returns nil if the input event is nil.

  • Converts the event content parts to A2A parts via ToA2AParts.

  • Sets the message role based on the event author:

    • "user" author → a2a.MessageRoleUser.

    • Otherwise → a2a.MessageRoleAgent.

  • Attaches event actions (e.g., escalate, transfer) as metadata on the message.

Usage:
Used when sending an ADK event over the network to a remote agent using the A2A protocol.

ToSessionEvent(ctx agent.InvocationContext, event a2a.Event) (*session.Event, error)

Converts an incoming A2A event into an ADK session event authored by the agent in the given invocation context.

• Parameters:

  • ctx: The invocation context for attribution.

  • event: The A2A event to convert (can be of various concrete types).

• Returns:

  • Pointer to the converted session.Event.

  • Error if conversion fails or event type is unknown.

• Supported A2A Event Types:

  • *a2a.Task: Converts via taskToEvent.

  • *a2a.Message: Converts via messageToEvent.

  • *a2a.TaskArtifactUpdateEvent: Converts artifact parts; marks as partial.

  • *a2a.TaskStatusUpdateEvent: Converts final or partial task status updates; marks partial or turn complete.

• Returns an error for unknown event types.

This function enables the client side of A2A communication to interpret remote agent events as local session events.

ToADKMetaKey(key string) string

Adds a prefix "a2a:" to a metadata key to differentiate A2A-related keys in session event custom metadata.

• Parameters:

  • key: The key string to prefix.

• Returns:

  • Prefixed key string, e.g., "a2a:task_id".

ToCustomMetadata(taskID a2a.TaskID, ctxID string) map[string]any

Creates a custom metadata map for a session event including the A2A task ID and context ID.

• Parameters:

  • taskID: The A2A task identifier.

  • ctxID: The A2A context identifier.

• Returns:

  • A map with keys customMetaTaskIDKey and customMetaContextIDKey mapping to string values.

This metadata is used to track task and context IDs throughout event processing and conversion.

GetA2ATaskInfo(event *session.Event) (a2a.TaskID, string)

Extracts the A2A task ID and context ID from a session event’s custom metadata, if present.

• Parameters:

  • event: The session event to inspect.

• Returns:

  • taskID: The extracted a2a.TaskID (empty if none).

  • contextID: The extracted context ID string (empty if none).

Conversion Helper Functions (all internal)

• messageToEvent(ctx agent.InvocationContext, msg *a2a.Message) (*session.Event, error)

  Converts an A2A message to a session event authored by the agent in the invocation context.

• artifactToEvent(ctx agent.InvocationContext, artifact *a2a.Artifact) (*session.Event, error)

  Converts an A2A artifact (with parts) to a session event.

• taskToEvent(ctx agent.InvocationContext, task *a2a.Task) (*session.Event, error)

  Converts an A2A task (including artifacts and status messages) to a session event. This function also detects long-running tool IDs and sets partial flags depending on the task state.

• finalTaskStatusUpdateToEvent(ctx agent.InvocationContext, update *a2a.TaskStatusUpdateEvent) (*session.Event, error)

  Converts a final task status update event to a session event, marking it as a completed turn.

• getLongRunningToolIDs(parts []a2a.Part, converted []*genai.Part) []string

  Scans parts for those marked as long-running tools via metadata and extracts their function call IDs for tracking.

• toGenAIRole(role a2a.MessageRole) genai.Role

  Maps A2A message roles (User or Agent) to the internal genai.Role enumeration.

• toEventActions(event a2a.Event) session.EventActions

  Extracts action flags (escalate, transfer_to_agent) from an A2A event’s metadata and returns them as a session.EventActions struct for inclusion in session events.

Important Implementation Details

• Role Mapping: The system distinguishes user versus agent authored messages to properly set roles in both ADK and A2A message models.

• Partial Event Handling: Some events, such as artifact updates or partial task status updates, are marked as partial (event.Partial = true) to indicate incremental or incomplete information. Final task status updates mark the event turn as complete.

• Long-Running Tool Identification: Parts flagged with metadata indicating long-running tools are detected and their function call IDs are tracked. This supports signaling input requirements in tasks.

• Custom Metadata Usage: Task and context IDs are stored in session event custom metadata using prefixed keys to maintain traceability of remote interactions.

• Error Handling: Functions return descriptive errors when required context is missing or unsupported event types are encountered.

• Action Flags Propagation: Actions such as escalation and agent transfer are propagated between session events and A2A messages through metadata, enabling remote agents to respond to control signals.

Interaction with Other System Components

• This file is part of the Remote Agent Communication (A2A) module, specifically supporting the Event Conversion and Processing subtopic.

• It interacts closely with:

  • The agent.InvocationContext interface (Agent Invocation Context) to obtain agent and invocation details for event attribution.

  • The session.Event model (Session Management) for representing local agent session interactions.

  • The a2a.Event and a2a.Message types from the A2A protocol (Remote Agent Communication (A2A)) for network communication.

  • Content part conversion utilities implemented in companion files (e.g., parts.go), which convert message parts between ADK’s genai.Part and A2A parts.

• The file supports remote agent invocation flows by converting outgoing session events to A2A messages, and by converting incoming A2A events back into session events for local processing.

• These conversions enable the Executor and Server components to interact with underlying agents seamlessly over the A2A protocol.

Diagram: Function and Conversion Flow

flowchart TD
subgraph ADK Session Events
SE[session.Event]
end
subgraph A2A Protocol Events
AM[a2a.Message]
AE[a2a.Event]
end
SE -->|EventToMessage| AM
AE -->|ToSessionEvent| SE
AM -.->|Metadata: Actions| AM
SE -.->|CustomMetadata: Task & Context IDs| SE
AM -->|Parts Conversion| AM
AE -->|Parts Conversion| SE

This diagram illustrates the bidirectional conversion between ADK session events and A2A protocol messages/events, highlighting the propagation of metadata and content parts.

Usage Patterns and Examples

• Creating a Remote Agent Event:

event := NewRemoteAgentEvent(ctx)

• Converting a session event to a message for sending:

msg, err := EventToMessage(event)
if err != nil {
    // handle error
}
// send msg over network

• Receiving an A2A event and converting it to a session event:

sessionEvent, err := ToSessionEvent(ctx, a2aEvent)
if err != nil {
    // handle error
}
// process sessionEvent

• Extracting A2A task info from a session event:

taskID, ctxID := GetA2ATaskInfo(sessionEvent)

References to Related Topics

• See Remote Agent Communication (A2A) for an overview of the A2A protocol and its role in inter-agent communication.

• Refer to Session Management for details on the internal session event model.

• Review Agent Invocation Context for the role of invocation context in event creation and attribution.

• Consult Event Conversion and Processing for the broader context of event translation and stream management in the system.

• The content part conversions invoked here rely on utilities discussed in Event Conversion and Processing and related files like parts.go.

This file is a critical component in the event translation layer, ensuring seamless interoperability between internal session state and the external A2A communication protocol.