a2a.helpers.proto_helpers module

Unified helper functions for creating and handling A2A types.

a2a.helpers.proto_helpers.get_artifact_text(artifact: Artifact, delimiter: str = '\n') → str

Extracts and joins all text content from an Artifact’s parts.

a2a.helpers.proto_helpers.get_message_text(message: Message, delimiter: str = '\n') → str

Extracts and joins all text content from a Message’s parts.

a2a.helpers.proto_helpers.get_stream_response_text(response: StreamResponse, delimiter: str = '\n') → str

Extracts text content from a StreamResponse.

a2a.helpers.proto_helpers.get_text_parts(parts: Sequence[Part]) → list[str]

Extracts text content from all text Parts.

a2a.helpers.proto_helpers.new_artifact(parts: list[Part], name: str, description: str | None = None, artifact_id: str | None = None) → Artifact

Creates a new Artifact object.

a2a.helpers.proto_helpers.new_data_artifact(name: str, data: Any, media_type: str | None = None, description: str | None = None, artifact_id: str | None = None) → Artifact

Creates a new Artifact object containing only a single data Part.

Parameters:

  • name – The name of the artifact.

  • data – JSON-serializable data to embed (dict, list, str, etc.).

  • media_type – Optional MIME type of the part content (e.g., “text/plain”, “application/json”, “image/png”).

  • description – Optional description.

  • artifact_id – Optional artifact ID (auto-generated if not provided).

Returns:

An Artifact with a single data Part.

a2a.helpers.proto_helpers.new_data_message(data: Any, media_type: str | None = None, context_id: str | None = None, task_id: str | None = None, role: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7f5838743550> = 2) → Message

Creates a new message containing a single data Part.

Parameters:

  • data – JSON-serializable data to embed (dict, list, str, etc.).

  • media_type – Optional MIME type of the part content (e.g., “text/plain”, “application/json”, “image/png”).

  • context_id – Optional context ID.

  • task_id – Optional task ID.

  • role – The role of the message sender (default: ROLE_AGENT).

Returns:

A Message with a single data Part.

a2a.helpers.proto_helpers.new_data_part(data: Any, media_type: str | None = None) → Part

Creates a Part with structured data (google.protobuf.Value).

Parameters:

  • data – JSON-serializable data to embed (dict, list, str, etc.).

  • media_type – Optional MIME type of the part content (e.g., “text/plain”, “application/json”, “image/png”).

Returns:

A Part with the data field set.

a2a.helpers.proto_helpers.new_message(parts: list[~a2a_pb2.Part], context_id: str | None = None, task_id: str | None = None, role: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7f5838743550> = 2) → Message

Creates a new message containing a list of Parts.

a2a.helpers.proto_helpers.new_raw_artifact(name: str, raw: bytes, media_type: str | None = None, filename: str | None = None, description: str | None = None, artifact_id: str | None = None) → Artifact

Creates a new Artifact object containing only a single raw bytes Part.

Parameters:

  • name – The name of the artifact.

  • raw – The raw bytes content.

  • media_type – Optional MIME type (e.g. ‘image/png’).

  • filename – Optional filename.

  • description – Optional description.

  • artifact_id – Optional artifact ID (auto-generated if not provided).

Returns:

An Artifact with a single raw Part.

a2a.helpers.proto_helpers.new_raw_message(raw: bytes, media_type: str | None = None, filename: str | None = None, context_id: str | None = None, task_id: str | None = None, role: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7f5838743550> = 2) → Message

Creates a new message containing a single raw bytes Part.

Parameters:

  • raw – The raw bytes content.

  • media_type – Optional MIME type (e.g. ‘image/png’).

  • filename – Optional filename.

  • context_id – Optional context ID.

  • task_id – Optional task ID.

  • role – The role of the message sender (default: ROLE_AGENT).

Returns:

A Message with a single raw Part.

a2a.helpers.proto_helpers.new_raw_part(raw: bytes, media_type: str | None = None, filename: str | None = None) → Part

Creates a Part with raw bytes content.

Parameters:

  • raw – The raw bytes content.

  • media_type – Optional MIME type (e.g. ‘image/png’).

  • filename – Optional filename.

Returns:

A Part with the raw field set.

a2a.helpers.proto_helpers.new_task(task_id: str, context_id: str, state: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7f5838740650>, artifacts: list[Artifact] | None = None, history: list[Message] | None = None) → Task

Creates a Task object with a specified status.

a2a.helpers.proto_helpers.new_task_from_user_message(user_message: Message) → Task

Creates a new Task object from an initial user message.

a2a.helpers.proto_helpers.new_text_artifact(name: str, text: str, media_type: str | None = None, description: str | None = None, artifact_id: str | None = None) → Artifact

Creates a new Artifact object containing only a single text Part.

a2a.helpers.proto_helpers.new_text_artifact_update_event(task_id: str, context_id: str, name: str, text: str, append: bool = False, last_chunk: bool = False, artifact_id: str | None = None) → TaskArtifactUpdateEvent

Creates a TaskArtifactUpdateEvent with a single text artifact.

a2a.helpers.proto_helpers.new_text_message(text: str, media_type: str | None = None, context_id: str | None = None, task_id: str | None = None, role: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7f5838743550> = 2) → Message

Creates a new message containing a single text Part.

a2a.helpers.proto_helpers.new_text_part(text: str, media_type: str | None = None) → Part

Creates a Part with text content.

Parameters:

  • text – The text content.

  • media_type – Optional MIME type (e.g. ‘text/plain’, ‘text/markdown’).

Returns:

A Part with the text field set.

a2a.helpers.proto_helpers.new_text_status_update_event(task_id: str, context_id: str, state: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7f5838740650>, text: str) → TaskStatusUpdateEvent

Creates a TaskStatusUpdateEvent with a single text message.

a2a.helpers.proto_helpers.new_url_artifact(name: str, url: str, media_type: str | None = None, filename: str | None = None, description: str | None = None, artifact_id: str | None = None) → Artifact

Creates a new Artifact object containing only a single URL Part.

Parameters:

  • name – The name of the artifact.

  • url – The URL pointing to the file content.

  • media_type – Optional MIME type (e.g. ‘image/png’).

  • filename – Optional filename.

  • description – Optional description.

  • artifact_id – Optional artifact ID (auto-generated if not provided).

Returns:

An Artifact with a single URL Part.

a2a.helpers.proto_helpers.new_url_message(url: str, media_type: str | None = None, filename: str | None = None, context_id: str | None = None, task_id: str | None = None, role: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7f5838743550> = 2) → Message

Creates a new message containing a single URL Part.

Parameters:

  • url – The URL pointing to the file content.

  • media_type – Optional MIME type (e.g. ‘image/png’).

  • filename – Optional filename.

  • context_id – Optional context ID.

  • task_id – Optional task ID.

  • role – The role of the message sender (default: ROLE_AGENT).

Returns:

A Message with a single URL Part.

a2a.helpers.proto_helpers.new_url_part(url: str, media_type: str | None = None, filename: str | None = None) → Part

Creates a Part with a URL pointing to file content.

Parameters:

  • url – The URL to the file content.

  • media_type – Optional MIME type (e.g. ‘image/png’).

  • filename – Optional filename.

Returns:

A Part with the url field set.