[Docs]: Add deployment best practices for A2A HTTP base path (e.g. /a2a)
- 主要語言
- Shell
- 星號
- 25.7k
- 分支
- 2.6k
- 平均合併
- 3 天 6 小時
- 30 天內合併 PR
- 16
描述
While implementing a Spring-based A2A server integration, I ran into a question regarding HTTP endpoint organization in production deployments.
The specification defines only relative HTTP paths (e.g. /message:send, /tasks/{id}) and leaves the base URL fully implementation-defined. This provides flexibility, but also leaves ambiguity for framework authors and production setups where A2A endpoints coexist with business REST APIs, admin endpoints, and observability interfaces.
Because of this, implementers need to make their own decision whether to expose A2A endpoints at the root level or under a dedicated base path.
Example:
/message:send
/tasks/{id}
vs
/a2a/message:send
/a2a/tasks/{id}
From an operational perspective, using a dedicated base path (e.g. /a2a) simplifies:
- API Gateway routing
- security configuration (Spring Security / OAuth / mTLS boundaries)
- reverse proxy setup
- rate limiting and traffic separation
- logging and observability
- clear separation between business APIs and A2A protocol endpoints
I am not proposing any change to the protocol itself and not suggesting to make any base path mandatory.
Instead, I would like to contribute a small documentation addition describing deployment best practices for HTTP endpoints, to help implementers make consistent production decisions.
A possible recommendation could be:
"A2A endpoints MAY be exposed under a dedicated base path such as /a2a to simplify routing, security configuration, and operational management."
If this makes sense, I would be happy to contribute a PR. I’d also appreciate guidance on where such documentation would fit best (specification vs separate deployment/best-practices section).
貢獻指南
評估
這個 Issue 還沒有評估資料。