parts.go

Overview

The parts.go source file provides the core functionality for converting message content parts between two distinct representations used within the system:

• The genai.Part representation, which is used internally by the ADK framework for AI message parts.

• The a2a.Part representation, which is part of the Agent-To-Agent (A2A) protocol for distributed multi-agent communication.

This conversion layer supports various content types including text, file attachments, function calls, function responses, executable code, and code execution results. It preserves semantic metadata such as long-running tool indications and ensures proper encoding/decoding of file bytes.

By handling these conversions, this file enables seamless interoperability between local ADK agents and remote agents communicating over the A2A protocol. It also facilitates the streaming and processing of complex message contents that may include executable code or function calls, crucial for advanced AI workflows.

Detailed Explanation of Functions

ToA2AParts

func ToA2AParts(parts []*genai.Part, longRunningToolIDs []string) ([]a2a.Part, error)

• Purpose: Converts a slice of genai.Part objects into their corresponding a2a.Part equivalents.

• Parameters:

  • parts: Slice of pointers to genai.Part representing the message parts to convert.

  • longRunningToolIDs: Slice of strings identifying tool IDs considered "long running" for metadata tagging.

• Returns:

  • A slice of a2a.Part containing the converted parts.

  • An error if any conversion fails.

• Behavior:

  • Iterates over each genai.Part.

  • If the part contains plain text, converts it to a2a.TextPart, optionally tagging with a "thought" metadata flag.

  • If the part contains either inline or file data, converts it using toA2AFilePart.

  • Otherwise, attempts to convert it as a data part (function call, function response, executable code, or code execution result) using toA2ADataPart.

• Usage Example:

  a2aParts, err := ToA2AParts(genaiParts, []string{"tool1", "tool2"})
  if err != nil {
      // handle error
  }
  // use a2aParts for A2A messaging
  

toA2AFilePart

func toA2AFilePart(v *genai.Part) (a2a.FilePart, error)

• Purpose: Converts a genai.Part that contains file data (either inline bytes or a file URI) into an a2a.FilePart.

• Parameters:

  • v: Pointer to a genai.Part expected to have either InlineData or FileData.

• Returns:

  • An a2a.FilePart with appropriately populated fields.

  • An error if the part is not a file part or if metadata conversion fails.

• Implementation Details:

  • If FileData is present, constructs an a2a.FilePart with a FileURI.

  • If InlineData is present, encodes the bytes as base64 and constructs an a2a.FilePart with FileBytes.

  • If video metadata is present, converts it to a generic map structure and attaches it to part metadata.

• Important: Proper base64 encoding is performed to safely transmit inline file bytes.

toA2ADataPart

func toA2ADataPart(part *genai.Part, longRunningToolIDs []string) (a2a.DataPart, error)

• Purpose: Converts a genai.Part representing structured data such as function calls, function responses, executable code, or code execution results into an a2a.DataPart.

• Parameters:

  • part: Pointer to the genai.Part to convert.

  • longRunningToolIDs: List of tool IDs marking long-running function calls.

• Returns:

  • An a2a.DataPart representing the converted content with appropriate metadata tags.

  • An error if conversion to map structure fails.

• Implementation Details:

  • Checks for presence of CodeExecutionResult, FunctionResponse, ExecutableCode, or FunctionCall.

  • Converts the found data structure into a generic map using converters.ToMapStructure.

  • Annotates the Metadata with a type key indicating the kind of data part.

  • For FunctionCall, also tags whether it is long-running based on the provided IDs.

  • If none of these fields are set, returns an empty data map.

ToGenAIParts

func ToGenAIParts(parts []a2a.Part) ([]*genai.Part, error)

• Purpose: Converts a slice of a2a.Part objects back into genai.Part equivalents.

• Parameters:

  • parts: Slice of a2a.Part interfaces.

• Returns:

  • Slice of pointers to genai.Part.

  • An error if any part conversion fails or an unknown part type is encountered.

• Behavior:

  • Switches on the dynamic type of each a2a.Part.

  • Converts a2a.TextPart to text genai parts, preserving "thought" metadata.

  • Converts a2a.DataPart using toGenAIDataPart.

  • Converts a2a.FilePart using toGenAIFilePart.

  • Returns error if a part type is unknown.

toGenAIFilePart

func toGenAIFilePart(part a2a.FilePart) (*genai.Part, error)

• Purpose: Converts an a2a.FilePart back into a genai.Part with either inline or file data.

• Parameters:

  • part: The a2a.FilePart to convert.

• Returns:

  • Pointer to a genai.Part representing the file.

  • An error if decoding or type assertion fails.

• Implementation Details:

  • If the file content is a2a.FileBytes, decodes base64 bytes back to raw bytes and creates genai.Blob.

  • If the file content is a2a.FileURI, creates genai.FileData with URI.

  • Returns error on unknown file content types.

toGenAIDataPart

func toGenAIDataPart(part a2a.DataPart) (*genai.Part, error)

• Purpose: Converts an a2a.DataPart into the appropriate genai.Part based on metadata type.

• Parameters:

  • part: The a2a.DataPart to convert.

• Returns:

  • Pointer to a genai.Part with the proper structured data field set.

  • An error if JSON marshal/unmarshal fails or an unknown type is encountered.

• Implementation Details:

  • Checks the metadata type key.

  • Serializes the data map to JSON bytes and deserializes into the corresponding genai struct (CodeExecutionResult, FunctionCall, ExecutableCode, or FunctionResponse).

  • Defaults to returning plain text part if metadata type is missing or unrecognized.

toGenAITextPart

func toGenAITextPart(part a2a.DataPart) (*genai.Part, error)

• Purpose: Converts an a2a.DataPart without metadata into a genai.Part containing JSON-encoded text.

• Parameters:

  • part: The a2a.DataPart to convert.

• Returns:

  • Pointer to a genai.Part with the JSON string in the Text field.

  • An error if JSON marshaling fails.

toGenAIContent

func toGenAIContent(msg *a2a.Message) (*genai.Content, error)

• Purpose: Converts an a2a.Message into a genai.Content by converting its parts.

• Parameters:

  • msg: Pointer to an a2a.Message.

• Returns:

  • Pointer to a genai.Content with role set to genai.RoleUser.

  • An error if part conversion fails.

• Usage: Used internally to bridge A2A messages into the genai representation for agent execution.

Important Implementation Details and Algorithms

• Conversion functions rely heavily on the converters.ToMapStructure utility to convert complex Go structs into generic map[string]any representations suitable for JSON serialization and metadata embedding.

• Base64 encoding/decoding is used to safely transmit raw file bytes inline in the message parts.

• Metadata keys are normalized via ToA2AMetaKey function to ensure consistency in metadata tagging.

• Long-running tool identification is supported by tagging function calls with a boolean metadata flag based on a configured list of tool IDs.

• Error handling is consistent: conversion failures yield descriptive errors allowing upstream callers to respond appropriately.

• The conversion routines distinguish between different content types by inspecting the presence of specific fields (FunctionCall, ExecutableCode, etc.) and metadata.

Interaction with Other Parts of the System

• This file is a core utility within the Remote Agent Communication (A2A) module (80565) that handles the translation of message parts between the internal ADK representation (genai.Part) and the A2A protocol representation (a2a.Part).

• It is closely integrated with the Event Conversion and Processing subtopic (80591), which converts entire session events and messages by leveraging these part conversion functions.

• The ToA2AParts and ToGenAIParts functions are used by the A2A Agent Implementation (80586) to marshal messages sent over the network and to interpret messages received from remote agents.

• This file also interacts with the Executor and Server (80589) by enabling the server executor to convert incoming A2A messages to genai content for agent execution and to convert agent responses back into A2A parts.

• The converters package used here provides generic struct-to-map conversion utilities shared across the system for serializing complex data types.

• This conversion layer supports the correct propagation of metadata flags (e.g., thought markers, long-running tools) needed for advanced agent workflows and task lifecycle management.

Visual Diagram

flowchart TD
subgraph GenAI_Parts [genai.Part]
genText[Text Part]
genFileInline[Inline File Data]
genFileURI[File URI Data]
genFuncCall[Function Call]
genFuncResp[Function Response]
genExecCode[Executable Code]
genCodeExecRes[Code Execution Result]
end
subgraph Conversion_Functions
ToA2APartsFunc[ToA2AParts]
toA2AFilePartFunc[toA2AFilePart]
toA2ADataPartFunc[toA2ADataPart]
ToGenAIPartsFunc[ToGenAIParts]
toGenAIFilePartFunc[toGenAIFilePart]
toGenAIDataPartFunc[toGenAIDataPart]
end
subgraph A2A_Parts [a2a.Part]
a2aText[a2a.TextPart]
a2aFile[a2a.FilePart]
a2aData[a2a.DataPart]
end
genText -->|ToA2AParts| ToA2APartsFunc
genFileInline -->|ToA2AParts| ToA2APartsFunc
genFileURI -->|ToA2AParts| ToA2APartsFunc
genFuncCall -->|ToA2AParts| ToA2APartsFunc
genFuncResp -->|ToA2AParts| ToA2APartsFunc
genExecCode -->|ToA2AParts| ToA2APartsFunc
genCodeExecRes -->|ToA2AParts| ToA2APartsFunc
ToA2APartsFunc -->|calls| toA2AFilePartFunc
ToA2APartsFunc -->|calls| toA2ADataPartFunc
toA2AFilePartFunc --> a2aFile
toA2ADataPartFunc --> a2aData
ToA2APartsFunc --> a2aText
a2aText -->|ToGenAIParts| ToGenAIPartsFunc
a2aFile -->|ToGenAIParts| ToGenAIPartsFunc
a2aData -->|ToGenAIParts| ToGenAIPartsFunc
ToGenAIPartsFunc -->|calls| toGenAIFilePartFunc
ToGenAIPartsFunc -->|calls| toGenAIDataPartFunc
toGenAIFilePartFunc --> genFileInline
toGenAIFilePartFunc --> genFileURI
toGenAIDataPartFunc --> genFuncCall
toGenAIDataPartFunc --> genFuncResp
toGenAIDataPartFunc --> genExecCode
toGenAIDataPartFunc --> genCodeExecRes
toGenAIDataPartFunc --> genText

Summary

This file is essential for bridging the internal and external message part representations, enabling the system to:

• Serialize and deserialize complex AI message content,

• Preserve rich metadata for function calls and long-running tools,

• Handle file attachments safely via base64 encoding or URIs,

• Support executable code and function call semantics within messages.

It operates at the heart of the agent communication stack, enabling flexible remote agent invocation, streaming, and response processing as described in the broader Remote Agent Communication (A2A) topic and the related Event Conversion and Processing subtopic.