Skip to content

feat(a2a): support mounts for containerized deployments #524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 23, 2025

Conversation

jer96
Copy link
Member

@jer96 jer96 commented Jul 23, 2025

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:

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.

@jer96 jer96 temporarily deployed to auto-approve July 23, 2025 14:28 — with GitHub Actions Inactive
@jer96 jer96 temporarily deployed to auto-approve July 23, 2025 15:29 — with GitHub Actions Inactive
@jer96 jer96 temporarily deployed to auto-approve July 23, 2025 15:52 — with GitHub Actions Inactive
@jer96 jer96 marked this pull request as ready for review July 23, 2025 16:01
@cagataycali cagataycali merged commit 4f4e5ef into strands-agents:main Jul 23, 2025
22 checks passed
dbschmigelski pushed a commit to Ketansuhaas/sdk-python that referenced this pull request Jul 24, 2025
…ts#524)

* feat(a2a): support mounts for containerized deployments

* feat(a2a): escape hatch for load balancers which strip paths

* feat(a2a): formatting

---------

Co-authored-by: jer <jerebill@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants