feat: pass A2A request context metadata as invocation state

[mkmeral]

Description

When the A2A executor handles an incoming request, downstream tools and hooks have no way to access A2A-specific context — metadata the caller attached, the task being processed, the request configuration, or related tasks. This forces tool authors to work around the limitation by tracking state externally or simply going without.

The stream_async method already accepts an invocation_state parameter that flows through the entire execution pipeline (event loop → hook events → ToolContext.invocation_state), but the A2A executor wasn't using it.

This change passes the full RequestContext object through invocation_state under the a2a_request_context key, giving tools and hooks access to all A2A request context — metadata, current_task, task_id, context_id, configuration, call_context, related_tasks, and requested_extensions — without decomposing it into individual fields that would need updating every time the A2A SDK adds a new property.

Related Issues

None

Documentation PR

None

Type of Change

New feature

Public API Changes

Tools and hooks receiving requests through the A2A server can now access the full A2A RequestContext via invocation_state:

from strands import tool
from strands.tools import ToolContext

@tool
def my_tool(input: str, tool_context: ToolContext) -> str:
    # Access the A2A request context
    a2a_context = tool_context.invocation_state.get("a2a_request_context")
    if a2a_context:
        metadata = a2a_context.metadata
        task_id = a2a_context.task_id
        config = a2a_context.configuration
    return f"Processed: {input}"

Hook providers can access it identically:

from strands.hooks.events import BeforeToolCallEvent

def before_tool(event: BeforeToolCallEvent) -> None:
    a2a_context = event.invocation_state.get("a2a_request_context")
    if a2a_context and a2a_context.metadata.get("priority") == "high":
        logger.info("High-priority A2A request for task %s", a2a_context.task_id)

The a2a_request_context key is only present when the agent is invoked through the A2A server. Non-A2A invocations are unaffected.

Testing

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Assessment: Request Changes

This PR introduces a clean, well-tested feature that leverages the existing invocation_state mechanism to expose A2A request context to tools and hooks. The implementation is minimal and follows established patterns.

Review Summary

• Documentation: The PR description states "Documentation PR: None" without justification. Since this adds a new public API pattern (a2a_request_context key) that tool/hook developers will rely on, please either link to a documentation PR or add a justification explaining why documentation updates are not needed.
• Implementation: Clean 4-line change that correctly passes the RequestContext through the existing invocation_state parameter.
• Testing: Comprehensive test coverage (5 new tests) covering various scenarios including with/without task, A2A compliant streaming mode, and access patterns.
• API Design: Good choice to pass the full RequestContext object rather than individual fields, providing forward compatibility as the A2A SDK evolves.

Please update the "Documentation PR" section with either a link to a docs PR or a brief justification for why docs aren't needed.

It is right that we need documentation. But I'm not going to block this PR on it