feat: cli spec reconciliation part 2 - #23
Open
yarolegovich wants to merge 7 commits into
Open
Conversation
yarolegovich
requested review from
Tehsmash,
msampathkumar and
nahapetyan-serob
August 28, 2026 15:56
|
|
||
| Cross-cutting options such as `--insecure` apply to whichever transport is negotiated. Where a future option is meaningful only for one binding (for example a gRPC keepalive setting that HTTP has no analogue for), a tool SHOULD namespace it per transport rather than overloading a global flag; the reserved convention is `--<binding>-<option>` (for example `--grpc-keepalive`). This specification defines no such per-transport option today; the convention is reserved so that adding one later is not a breaking change. | ||
|
|
||
| 13.2 **Protocol version (MUST):** a tool MUST signal the A2A protocol version on every request — A2A §3.6.1 makes this a client MUST. It travels as the `A2A-Version` service parameter, carried by each binding in its own mechanism (an HTTP header, or gRPC metadata); over HTTP a client MAY instead pass it as a request parameter (`?A2A-Version=1.0`, A2A §3.6.1). An empty value makes the server assume **0.3** (A2A §3.6.2), so the tool MUST set it explicitly. The tool SHOULD expose `--a2a-version`. Absent an explicit value, a tool SHOULD negotiate down to the highest version supported by both itself and the agent as declared on the Agent Card, but MUST NOT negotiate below **1.0**: versions earlier than 1.0 are legacy and MUST require an explicit opt-in. A tool MUST surface a version-unsupported error clearly rather than silently downgrading. |
Member
There was a problem hiding this comment.
This is intentional. I want to reduce the scope of work to be v1.0 or above.
At the start of the document I also mention that we are taking A2A v1.0 protocol as a the basedline.
| | `--metadata <json-string>` | Attach caller-supplied metadata to the message/request as an inline JSON object string (e.g. `'{"k":"v"}'`); values may be any JSON. Sent in the request **payload** (A2A §3.2.5); distinct from `--svc-param`, which sets transport-level parameters (A2A §3.2.6). | | ||
| | `-o, --output <text\|json>` | Output **format** only: `text` (default, §6.5, §11.2) or `json`, the protocol's own types (Appendix B). Whether `json` is one document or JSONL is set by `--stream`, not this flag (§11.3). | | ||
| | `--poll-interval <duration>` / `--timeout <duration>` | How often to re-check task status while waiting, and how long to wait before giving up (§9.3). | | ||
| | `--pretty` | Pretty-print (indent) `-o json --stream` records for human reading instead of the default one-compact-object-per-line JSONL (§11.3). Affects presentation only, not the data. OPTIONAL. | |
Member
There was a problem hiding this comment.
LGTM. A question: What if --pretty is a provided along with --stream or -o as input params for the CLI ?
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.
--polling-interval->--poll-interval.:as service parameter separator.--a2a-versionwhich can pin protocol version to a specific value. The default is all supported transports.jsonmode.--prettyfor re-enabling indentation.