Event Conversion and Processing

Purpose

Within the broader scope of the Remote Agent Communication (A2A) topic, the Event Conversion and Processing subtopic addresses the critical need to translate and manage event data exchanged between the ADK session model and the A2A protocol model. This subtopic solves two main problems:

• Interoperability: It converts events from the ADK internal session event format into A2A protocol messages and vice versa, enabling seamless communication between local agents and remote agents over gRPC/HTTP.

• Event Stream Processing: It processes streams of session events, especially those containing LLM responses, partial outputs, tool invocations, and task status updates, to produce coherent A2A task artifact updates and terminal task status events.

This functionality is essential to support distributed multi-agent workflows where agents interact remotely, translate complex event data structures, and maintain task status consistency.

Functionality

Conversion Between ADK Session Events and A2A Events

This subtopic provides bidirectional conversion functions that map between the ADK session.Event and A2A a2a.Event types. This includes:

• Session Event → A2A Message: The EventToMessage function converts an ADK session event into an A2A message, translating content parts and author roles. It also transfers action metadata such as escalation or agent transfer requests.

• A2A Event → Session Event: The ToSessionEvent function converts various A2A event types (e.g., Task, Message, TaskArtifactUpdateEvent, TaskStatusUpdateEvent) into ADK session events authored by the current invocation context's agent. It enriches session events with custom metadata like task and context IDs.

• Parts Conversion: Conversion between ADK genai.Part structures and A2A a2a.Part structures for message and artifact content is handled by ToA2AParts and ToGenAIParts. These functions manage complex data such as function calls, executable code, and file parts with encoding/decoding logic.

The conversion ensures that semantic information (e.g., which function calls are long-running) is preserved using metadata keys, enabling correct handling downstream.

Processing Event Streams for Task Status

The eventProcessor type encapsulates logic to process a sequence of ADK session events, typically generated as an agent executes and produces incremental output. Key features include:

• Handling LLM Responses: It inspects the LLMResponse within each event to extract content parts or error codes, converting them into A2A artifact update events.

• Tracking Terminal Conditions: The processor tracks whether the task has failed, requires input, or completed successfully, postponing terminal event emission until all partial content is processed.

• Long-running Tool Calls: It detects partial function calls flagged as long-running tools and generates input_required task states accordingly.

• Action Metadata Propagation: Action flags such as escalate or transfer_to_agent are accumulated and embedded into terminal event metadata to ensure remote agents can act on these signals.

• Artifact Event Management: The processor manages artifact IDs and whether updates should append or finalize the artifact stream, ensuring that multi-part responses are correctly represented.

This processing enables the system to generate consistent A2A task status updates from incremental ADK session events, supporting smooth remote agent interactions and task lifecycle management.

Integration

• With Remote Agent Communication (A2A): This subtopic is a core enabler for the A2A protocol implementation, translating between ADK's internal event model and the standardized A2A event types used over the network.

• With Session Management: It relies on session events generated and stored by the session subsystem, converting session state and event histories into A2A events to represent remote agent task progress.

• With Agent Execution Runner: The event processor's outputs are used by the runner to communicate incremental agent outputs and final statuses over A2A, supporting remote agent execution flows.

• With Agent Workflow Management: Workflow agents produce session events that this subtopic processes to maintain accurate remote task status and event translation.

• With Telemetry and Observability: While not directly managing telemetry, the event conversion and processing layer ensures that event metadata (e.g., escalate flags) are propagated properly, facilitating observability in distributed multi-agent interactions.

Code Interaction Highlights

• Event Conversion Example:

// Converts an ADK session event to an A2A message.
func EventToMessage(event *session.Event) (*a2a.Message, error) {
    parts, err := ToA2AParts(event.Content.Parts, event.LongRunningToolIDs)
    if err != nil {
        return nil, err
    }
    var role a2a.MessageRole
    if event.Author == "user" {
        role = a2a.MessageRoleUser
    } else {
        role = a2a.MessageRoleAgent
    }
    msg := a2a.NewMessage(role, parts...)
    msg.Metadata = setActionsMeta(msg.Metadata, event.Actions)
    return msg, nil
}

• Event Stream Processing Core:

func (p *eventProcessor) process(_ context.Context, event *session.Event) (*a2a.TaskArtifactUpdateEvent, error) {
    p.updateTerminalActions(event)
    resp := event.LLMResponse
    if resp.ErrorCode != "" {
        // Mark failure and prepare terminal event
        ...
    }
    if resp.Content == nil || len(resp.Content.Parts) == 0 {
        return nil, nil
    }
    if isInputRequired(event, resp.Content.Parts) {
        // Handle long-running tool input requirement
        ...
    }
    parts, err := ToA2AParts(resp.Content.Parts, event.LongRunningToolIDs)
    ...
    return a2a.NewArtifactEventOrUpdate(p.reqCtx, p.responseID, parts...), nil
}

• Round-trip Conversion Testing: The subtopic includes extensive tests verifying the correctness of conversions and processing logic, ensuring that all event types and edge cases (e.g., partial updates, failures) are handled as expected.

Diagram

sequenceDiagram
participant ADK as ADK Session
participant EP as EventProcessor
participant A2A as A2A Protocol
ADK->>EP: session.Event stream (includes LLMResponse, actions)
EP->>A2A: Convert to a2a.TaskArtifactUpdateEvent
EP->>EP: Track terminalActions (escalate, transfer)
EP->>A2A: Emit terminal a2a.TaskStatusUpdateEvent when complete
A2A->>EP: Incoming a2a.Event (Task, Message, ArtifactUpdate)
EP->>ADK: Convert to session.Event with custom metadata

This diagram illustrates the bidirectional flow where session events from the ADK are processed and converted into A2A events for remote communication, and incoming A2A events are translated back into session events for local consumption.

The Event Conversion and Processing subtopic thus forms the essential bridge and event stream manager within the distributed agent communication infrastructure, ensuring coherent and interoperable task status representation across the ADK and A2A layers. It complements other subtopics like A2A Agent Implementation by providing the translation and event flow logic necessary for remote agent interactions.