Add per-agent Foundry endpoint alias routing in src/a2a_servers

[Copilot]

Description

a2a_servers could only target one AZURE_AI_PROJECT_ENDPOINT for all mounted agents, which blocked multi-project Foundry deployments. This change moves endpoint selection to each agent definition via endpoint aliases resolved from environment secrets, while keeping full endpoint URLs out of TOML.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test addition/improvement

Related Issues

N/A

Changes Made

• Per-agent Foundry endpoint mapping

  • Added foundry.endpoint_alias to agent config contract.
  • AgentDefinition now resolves/stores foundry_project_endpoint per agent.
  • Endpoint resolution order:
    1. AZURE_AI_PROJECT_ENDPOINT_<ALIAS_UPPER>
    2. AZURE_AI_PROJECT_ENDPOINT (backward-compatible fallback)

• Runtime wiring

  • app_factory.create_agent_app() now uses definition.foundry_project_endpoint instead of a single global endpoint.
  • Removed global project-endpoint requirement from ServerSettings.

• Validation semantics

  • Duplicate Foundry conflict detection changed from agent_name only to (endpoint_alias, agent_name) target.
  • Allows same agent name across different endpoint aliases/projects.

• Operational safety and observability

  • Startup logs now include endpoint alias and endpoint host only (not full endpoint URL).
  • Updated checked-in agent TOMLs and template to include endpoint_alias.

• Documentation + contract updates

  • Updated .env.template and a2a docs (foundry-integration, agent-definition-reference, setup/deploy/troubleshooting/runbook) for alias-based env configuration.

# agents/quote_agent.toml
[foundry]
agent_name = "userQuote"
endpoint_alias = "contoso_main"

# .env
AZURE_AI_PROJECT_ENDPOINT_CONTOSO_MAIN=https://<your-ai-services>.services.ai.azure.com/api/projects/<project>
# optional fallback
AZURE_AI_PROJECT_ENDPOINT=

Testing

• All existing tests pass
• Added new tests for new functionality
• Manually tested the changes
• Updated documentation

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Screenshots (if applicable)

N/A (no UI changes)

Additional Context

This introduces a config contract change: foundry.endpoint_alias is now required in *_agent.toml. Existing agent files must add the alias and corresponding AZURE_AI_PROJECT_ENDPOINT_<ALIAS_UPPER> secret.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• learn.microsoft.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.