Skip to content

fix(docs): Clearer wording around context id.#1588

Merged
herczyn merged 7 commits intoa2aproject:mainfrom
herczyn:context_id_wording
Mar 5, 2026
Merged

fix(docs): Clearer wording around context id.#1588
herczyn merged 7 commits intoa2aproject:mainfrom
herczyn:context_id_wording

Conversation

@herczyn
Copy link
Copy Markdown
Member

@herczyn herczyn commented Mar 4, 2026

client side context id passing can be supported, server can choose to reject, client's should know how to fallback accordingly
if server accepts, server must respond with the context id
if server cannot accept client side context id it MUST respond with an error (i.e. it SHOULD not respond with a task with a different context id?)
servers may not accept a client side context id for a number of reasons: clashes, validation errors, not supporting context ids

@herczyn herczyn requested a review from a team as a code owner March 4, 2026 15:21
@gemini-code-assist
Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the documentation around the contextId within the A2A specification. The changes aim to provide clearer and more flexible guidelines for both agents and clients regarding the generation, assignment, and usage of contextIds, particularly addressing scenarios where clients might provide their own identifiers. The updates ensure the specification is more robust and less restrictive, accommodating various implementation strategies while maintaining consistency.

Highlights

  • Clarified 'Context' Definition: The definition of 'Context' in the specification has been updated to remove the 'server-generated' constraint, making it a more general optional identifier.
  • Softened contextId Generation Requirement: The guideline for agents generating a new contextId when one is not provided has been changed from 'MUST' to 'SHOULD', offering more flexibility.
  • Added Client-Side contextId Guidance: New guidance has been added advising clients not to provide a client-generated contextId unless they understand how the server will process it, enhancing clarity on client responsibilities.
Changelog
  • docs/specification.md
    • Updated the definition of 'Context' to remove the 'server-generated' attribute.
    • Modified the contextId generation rule for agents from 'MUST' to 'SHOULD'.
    • Added a new guideline for clients regarding the provision of client-generated contextIds.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request clarifies the wording around contextId handling, allowing for client-provided context IDs. The changes in docs/specification.md are a good step towards this. I've kept the original suggestions to further improve the clarity and consistency of the specification based on the points raised in your PR description.

Note: Security Review has been skipped due to the limited scope of the PR.

herczyn and others added 4 commits March 4, 2026 15:26
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Copy link
Copy Markdown
Contributor

@vinoo999 vinoo999 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm . will close out mine

Copy link
Copy Markdown
Member

@muscariello muscariello left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@herczyn herczyn merged commit dec790a into a2aproject:main Mar 5, 2026
8 checks passed
@herczyn herczyn deleted the context_id_wording branch March 5, 2026 11:33
darrelmiller pushed a commit that referenced this pull request Mar 12, 2026
🤖 I have created a release *beep* *boop*
---


## [1.0.0](v0.3.0...v1.0.0)
(2026-03-12)


### ⚠ BREAKING CHANGES

* **spec:** Combine `TaskPushNotificationConfig` and
`PushNotificationConfig`
([#1500](#1500))
* **spec:** remove duplicated ID from the create task push config
request ([#1487](#1487))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs`
([#1486](#1486))
* **spec:** Add LF prefix to the package.
([#1474](#1474))
* **spec:** Switch to non-complex IDs in requests
([#1389](#1389))
* **spec:** Standardize spelling of "canceled" to use American Spelling
throughout ([#1283](#1283))
* **spec:** Align enum format with ADR-001 ProtoJSON specification
([#1384](#1384))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent`
([#1308](#1308))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities`
([#1307](#1307))
* **spec:** Fixes for the last_updated_after field
([#1358](#1358))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add
device code / pkce
([#1303](#1303))
* **spec:** Make "message" field name consistent between protocol
bindings ([#1302](#1302))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release
([#1301](#1301))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to
`supportsExtendedAgentCard`
([#1222](#1222))
* **spec:** Remove v1s from a2a url http bindings
* **spec:** Large refactor of specification to separate application
protocol definition from mapping to transports

### Features

* **spec:** Add `tasks/list` method with filtering and pagination to the
specification
([0a9f629](0a9f629))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add
device code / pkce
([#1303](#1303))
([525ff38](525ff38))
* **spec:** Natively Support Multi-tenancy on gRPC through an additional
scope field on the request.
([#1195](#1195))
([cfbce32](cfbce32)),
closes [#1148](#1148)
* **spec:** Provide ability for SDKs to be backwards compatible.
([#1401](#1401))
([227e249](227e249))
* **spec:** Remove v1s from a2a url http bindings
([1bd263f](1bd263f))


### Bug Fixes

* Add missing metadata field to Part message in gRPC specification
([#1019](#1019))
([b3b266d](b3b266d)),
closes [#1005](#1005)
* Add name field to FilePart protobuf message
([#983](#983))
([2b7cb6f](2b7cb6f)),
closes [#984](#984)
* Clarify blocking calls return on interrupted states
([#1403](#1403))
([0655ff3](0655ff3))
* **doc:** Makes JSON-RPC SendMessage response clearer
([#1241](#1241))
([5792804](5792804))
* **docs:** Clearer wording around context id.
([#1588](#1588))
([dec790a](dec790a))
* **grpc:** Fix inconsistent property name between gRPC and JSON-RPC in
Message object ([#1100](#1100))
([2a1f819](2a1f819))
* **grpc:** missing field in gRPC spec - state_transition_history
([#1138](#1138))
([a2de798](a2de798)),
closes [#1139](#1139)
* **grpc:** Update `CreateTaskPushNotificationConfig` endpoint to
`/v1/{parent=tasks/*/pushNotificationConfigs}`
([#979](#979))
([911f9b0](911f9b0))
* **proto:** Add icon_url to a2a.proto
([#986](#986))
([17e7f62](17e7f62))
* **proto:** Adds metadata field to A2A DataPart proto
([#1004](#1004))
([a8b45dc](a8b45dc))
* Remove unimplemented state_transition_history capability field
([#1396](#1396))
([c768a44](c768a44)),
closes [#1228](#1228)
* Restore CreateTaskPushNotificationConfig method naming
([#1402](#1402))
([d14f410](d14f410))
* Revert "chore(gRPC): Update a2a.proto to include metadata on
GetTaskRequest" ([#1000](#1000))
([e6b8c65](e6b8c65))
* Simplify Part message structure by flattening FilePart and DataPart
([#1411](#1411))
([bfae8f7](bfae8f7))
* **spec:** Add LF prefix to the package.
([#1474](#1474))
([a54e809](a54e809))
* **spec:** add metadata to `CancelTaskRequest`
([#1485](#1485))
([c441b91](c441b91)),
closes [#1484](#1484)
* **spec:** Added clarification on timestamps in HTTP query params
([#1425](#1425))
([6292104](6292104))
* **spec:** Added clarifying text around messages and artifacts
([#1424](#1424))
([b03d141](b03d141))
* **spec:** Adjust field number for `ListTasksRequest.tenant` to prevent
missing number ([#1470](#1470))
([cd16c52](cd16c52))
* **spec:** Clarify contextId behavior when message is sent with taskId
but without contextId
([#1309](#1309))
([a336a5a](a336a5a))
* **spec:** Clarify versioning strategy and client responsibilities in
protocol specification
([#1259](#1259))
([a4afeea](a4afeea))
* **spec:** Fix/1251 clarify authentication scheme
([#1256](#1256))
([3e6c7db](3e6c7db))
* **spec:** Fixes for the last_updated_after field
([#1358](#1358))
([0e204bf](0e204bf))
* **spec:** Make "message" field name consistent between protocol
bindings ([#1302](#1302))
([1e5f462](1e5f462)),
closes [#1230](#1230)
* **spec:** make `history_length` optional
([#1071](#1071))
([0572953](0572953))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs`
([#1486](#1486))
([cf735cb](cf735cb))
* **spec:** Remove config from binding.
([#1587](#1587))
([010b9cc](010b9cc))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release
([#1301](#1301))
([60f83c3](60f83c3)),
closes [#1227](#1227)
* **spec:** remove duplicated ID from the create task push config
request ([#1487](#1487))
([393898d](393898d))
* **spec:** Remove metadata field from ListTasksRequest
([#1235](#1235))
([b6ef9ee](b6ef9ee))
* **spec:** Remove reserved and fix tags ordering
([#1494](#1494))
([1997c9d](1997c9d))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to
`supportsExtendedAgentCard`
([#1222](#1222))
([c196824](c196824)),
closes [#1215](#1215)
* **spec:** Standardize spelling of "canceled" to use American Spelling
throughout ([#1283](#1283))
([4dd980f](4dd980f))
* **spec:** Suggest Unique Identifier fields to be UUID
([#966](#966))
([00cf76e](00cf76e))
* **spec:** Switch to non-complex IDs in requests
([#1389](#1389))
([2596c1c](2596c1c)),
closes [#1390](#1390)
* **spec:** Update security schemes example
([#1364](#1364))
([f9a8f5b](f9a8f5b))
* Update the Java tutorials and descriptions
([#1181](#1181))
([202aa06](202aa06))


### Documentation

* **spec:** Align enum format with ADR-001 ProtoJSON specification
([#1384](#1384))
([810eaa1](810eaa1)),
closes [#1344](#1344)


### Code Refactoring

* **spec:** Combine `TaskPushNotificationConfig` and
`PushNotificationConfig`
([#1500](#1500))
([d1ed0da](d1ed0da))
* **spec:** Large refactor of specification to separate application
protocol definition from mapping to transports
([b078419](b078419))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities`
([#1307](#1307))
([40d6286](40d6286))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent`
([#1308](#1308))
([5b101cc](5b101cc))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants