[Bug]: Agent Card response missing Cache-Control and ETag caching headers

[jmesnil]

What happened?

Summary

The Agent Card HTTP response does not include Cache-Control, ETag, or Last-Modified caching headers, failing three caching-related requirements across all transports.

Requirement

• ID: CARD-CACHE-001, CARD-CACHE-002, CARD-CACHE-003
• Section: 2.1.1 — Agent Card Caching
• Level: SHOULD (CARD-CACHE-001, CARD-CACHE-002), MAY (CARD-CACHE-003)
• Spec: specification.md#211-agent-card

Specification

Servers SHOULD include standard HTTP caching headers (e.g., Cache-Control, ETag) in their Agent Card responses to allow clients to cache and revalidate efficiently. Servers MAY also include a Last-Modified header.

Expected behavior

A compliant implementation should:

1. Include a Cache-Control header with a max-age directive in the Agent Card response (CARD-CACHE-001)
2. Include an ETag header in the Agent Card response (CARD-CACHE-002)
3. Optionally include a Last-Modified header in the Agent Card response (CARD-CACHE-003)

Actual behavior

The Agent Card response at /.well-known/agent-card.json contains none of these caching headers:

< HTTP/1.1 200 OK
< content-type: application/json;charset=UTF-8
< content-length: ...

No Cache-Control, ETag, or Last-Modified headers are present.

Reproducer

# Fetch the agent card and inspect response headers
curl -si http://localhost:9999/.well-known/agent-card.json | head -20

# Check specifically for caching headers (all missing)
curl -si http://localhost:9999/.well-known/agent-card.json | grep -iE '^(cache-control|etag|last-modified):'

TCK test

• tests/compatibility/agent_card/test_agent_card_caching.py::TestAgentCardCacheControl::test_cache_control_present
• tests/compatibility/agent_card/test_agent_card_caching.py::TestAgentCardCacheControl::test_cache_control_has_max_age
• tests/compatibility/agent_card/test_agent_card_caching.py::TestAgentCardETag::test_etag_present
• tests/compatibility/agent_card/test_agent_card_caching.py::TestAgentCardLastModified::test_last_modified_present

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[jmesnil]

The spec says that the server SHOULD add these headers so we don't have to do it to be compatible.

However I have still opened that issue because I'm not sure how an user COULD do it. The Agent Card creation is hidden behind a @Produces @PublicAgentCard method and it's not clear to me where the user could specify any caching headers that would be added to the Agent Card HTTP response

[kabir]

Could perhaps the AgentCard contain a timestamp (which is not serialized) when the bean is initialised? Not sure exactly how @PostConstruct works with @produces beans.
But then we could potentially add the headers from that information in the web layer(s)?