feat: add agent-card list

[NicoleMGomes]

Disclaimer: Do not include SAP-internal or customer-specific information in this PR (e.g. internal system URLs, customer names, tenant IDs, or confidential configurations). This is a public repository.

Description

Adds A2A agent card discovery to the Agent Gateway module. A new list_agent_cards() method on AgentGatewayClient discovers destination fragments labelled agw.a2a.server and fetches each agent's card from {fragment_url}/.well-known/agent-card.json. Results can be filtered by fragment name or ORD ID via the new AgentCardFilter dataclass.

This release also extracts all fragment-listing logic into a dedicated _fragments.py module, centralising label constants and BTP Destination Service fragment operations that were previously scattered across _lob.py.

Changes:

• _models.py: new AgentCard, Agent, and AgentCardFilter dataclasses.
• _fragments.py (new): centralised fragment discovery — label constants (LABEL_KEY, MCP_LABEL_VALUE, IAS_LABEL_VALUE, IAS_USER_LABEL_VALUE, A2A_LABEL_VALUE), list_mcp_fragments, list_a2a_fragments, get_ias_fragment_name, get_ias_user_fragment_name.
• _lob.py: new _fetch_agent_card and get_agent_cards_lob functions; fragment helpers removed (now in _fragments.py).
• agw_client.py: new list_agent_cards(filter: AgentCardFilter | None) method with telemetry; customer agent path raises AgentGatewaySDKError (not yet supported).
• operation.py: new AGENTGATEWAY_LIST_AGENT_CARDS telemetry operation.
• user-guide.md: new A2A Agent Cards section, Fragments and Labels table, updated API reference.

Related Issue

Closes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Code refactoring
• Dependency update

How to Test

1. Create a LoB agent client:

   from sap_cloud_sdk.agentgateway import create_client
   agw_client = create_client(tenant_subdomain="my-tenant")

2. Call agents = await agw_client.list_agent_cards() — should return one Agent per A2A fragment (label agw.a2a.server).
3. Verify each agent.ord_id matches the ordId property on the fragment and agent.agent_card.raw contains the parsed JSON from {fragment_url}/.well-known/agent-card.json.
4. Call with a filter:

   from sap_cloud_sdk.agentgateway import AgentCardFilter
   agents = await agw_client.list_agent_cards(
       filter=AgentCardFilter(names=["my-fragment"], ord_ids=["sap.s4:apiAccess:agent:v1"])
   )

   Only matching fragments should be returned.
5. Call from a customer agent environment (credentials file present) — should raise AgentGatewaySDKError with "not yet supported for customer agents".
6. Run unit tests:

   uv run pytest tests/agentgateway/unit/ -q

   Expected: all 89 tests pass.

Checklist

• I have read the Contributing Guidelines
• I have verified that my changes solve the issue
• I have added/updated automated tests to cover my changes
• All tests pass locally
• I have verified that my code follows the Code Guidelines
• I have updated documentation (if applicable)
• I have added type hints for all public APIs
• My code does not contain sensitive information (credentials, tokens, etc.)
• I have followed Conventional Commits for commit messages

Additional Notes

• list_agent_cards is currently LoB-only. Customer agent support is tracked with a TODO in agw_client.py and will be added in a follow-up.
• _fragments.py is internal (_-prefixed) and not part of the public API. All functions previously accessible via _lob continue to work as before.
• AgentCardFilter uses AND semantics when both names and ord_ids are set. Empty lists behave the same as None (no filtering on that field).
• Each A2A fragment must have URL (base URL) and ordId properties. Fragments missing either are skipped with a warning log.