docs: add A2A server FRD (simple profile) - #208
Tsuyoshi Ushio (TsuyoshiUshio) wants to merge 1 commit into
Conversation
f435721 to
b2d9d1f
Compare
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
The architecture and compatibility proposal require final human review.
Review effort: Lite
Findings: None
What changed in this PR
This documentation-only PR proposes A2A server support through FRD 0009, architecture documentation, and a staged implementation plan.
Changes:
- Adds FRD 0009 and its index entry.
- Documents A2A architecture, lifecycle, authentication, and compatibility gates.
- Defines staged implementation work, including Durable execution.
| File | Summary |
|---|---|
docs/frds/README.md |
Adds FRD 0009 to the index. |
docs/frds/0009-a2a-server.md |
Defines requirements, decisions, and acceptance criteria. |
docs/design/a2a-server.md |
Documents the proposed architecture and compatibility gates. |
docs/design/a2a-implementation-plan.md |
Defines staged implementation slices and acceptance criteria. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
b2d9d1f to
a323c5b
Compare
Tsuyoshi Ushio (TsuyoshiUshio)
changed the title
hallvictoria
left a comment
hallvictoria
left a comment
There was a problem hiding this comment.
A few design and coverage questions before implementation.
| - `url` is required. It is the trusted external JSON-RPC URL that the Agent Card | ||
| publishes. It must be absolute HTTPS, without credentials, query, or fragment. | ||
| HTTP is accepted only for loopback hosts. The path must end with | ||
| `/agents/{slug}/a2a`. The runtime does not infer it from request headers. |
There was a problem hiding this comment.
Could we avoid requiring the public URL to end with the internal Functions route? API Management and reverse proxies commonly rewrite paths, while A2A only requires the card to publish an absolute reachable URL. Keeping the HTTPS and credential checks but allowing a different external path would cover those deployments.
| it is absent. The runner session ID is a SHA-256 hash of the auth scope, agent | ||
| slug, and `contextId`, so client input never becomes a file name. Function, | ||
| admin, and anonymous modes share one app trust scope. Entra uses the validated | ||
| tenant and object or client identity. |
There was a problem hiding this comment.
Hashing makes contextId filename-safe, but it does not establish ownership. In anonymous/function/admin modes every caller shares the same app scope, so a caller who knows another context ID can resume that transcript. Could continuation require identity-backed auth or a signed server-issued context token, or otherwise remain stateless in shared-scope modes?
| ### Conversation context | ||
|
|
||
| The optional `contextId` continues a conversation. The server generates one when | ||
| it is absent. The runner session ID is a SHA-256 hash of the auth scope, agent |
There was a problem hiding this comment.
Reusing runner sessions also inherits the one-active-turn-per-session constraint. Concurrent requests with the same contextId can load the same history and append conflicting turns, especially across workers. Please define per-context serialization/rejection and include a concurrent same-context test.
|
|
||
| ### Limits | ||
|
|
||
| Fixed limits for each agent: 32 executions in flight, 256 KiB request body, |
There was a problem hiding this comment.
Is this limit intended to be global or per worker process? An in-memory limiter is per Functions worker, so scale-out can exceed 32 executions for one agent. Please either describe it as a per-process safety limit or specify distributed/global admission control.
| `returnImmediately`, unsupported methods and Parts, limits, and JSON-RPC ID | ||
| correlation. | ||
| - [x] CI: clean wheel install of `[a2a]` on Python 3.13 and 3.14. | ||
| - [x] E2E: real Functions host. MAF `A2AAgent` and a raw HTTP client fetch the |
There was a problem hiding this comment.
The real-host E2E in the implementation PR uses anonymous auth, and Core Tools does not enforce function keys locally. Could we add an integration scenario that protects both card discovery and JSON-RPC invocation, or narrow this checked item to anonymous interoperability?
Purpose
Add FRD 0009 for the experimental A2A server simple profile and its FRD index entry. This PR contains documentation only. It has no product behavior, dependency, or configuration changes.
The FRD covers only the scope that #209 implements:
builtin_endpoints.a2aconfiguration (mode: simple, expliciturl).SendMessageroute.Messageresponse. The existing HTTP auth, runner, and sessions are used again.Streaming, Tasks, push notifications, REST binding, and other items are listed as planned work only. They are not specified in this FRD.
Does this introduce a breaking change?
Pull Request Type
How to Test
Review
docs/frds/0009-a2a-server.md. Start with the goals, non-goals, and Decisions log.Other Information
This is the bottom PR of the stack. The implementation and sample are in #209.