Including None type hints and overall annotation consistency improvements

[rodrigobr-msft]

This pull request modernizes the type annotations throughout the microsoft-agents-activity library by replacing most uses of Optional[T] and List[T] with the more concise T | None and list[T] syntax introduced in Python 3.10. It also removes now-unnecessary imports of Optional and List, and updates function signatures and class attributes accordingly. These changes improve code readability and consistency, and help standardize type usage across the codebase.

Type annotation modernization:

• Replaced Optional[T] with T | None and List[T] with list[T] across all relevant files, including activity.py, card_action.py, channel_account.py, conversation_account.py, conversation_reference.py, channel_id.py, channel_adapter_protocol.py, and various entity classes. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

• Updated method signatures and property return types to use the new | None and list[] syntax, e.g., def create_reply(self, text: str | None = None, ...) and def get_agentic_instance_id(self) -> str | None. [1] [2] [3] [4] [5]

Import cleanup:

• Removed unused imports of Optional and List from all affected files, streamlining the import sections. [1] [2] [3] [4] [5] [6] [7] [8] [9]

Consistency improvements:

• Ensured all class attributes and computed fields use the updated type annotations, such as in ChannelAccount, ConversationAccount, ConversationReference, and entity classes. [1] [2] [3] [4] [5]

• Updated method implementations to use the new types, including checks like if value is not None instead of if value. [1] [2]

General code modernization:

• Applied the new type hinting style consistently throughout the codebase, which will make the code more maintainable and easier to follow for developers familiar with modern Python. (all references above)

[Copilot]

Pull request overview

This PR modernizes type annotations across the Python libraries by replacing typing.Optional / typing.Union / typing.List-style hints with Python 3.10+ PEP 604 unions (X | None) and built-in generics (list[...], dict[...]), while removing now-unneeded typing imports.

Changes:

• Replace Optional[...] / Union[..., None] with ... | None in function signatures, protocols, and dataclasses.
• Replace List[...] / Dict[...] / Tuple[...] with list[...] / dict[...] / tuple[...].
• Clean up typing imports after the annotation updates.

Reviewed changes

Copilot reviewed 144 out of 144 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
libraries/microsoft-agents-storage-cosmos/microsoft_agents/storage/cosmos/cosmos_db_storage_config.py	Updates optional config typing to `
libraries/microsoft-agents-storage-cosmos/microsoft_agents/storage/cosmos/cosmos_db_storage.py	Updates storage read-item typing to PEP 604 unions.
libraries/microsoft-agents-storage-blob/microsoft_agents/storage/blob/blob_storage_config.py	Updates credential typing to `AsyncTokenCredential
libraries/microsoft-agents-storage-blob/microsoft_agents/storage/blob/blob_storage.py	Updates storage read-item typing to PEP 604 unions.
libraries/microsoft-agents-hosting-teams/microsoft_agents/hosting/teams/teams_info.py	Replaces Optional/List/Tuple typing with PEP 604 + built-in generics.
libraries/microsoft-agents-hosting-teams/microsoft_agents/hosting/teams/teams_activity_handler.py	Replaces List[...] with list[...] in Teams handler hooks.
libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/cloud_adapter.py	Updates adapter optional deps and process() return type to `Response
libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/agent_http_adapter.py	Updates protocol method return type to `Response
libraries/microsoft-agents-hosting-fastapi/microsoft_agents/hosting/fastapi/_start_agent_process.py	Updates return type to `Response
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/turn_context.py	Updates optional params/returns to PEP 604 unions and refactors trace signature formatting.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript_store.py	Updates continuation token typing to `str
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript_memory_store.py	Updates continuation token typing to `str
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript_logger.py	Updates generics and list/optional typing to PEP 604 + built-in generics.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/transcript_file_store.py	Updates container types and optionals to PEP 604 + built-in generics.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/storage.py	Updates Storage protocol and gather typing to PEP 604 + built-in generics.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/storage/memory_storage.py	Updates target_cls typing to `StoreItemT
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/state/state_property_accessor.py	Updates accessor default/factory typing to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/state/agent_state.py	Updates internal state typing to built-in generics and PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/rest_channel_service_client_factory.py	Updates optional scopes to `list[str]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/message_factory.py	Updates optional text/speak/input_hint typing to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/http/_http_response.py	Updates HttpResponse field typing to PEP 604 unions + built-in generics.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/http/_http_request_protocol.py	Updates protocol types to built-in generics and PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/http/_http_adapter_base.py	Updates optional dependencies to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/http/_channel_service_routes.py	Updates serialize_model input typing to `AgentsModel
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/connector/user_token_base.py	Updates optional params (channel_id, code, etc.) to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/connector/mcs/mcs_connector_client.py	Updates optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/connector/conversations_base.py	Updates optional paging params to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/connector/client/user_token_client.py	Updates optional params and bodies to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/connector/client/connector_client.py	Updates paging params to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/connector/attachments_base.py	Updates optional attachment stream return type to `AsyncIterator[bytes]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/client/http_agent_channel.py	Updates optional response body type to `type[...]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/client/channels_configuration.py	Updates optional init args to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/client/channel_protocol.py	Updates optional response body type to `type[...]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/channel_service_client_factory_base.py	Updates optional scopes type to `list[str]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/channel_service_adapter.py	Updates docstrings/locals and optional types to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/channel_api_handler_protocol.py	Updates paging params typing to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/channel_adapter.py	Updates list/optional types to built-in generics + PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/claims_identity.py	Updates optional auth fields and return types to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/anonymous_token_provider.py	Updates optional token returns to `str
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/access_token_provider_base.py	Updates optional token returns to `str
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/typing_indicator.py	Updates optional task typing to `asyncio.Task[None]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/streaming/streaming_response.py	Updates internal optional/list typing to PEP 604 + built-in generics.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/streaming/citation_util.py	Updates citation list typing and return type to `list[...]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/streaming/citation.py	Updates Citation optional fields to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/state/turn_state.py	Updates optional factory and tuple typing to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/state/temp_state.py	Updates dict/list/optional typing to built-in generics + PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/state/state.py	Updates decorator overload typing and state API optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/proactive_options.py	Updates optional storage typing to `Storage
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/proactive.py	Updates return/param optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/create_conversation_options.py	Updates optional dataclass fields to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/conversation_reference_builder.py	Updates builder optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/conversation_builder.py	Updates builder optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/conversation.py	Updates optional identity typing to `ClaimsIdentity
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/authorization.py	Updates handler optionals and callback typing to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/auth_handler.py	Updates optional scopes typing to `list[str]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/_sign_in_state.py	Updates optional continuation activity typing to `Activity
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/_sign_in_response.py	Updates optional token_response typing to `TokenResponse
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/_handlers/connector_user_authorization.py	Updates handler optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/_handlers/agentic_user_authorization.py	Updates handler optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/_handlers/_user_authorization.py	Updates handler method optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/oauth/_handlers/_authorization_handler.py	Updates handler optionals to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/input_file.py	Updates optional/list typing to PEP 604 + built-in generics.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/app_options.py	Updates dataclass optionals and lists to PEP 604 + built-in generics.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/agent_application.py	Updates optionals and union-typed parameters to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/_routes/_route.py	Updates optional auth_handlers typing to `list[str]
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/activity_handler.py	Updates optional invoke response typing and body param typing to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/_oauth/_oauth_flow.py	Updates optional token/sign-in resource typing to PEP 604 unions.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/_oauth/_flow_storage_client.py	Updates optional cache_class and flow state return typing to `
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/_oauth/_flow_state.py	Updates optional continuation activity to `Activity
libraries/microsoft-agents-hosting-aiohttp/microsoft_agents/hosting/aiohttp/cloud_adapter.py	Updates optional deps and process() return type to `Response
libraries/microsoft-agents-hosting-aiohttp/microsoft_agents/hosting/aiohttp/agent_http_adapter.py	Updates protocol method return type to `Response
libraries/microsoft-agents-hosting-aiohttp/microsoft_agents/hosting/aiohttp/_start_agent_process.py	Updates return type to `Response
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/subscribe_event.py	Updates optional event_id typing to `str
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/start_request.py	Updates optional Pydantic fields to `str
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/power_platform_environment.py	Updates optional URL/IDs typing to PEP 604 unions.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/direct_to_engine_connection_settings_protocol.py	Updates protocol optionals to PEP 604 unions.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/copilot_client_protocol.py	Updates optional conversation/event IDs typing to `
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/copilot_client.py	Updates optional conversation/event IDs typing to `
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/connection_settings.py	Updates optionals and return dict typing to built-in generics + PEP 604 unions.
libraries/microsoft-agents-authentication-msal/microsoft_agents/authentication/msal/msal_connection_manager.py	Updates internal mapping/list typing to built-in generics + PEP 604 unions.
libraries/microsoft-agents-authentication-msal/microsoft_agents/authentication/msal/msal_auth.py	Updates optional URI and token return typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/turn_context_protocol.py	Updates protocol optionals and list typing to built-in generics + PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/token_status.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/token_response.py	Updates optional return typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/token_exchange_state.py	Updates optional relates_to typing to PEP 604 union.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/teams_paged_members_result.py	Updates members type to list[...] (but still defaults to None).
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/teams_channel_data.py	Updates on_behalf_of type to list[...] (but still defaults to None).
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/task_module_request_context.py	Updates optional theme typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/task_module_request.py	Updates data/context/tab typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/task_module_message_response.py	Updates optional value typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/task_module_continue_response.py	Updates optional value typing to `TaskModuleTaskInfo
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/targeted_meeting_notification_value.py	Updates recipients/surfaces type to list[...] (but still defaults to None).
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/tab_suggested_actions.py	Updates actions type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/tab_response_cards.py	Updates cards type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_view_action.py	Updates optional target typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_text_input.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_section.py	Updates optional fields and list optionals to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_open_uri.py	Updates targets type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_multichoice_input.py	Updates optional fields and choices list typing.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_input_base.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_image.py	Updates optional title typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_http_post.py	Updates optional body typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card_action_card.py	Updates inputs/actions type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/o365_connector_card.py	Updates optional fields and optional list typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/notification_info.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/messaging_extension_suggested_action.py	Updates actions type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/messaging_extension_result.py	Updates attachments and other optionals to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/messaging_extension_response.py	Updates optional compose_extension/cache_info typing.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/messaging_extension_query.py	Updates parameters/query_options typing.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/messaging_extension_attachment.py	Updates optional name/thumbnail_url typing.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/messaging_extension_action.py	Updates bot_activity_preview type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/message_actions_payload_user.py	Updates annotated optional union typing for constrained strings.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/message_actions_payload_reaction.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/message_actions_payload_mention.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/message_actions_payload_from.py	Updates optional nested model typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/message_actions_payload_attachment.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/message_actions_payload_app.py	Updates annotated optional union typing for constrained strings.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/message_actions_payload.py	Updates attachments/mentions/reactions list typing.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/meeting_start_event_details.py	Removes unused Optional import (typing cleanup).
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/meeting_participants_event_details.py	Updates members type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/meeting_participant_info.py	Removes unused Optional import (typing cleanup).
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/meeting_notification_response.py	Updates recipients_failure_info type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/meeting_notification_channel_data.py	Updates on_behalf_of_list type to list[...].
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/meeting_event_details.py	Removes unused Optional import (typing cleanup).
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/meeting_end_event_details.py	Removes unused Optional import (typing cleanup).
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/file_info_card.py	Updates optional etag typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/file_download_info.py	Updates optional etag typing to `str
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/file_consent_card_response.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/file_consent_card.py	Updates optional size_in_bytes typing to `int
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/conversation_list.py	Updates conversations list typing to built-in generics.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/channel_info.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/cache_info.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/batch_operation_state_response.py	Updates optional retry_after typing to `datetime
libraries/microsoft-agents-activity/microsoft_agents/activity/teams/app_based_link_query.py	Updates optional url/state typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/oauth_card.py	Updates optional token_exchange_resource typing to `
libraries/microsoft-agents-activity/microsoft_agents/activity/entity/ai_entity.py	Updates optionals and list typing to PEP 604 + built-in generics.
libraries/microsoft-agents-activity/microsoft_agents/activity/conversation_reference.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/conversation_account.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/channel_id.py	Updates optional args and properties to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/channel_adapter_protocol.py	Updates optional callback and list typing to PEP 604 + built-in generics.
libraries/microsoft-agents-activity/microsoft_agents/activity/channel_account.py	Updates optional fields typing to PEP 604 unions.
libraries/microsoft-agents-activity/microsoft_agents/activity/card_action.py	Updates optional channel_data typing to `object
libraries/microsoft-agents-activity/microsoft_agents/activity/activity.py	Updates optionals to PEP 604 unions and improves falsy-value handling in trace helpers.
libraries/microsoft-agents-activity/microsoft_agents/activity/_channel_id_field_mixin.py	Updates computed field typing to `ChannelId

Comments suppressed due to low confidence (2)

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/state/agent_state.py:25

• state defaults to None but the parameter is annotated as a non-optional dict[...]. This is inconsistent for type checkers and makes the API contract unclear. Consider changing the parameter type to dict[str, StoreItem | dict] | None (or default to {} and keep it non-optional).
  libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/http/_channel_service_routes.py:54
• serialize_model is annotated as returning dict, but the implementation returns a list[dict] when model_or_list is a list. This makes the type contract inaccurate for callers and for generated OpenAPI/schema. Update the return type to something like dict | list[dict] (or refactor into two functions with precise return types).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

These fields default to None but their annotations don’t allow None (continuation_token: str = None, members: list[...] = None). For Pydantic models this can lead to schema/validation inconsistencies (e.g., JSON null rejected). Consider updating to str | None and list[...] | None (or use Field(default_factory=list) if you want an empty list by default).

[Copilot]

recipients/surfaces default to None but are annotated as non-optional lists (list[...]). If null is ever received in payloads, Pydantic will reject it, and the generated schema suggests null isn’t allowed even though the default implies optional. Consider changing these to list[...] | None (or default to empty lists via Field(default_factory=list) if that’s the intent).

[Copilot]

on_behalf_of defaults to None but is annotated as a non-optional list[OnBehalfOf]. In Pydantic models this can create validation/schema mismatches (default implies optional, type implies required/non-null). Consider updating to list[OnBehalfOf] | None (and, for consistency, applying the same | None pattern to the other fields in this model that also default to None).