a2aproject / a2aproject/A2A

[Docs]: Add deployment best practices for A2A HTTP base path (e.g. /a2a)

Offen Anfängerfreundlich
#2,029 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Shell
Sterne
25.7k
Forks
2.6k
Ø Merge
3 T. 6 Std.
Gemergte PRs (30 T.)
16

Beschreibung

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).

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Find the documentation section on deployment or HTTP endpoints. Look for existing best practices or a deployment guide. The change is to add a sentence recommending a dedicated base path like /a2a for operational simplicity. Check the repository's documentation structure to see where this fits, possibly in a spec file or a separate best practices document.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
1/5
Geschätzter Aufwand
Unter einer Stunde
Aktivitätsstatus
Ruhig
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
70/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.