Add a server-side override for the A2A Agent Card URL

[AnuradhaKaruppiah]

Description

Closes #1501

This PR adds a server-side override for the A2A Agent Card URL so deployments behind Kubernetes ingress/proxies can publish the correct external endpoint.

Sample Usage:

 nat a2a serve --config_file examples/getting_start
ed/simple_calculator/configs/config.yml --port 10000 --public_base_url "http://nat.isamazing.com"

By Submitting this PR I confirm:

• I am familiar with the Contributing Guidelines.
• We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  • Any contribution which contains commits that are not Signed-Off will not be accepted.
• When the PR is ready for review, new or existing tests cover these changes.
• When the PR is ready for review, the documentation is up to date with these changes.

Summary by CodeRabbit

• New Features

  • Added optional public_base_url setting to let deployments advertise a custom external URL for the Agent Card.

• Tests

  • Added test coverage ensuring public_base_url is respected and normalized (trailing slash behavior).

• Documentation

  • New Kubernetes & Ingress deployment guide showing how to provide a public URL (including runtime/env-var injection examples) for proper Agent Card advertisement.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b022e93 and 823cb08.

📒 Files selected for processing (1)

• docs/source/run-workflows/a2a-server.md

---

Walkthrough

The PR adds an optional public_base_url to the A2A server front-end config, centralizes Agent Card URL resolution to prefer that field (or environment-injected value) over the default host:port, updates docs for Kubernetes/Ingress usage, and adds a test for URL normalization.

Changes

Cohort / File(s)	Summary
Configuration & Implementation packages/nvidia_nat_a2a/src/nat/plugins/a2a/server/front_end_config.py, packages/nvidia_nat_a2a/src/nat/plugins/a2a/server/front_end_plugin_worker.py	Added optional `public_base_url: HttpUrl
Documentation docs/source/run-workflows/a2a-server.md	Added "Kubernetes and Ingress Deployments" guidance showing that server bind address may differ from public address and recommending public_base_url (env var example NAT_PUBLIC_BASE_URL) with YAML snippets.
Tests packages/nvidia_nat_a2a/tests/server/test_agent_card_generation.py	Added test test_agent_card_url_uses_public_base_url_when_configured to assert Agent Card URL uses and normalizes public_base_url; added required config imports.

Sequence Diagram(s)

sequenceDiagram
  participant K8s as Kubernetes Init
  participant Server as A2A Server
  participant AgentCard as Agent Card
  participant Client as Client

  K8s->>Server: inject NAT_PUBLIC_BASE_URL / env config
  Server->>Server: read config.public_base_url or env
  Server->>Server: _resolve_agent_url() (normalize trailing slash)
  Server->>AgentCard: generate Agent Card with resolved URL
  Client->>AgentCard: fetch Agent Card (uses public URL)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise, descriptive, and directly summarizes the main change: adding a server-side override for the A2A Agent Card URL.
Linked Issues check	✅ Passed	The PR successfully implements the linked issue #1501 objectives: provides public_base_url option for runtime override of Agent Card URL, supports dynamic endpoint resolution, and enables correct URL publishing for Kubernetes/proxy deployments.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue: documentation updates, front-end config field addition, URL resolution logic, and corresponding tests. No unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[AnuradhaKaruppiah]

/ok to test b022e93

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/source/run-workflows/a2a-server.md`:
- Around line 117-120: Update the docs example to use the repository's required
NAT_ prefix by renaming PUBLIC_BASE_URL to NAT_PUBLIC_BASE_URL everywhere in
this section (the example key public_base_url and the explanatory sentence that
instructs to provide the variable at runtime). Ensure the text instructs users
to supply NAT_PUBLIC_BASE_URL via your deployment tooling (Helm values or
environment injection) and keep the variable name consistent across the snippet
and prose.

In
`@packages/nvidia_nat_a2a/src/nat/plugins/a2a/server/front_end_plugin_worker.py`:
- Around line 227-232: The fallback URL construction in _resolve_agent_url can
produce invalid URLs for IPv6 hosts (e.g., ::1); update the fallback branch in
_resolve_agent_url to detect IPv6 host literals (e.g., using Python's ipaddress
module or by checking for ':' in config.host) and wrap the host in square
brackets before appending the port so the returned URL is valid (use config.host
-> maybe wrap as f"[{config.host}]" when needed) while keeping existing behavior
for IPv4/hostname and preserving trailing slash.

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 22d6ecd and b022e93.

📒 Files selected for processing (4)

• docs/source/run-workflows/a2a-server.md
• packages/nvidia_nat_a2a/src/nat/plugins/a2a/server/front_end_config.py
• packages/nvidia_nat_a2a/src/nat/plugins/a2a/server/front_end_plugin_worker.py
• packages/nvidia_nat_a2a/tests/server/test_agent_card_generation.py

[AnuradhaKaruppiah]

/ok to test 823cb08

[AnuradhaKaruppiah]

/merge