a2a.helpers package

Submodules

• a2a.helpers.agent_card module
  • display_agent_card()
• a2a.helpers.proto_helpers module
  • get_artifact_text()
  • get_data_parts()
  • get_message_text()
  • get_raw_parts()
  • get_stream_response_text()
  • get_text_parts()
  • get_url_parts()
  • new_artifact()
  • new_data_artifact()
  • new_data_artifact_update_event()
  • new_data_message()
  • new_data_part()
  • new_message()
  • new_raw_artifact()
  • new_raw_artifact_update_event()
  • new_raw_message()
  • new_raw_part()
  • new_task()
  • new_task_from_user_message()
  • new_text_artifact()
  • new_text_artifact_update_event()
  • new_text_message()
  • new_text_part()
  • new_text_status_update_event()
  • new_url_artifact()
  • new_url_artifact_update_event()
  • new_url_message()
  • new_url_part()

Module contents

Helper functions for the A2A Python SDK.

a2a.helpers.display_agent_card(card: AgentCard) → None

Print a human-readable summary of an AgentCard to stdout.

Parameters:

card – The AgentCard proto message to display.

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

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

a2a.helpers.get_data_parts(parts: Sequence[Part]) → list[Any]

Extracts structured data from all data Parts.

Each returned element is the Python object obtained by converting the google.protobuf.Value back via MessageToDict.

Parameters:

parts – A sequence of Part objects.

Returns:

A list of deserialized Python objects from any data Parts found.

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

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

a2a.helpers.get_raw_parts(parts: Sequence[Part]) → list[bytes]

Extracts raw bytes content from all raw Parts.

Parameters:

parts – A sequence of Part objects.

Returns:

A list of bytes from any raw Parts found.

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

Extracts text content from a StreamResponse.

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

Extracts text content from all text Parts.

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

Extracts URL strings from all URL Parts.

Parameters:

parts – A sequence of Part objects.

Returns:

A list of URL strings from any URL Parts found.

a2a.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.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.new_data_artifact_update_event(task_id: str, context_id: str, name: str, data: Any, media_type: str | None = None, append: bool = False, last_chunk: bool = False, artifact_id: str | None = None) → TaskArtifactUpdateEvent

Creates a TaskArtifactUpdateEvent with a single data artifact.

Parameters:

• task_id – The task ID.

• context_id – The context ID.

• 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.

• append – Whether to append to the existing artifact.

• last_chunk – Whether this is the last chunk.

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

Returns:

A TaskArtifactUpdateEvent with a single data artifact.

a2a.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 0x7fd3bfac2250> = 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.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.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 0x7fd3bfac2250> = 2) → Message

Creates a new message containing a list of Parts.

a2a.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.new_raw_artifact_update_event(task_id: str, context_id: str, name: str, raw: bytes, media_type: str | None = None, filename: str | None = None, append: bool = False, last_chunk: bool = False, artifact_id: str | None = None) → TaskArtifactUpdateEvent

Creates a TaskArtifactUpdateEvent with a single raw bytes artifact.

Parameters:

• task_id – The task ID.

• context_id – The context ID.

• name – The name of the artifact.

• raw – The raw bytes content.

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

• filename – Optional filename.

• append – Whether to append to the existing artifact.

• last_chunk – Whether this is the last chunk.

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

Returns:

A TaskArtifactUpdateEvent with a single raw artifact.

a2a.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 0x7fd3bfac2250> = 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.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.new_task(task_id: str, context_id: str, state: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7fd3bfac2150>, artifacts: list[Artifact] | None = None, history: list[Message] | None = None) → Task

Creates a Task object with a specified status.

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

Creates a new Task object from an initial user message.

a2a.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.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.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 0x7fd3bfac2250> = 2) → Message

Creates a new message containing a single text Part.

a2a.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.new_text_status_update_event(task_id: str, context_id: str, state: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7fd3bfac2150>, text: str) → TaskStatusUpdateEvent

Creates a TaskStatusUpdateEvent with a single text message.

a2a.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.new_url_artifact_update_event(task_id: str, context_id: str, name: str, url: str, media_type: str | None = None, filename: str | None = None, append: bool = False, last_chunk: bool = False, artifact_id: str | None = None) → TaskArtifactUpdateEvent

Creates a TaskArtifactUpdateEvent with a single URL artifact.

Parameters:

• task_id – The task ID.

• context_id – The context ID.

• 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.

• append – Whether to append to the existing artifact.

• last_chunk – Whether this is the last chunk.

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

Returns:

A TaskArtifactUpdateEvent with a single URL artifact.

a2a.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 0x7fd3bfac2250> = 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.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.