fix: update agent card URL when host/port overridden in A2AServer.ser…

[mkmeral]

Description

This PR fixes a bug where specifying host and port parameters in A2AServer.serve() would start the server on the correct port, but the agent card (returned at /.well-known/agent-card.json) would still contain the original URL from the constructor defaults. This caused A2A clients to fail with HTTP 503 errors when trying to send messages, as they would attempt to connect to the wrong host/port.

Root Cause

The serve() method was passing the overridden host and port to uvicorn, but it wasn't updating the http_url and public_base_url attributes that are used to generate the agent card. As a result, clients would:

1. Successfully fetch the agent card (200 OK)
2. Extract the URL from the agent card (pointing to the wrong port)
3. Fail when trying to send messages to that incorrect URL (503 error)

Solution

1. Added a _http_url_explicit flag in __init__() to track whether the user explicitly provided an http_url parameter (e.g., for load balancer scenarios where the public URL differs from the local binding)
2. Modified serve() to update self.host, self.port, self.http_url, and self.public_base_url when host/port are overridden, but only if http_url wasn't explicitly set in the constructor

This preserves backwards compatibility and ensures that:

• Users who override host/port in serve() get the correct agent card URL
• Users who explicitly set http_url for load balancer scenarios don't have their public URL overwritten

Related Issues

Fixes #1258

Documentation PR

N/A - This is a bug fix that restores expected behavior. No documentation changes are needed.

Type of Change

Bug fix

Testing

How have you tested the change?

Unit Tests:

• Added 6 new unit tests to verify the fix:

  • test_serve_with_overridden_host_port_updates_agent_card_url - Verifies the main bug fix (issue [BUG] specifying host, port in A2AServer.serve(...) is broken #1258)
  • test_serve_with_overridden_port_only_updates_url - Tests port-only override
  • test_serve_with_overridden_host_only_updates_url - Tests host-only override
  • test_serve_with_explicit_http_url_does_not_override_url - Ensures explicit http_url is preserved for load balancer scenarios
  • test_serve_without_overrides_does_not_change_url - Verifies no changes when no overrides provided
  • test_http_url_explicit_flag_set_correctly - Tests the new flag initialization

• All 60 tests in tests/strands/multiagent/a2a/test_server.py pass

Manual testing:

• Created a test server with default config and called serve(host="localhost", port=9210)

• Verified the agent card at /.well-known/agent.json returns "url": "http://localhost:9210/" (correctly matching the overridden port)

• Verified the A2A client library (a2a.client.A2AClient) successfully retrieves the agent card with the correct URL

• 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.

[mkmeral]

/strands review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[mkmeral]

Agent Review Recommendation: Merge

### ✅ **Recommendation: Merge**

This is a well-implemented bug fix that correctly addresses issue #1258.

Key Points:

1. Bug Validated: I confirmed the bug exists in the main branch - the serve() method passes host/port to uvicorn but doesn't update the agent card URLs, causing clients to connect to the wrong address.

2. Implementation is Clean:

   • Added _http_url_explicit flag to track if user explicitly set http_url (for load balancer scenarios)
   • Modified serve() to update URLs only when host/port are overridden AND http_url wasn't explicit
   • Maintains full backwards compatibility

3. Excellent Test Coverage:

   • 6 new comprehensive tests covering all scenarios
   • All 60 tests pass
   • Codecov confirms 100% patch coverage

4. All Quality Checks Pass:

   • hatch fmt --formatter --check ✓
   • hatch fmt --linter --check ✓ (ruff + mypy)
   • No merge conflicts with main

Minor Suggestions (non-blocking):

1. The hasattr check is technically unnecessary since _http_url_explicit is always set in __init__(), but it's defensive coding and fine to keep.

2. There's a pre-existing docstring inaccuracy in serve() that says host defaults to "0.0.0.0" but it actually defaults to the __init__ value of "127.0.0.1" - this is not introduced by this PR.

3. Edge case with port=0 being treated as falsy is a pre-existing pattern and extremely unlikely to affect real users.