docs(spec): add HTTP base path deployment guidance - #2156
Open
madankumarpichamuthu wants to merge 2 commits into
Open
docs(spec): add HTTP base path deployment guidance#2156madankumarpichamuthu wants to merge 2 commits into
madankumarpichamuthu wants to merge 2 commits into
Conversation
handrews
reviewed
Aug 29, 2026
The HTTP+JSON/REST binding defines only relative URL patterns and leaves the base URL implementation-defined, which left implementers unsure whether to root A2A endpoints at the host root or under a dedicated prefix. Add a non-normative Base Path subsection to section 11.3 noting that implementations MAY serve endpoints under a dedicated prefix such as `/a2a` to simplify routing, middleware attachment, rate limiting, and observability. Clarify that a base path is an operational convenience, not a security or identity boundary, and that the advertised AgentInterface url must include the base path when one is used. Fixes a2aproject#2029
Address review feedback: the host plus prefix is not an RFC 3986 base URI, since resolving an operation path beginning with '/' against a base URI would replace the prefix rather than preserve it. Reframe the section around a path prefix that is concatenated with each operation path, add a note explaining the RFC 3986 distinction, and require that a prefix MUST NOT end with '/' to avoid '//' in the resulting path. Fixes a2aproject#2029
madankumarpichamuthu
force-pushed
the
docs/2029-http-base-path
branch
from
September 1, 2026 18:09
e5c7fb8 to
74daa8d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Closes #2029.
The HTTP+JSON/REST binding (§11.3) defines only relative URL patterns (
/message:send,/tasks/{id}, …) and leaves the base URL implementation-defined. This leaves framework authors and production deployments unsure whether to root A2A endpoints at the host root or under a dedicated prefix, especially where A2A endpoints coexist with business REST APIs, admin endpoints, and observability interfaces.This adds a non-normative §11.3.5 Base Path subsection that:
/a2a.AgentInterface.urlMUST include the base path when one is used.No protocol change and no mandatory base path — documentation only.
Checklist
CONTRIBUTINGGuide.docs(spec):forspecification.md).Fixes #2029