feat(a2a): support mounts for containerized deployments

[jer96]

Description

This PR adds native support for configurable public URLs and automatic path-based mounting to the A2AServer class, enabling seamless deployment in containerized environments and behind load balancers with path-based routing.

Key Changes

1. New http_url Parameter

• Added http_url: str | None = None parameter to A2AServer constructor
• When provided, overrides the auto-generated URL from host:port for public agent card URLs
• Maintains separate concerns: host/port for internal binding, http_url for external access

2. Automatic Path-Based Mounting

• When http_url contains a path component, the server automatically mounts the A2A application at that path
• Uses framework-native Starlette/FastAPI mounting capabilities (no middleware required)
• Handles URL parsing and normalization automatically

3. Escape Hatch for Path-Stripping Load Balancers

• Added serve_at_root: bool = False parameter as an escape hatch for edge cases
• When True, forces the server to serve at root path regardless of http_url path component
• Solves scenarios where load balancers strip path prefixes before forwarding to containers
• Maintains correct public URLs in agent cards while serving internally at root

4. Enhanced URL Handling

• Added _parse_public_url() method to extract base URL and mount path from provided URLs
• Proper URL normalization with trailing slash handling
• Intelligent mounting behavior with explicit override capability

5. Framework Integration

• Updated both to_starlette_app() and to_fastapi_app() methods to handle mounting
• Maintains backwards compatibility - existing code works unchanged

Use Cases Solved

• Container Deployments: Internal binding (0.0.0.0:8080) vs external URL (https://my-alb.amazonaws.com)
• Load Balancer Scenarios: Public URLs that don't match internal configuration
• Path-Based Routing: Multiple agents behind same ALB with different path prefixes
• Path-Preserving ALBs: Load balancer forwards full path to container (default behavior)
• Path-Stripping ALBs: Load balancer strips path prefix before forwarding (use serve_at_root=True)

Related Issues

Addresses two GitHub feature requests:

• [FEATURE] Path Prefix Support for A2A Server #382
• [FEATURE] Configurable HTTP URL for A2A Server #383

Documentation PR

Will publish a followup PR for docs.

Type of Change

New feature

Testing

• unit tests
• manual testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• 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 (13 new tests)
• I have updated the documentation accordingly (comprehensive inline docs + example script)
• My changes generate no new warnings
• Any dependent changes have been merged and published

Examples of New Functionality:

# Most ALB scenarios (path preservation)
A2AServer(agent, http_url="http://my-alb.com/agent1")
# → Mounts at /agent1, serves /agent1/.well-known/agent.json

# Path-stripping ALBs 
A2AServer(agent, http_url="http://my-alb.com/agent1", serve_at_root=True)
# → Serves at root, but agent card shows http://my-alb.com/agent1/

# Local dev (unchanged)
A2AServer(agent, host="localhost", port=9000)
# → Serves at root on http://localhost:9000/

---

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