Repository navigation
Commit 83d7f5d
authored
feat(server): add caching headers to the agent card endpoint (a2aproject#1272)
## What
Spec
[8.6.1](https://a2a-protocol.org/latest/specification/#861-server-requirements)
asks the card endpoint for a `Cache-Control` header with a `max-age`,
and an `ETag` "derived from the Agent Card's `version` field or a hash
of the card content". It sent neither, so every client refetched the
whole card every time with no way to revalidate - for content the spec
itself describes as changing "infrequently relative to the frequency at
which clients may fetch it".
One serving site, `agent_card_routes.py`. FastAPI re-wraps the same
endpoint rather than building its own response, so there is no second
variant to keep in step.
## Hash rather than version
8.6.1 allows either, but `card_modifier` can return a different card per
request without touching `version`, and a validator that goes stale
silently is worse than none. Hashing the card actually being served
stays correct under it. There is a test for exactly that.
`json.dumps(sort_keys=True)` rather than the RFC 8785 canonicalization
this repo already has for signing: an ETag is opaque and is only ever
compared against one this server produced, so determinism is the entire
requirement, and JCS would add a depth limit and a failure mode for
nothing. The signing canonicalizer also strips `signatures`, which would
be wrong here - a card whose signatures changed is a different response
body.
## Conditional requests
`If-None-Match` is honoured with a 304. Emitting a validator and then
ignoring the header that uses it would leave clients re-downloading the
card anyway, which is the thing 8.6 exists to avoid. Handled per RFC
9110 8.2.2: comparison is weak, so `W/"x"` matches `"x"`, `*` matches,
and a list is accepted.
## Cache-Control is opt-in
8.6.1 ties `max-age` to "the agent's expected update frequency", which
the SDK cannot know - a card regenerated per deployment and one static
for months want very different numbers, and a wrong guess baked into the
library is a stale card nobody can explain. It is a parameter with no
default. The `ETag` ships either way, so the endpoint satisfies 8.6.1's
either/or unconfigured, and revalidation costs one 304.
## Result
Clears `CARD-CACHE-001` (`should`) on all three bindings, and takes grpc
to zero failures at every level.1 parent 5751d31 commit 83d7f5d
3 files changed
Lines changed: 233 additions & 2 deletions
File tree
- .github/actions/spelling
- src/a2a/server/routes
- tests/server/routes
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
139 | 139 | | |
140 | 140 | | |
141 | 141 | | |
| 142 | + | |
142 | 143 | | |
143 | 144 | | |
144 | 145 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
1 | 4 | | |
2 | 5 | | |
3 | 6 | | |
| |||
28 | 31 | | |
29 | 32 | | |
30 | 33 | | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
31 | 75 | | |
32 | 76 | | |
33 | 77 | | |
34 | 78 | | |
| 79 | + | |
35 | 80 | | |
36 | | - | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
37 | 93 | | |
38 | 94 | | |
39 | 95 | | |
| |||
45 | 101 | | |
46 | 102 | | |
47 | 103 | | |
48 | | - | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
49 | 117 | | |
50 | 118 | | |
51 | 119 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
1 | 3 | | |
2 | 4 | | |
3 | 5 | | |
4 | 6 | | |
5 | 7 | | |
6 | 8 | | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
7 | 12 | | |
8 | 13 | | |
9 | 14 | | |
| |||
69 | 74 | | |
70 | 75 | | |
71 | 76 | | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
0 commit comments