Python: Add A2A metadata hooks for cross-agent runtime context

[droideronline]

Description

A2AAgent can send standard A2A message metadata, and RequestContext exposes inbound metadata on the server. However, there is currently no public way to bridge workflow runtime context into that metadata and then initialize the remote Microsoft Agent Framework session before execution.

This is needed when one workflow participant or tool produces structured runtime context and a later A2AAgent participant must send that context to a remote A2A server.

Current behavior

• GroupChat correctly forwards function_invocation_kwargs to its participants.
• A2AAgent.run() accepts function_invocation_kwargs for interface compatibility but does not transmit them over A2A.
• A2AAgent already maps Message.additional_properties["a2a_metadata"] to A2A Message.metadata, but callers must construct this message metadata themselves.
• A2AExecutor receives the inbound RequestContext, including metadata, but creates the MAF session internally with no hook to initialize session.state before calling the agent.

Desired behavior

Provide explicit, JSON-safe extension points for this flow without automatically serializing arbitrary runtime kwargs or placing application data in HTTP headers.

For example, one possible API would be:

A2AAgent.run(
    messages,
    a2a_metadata={"context": runtime_context},
)

and a server-side hook such as:

class A2AExecutor:
    async def prepare_session(
        self,
        context: RequestContext,
        session: AgentSession,
    ) -> None:
        pass

The server implementation could then do:

session.state["context"] = context.message.metadata.get("context")

Minimal reproduction

runtime_context = {"request_id": "example", "attributes": {"key": "value"}}

await workflow.run(
    "Process the request.",
    function_invocation_kwargs={"runtime_context": runtime_context},
)

The expected result is that the remote A2A server can retrieve the structured runtime context before invoking the MAF agent.

Proposed scope

• Add a documented outbound A2A metadata mechanism to A2AAgent.
• Add a documented pre-execution session initialization hook to A2AExecutor.
• Add focused client and server tests proving metadata is available before remote agent execution.
• Document that only JSON-compatible, explicitly selected application data should be transmitted.

I am happy to contribute the implementation after the API direction is confirmed.

[UniversePeak]

Thanks for the detailed reproduction. I verified the current main path: A2AAgent._prepare_message_for_a2a() already copies the explicit Message.additional_properties["a2a_metadata"] mapping to the outbound A2A message, while A2AExecutor.execute() creates the session immediately before _run()/_run_stream() and has no pre-execution hook. I also found no open PR or commit linked to #7973.

I can contribute the smallest focused implementation once the API direction is confirmed. My proposed slice is:

1. Keep arbitrary function_invocation_kwargs out of transport. Add an explicit, JSON-safe a2a_metadata input at the A2AAgent boundary (or document/reuse the existing message-level a2a_metadata path if maintainers prefer), and cover both regular and streaming sends without changing unrelated headers.
2. Add an awaited A2AExecutor session-preparation extension point that runs after create_session(...) and before _run/_run_stream, receiving the inbound RequestContext and newly-created AgentSession. The default remains a no-op, so existing users are unaffected.
3. Add focused unit tests proving that selected metadata arrives at the remote A2A message and that the hook can populate session state before agent execution, including the streaming path where applicable.

Could a maintainer confirm the preferred public API/signature and whether this issue should be assigned to me for implementation? I will keep the change limited to the Python A2A package and its tests, and document that only explicitly selected JSON-compatible application data is transmitted.