a2aproject / a2aproject/A2A

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

Aperta Adatta ai principianti
#2,029 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Shell
Stelle
25.7k
Fork
2.6k
Merge medio
3g 6h
PR unite (30g)
16

Descrizione

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

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
1/5
Tempo stimato
Meno di un'ora
Stato di attività
Tranquilla
Chiarezza
Specificata chiaramente
Idoneità per principianti
70/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.