Issue: #1679
# Description
[a2a-samples/python](https://github.com/a2aproject/a2a-samples/tree/main/samples/python)
is being updated to use the new `v1.0`:
[samples-#462](https://github.com/a2aproject/a2a-samples/issues/462). We
are looking to merge [update helloworld sample to
v1.0-alpha](https://github.com/a2aproject/a2a-samples/pull/474) and
consequently need to update python tutorial in A2A as it references the
`helloworld sample`.
# Key Changes
- **Agent Skills & Card** (3-agent-skills-and-card.md): Updated the docs
to match the new AgentCard schema. Replaced the legacy `url` property
with `icon_url`, documented the new `supported_interfaces` field for
protocol bindings, and added mentions of the extended_agent_card
capability.
- **HelloWorldAgentExecutor logic** (4-agent-executor.md): Rewrote the
walkthrough for the execute method to reflect the modern event-driven
approach and to make the difference between non-streaming and streaming
more clear. It now explicitly describes enqueueing Task,
TaskStatusUpdateEvent (with `TASK_STATE_WORKING`),
TaskArtifactUpdateEvent, and TaskStatusUpdateEvent (with
`TASK_STATE_COMPLETED`) instead of single string messages.
- **Server Setup** (5-start-server.md): Replaced `0.0.0.0` with
`127.0.0.1` in the host binding tutorial and log examples to enforce
safer local testing defaults.
- **Client Interaction** (6-interact-with-server.md):
- Replaced MessageSendParams dictionaries with native protobuf
`Message/Part/Role` construction.
- Replaced direct A2ACardResolver instantiation with the new
`ClientFactory` approach.
- Unified the documentation around `send_message` (which now handles
streams dynamically based on `config` and agent capabilities) and
updated expected log outputs.
## Summary
Fixes documentation inconsistencies related to Part discriminator field
values, identified in #1365.
## Changes
### `docs/specification.md` — Appendix A.2.1
- **Legacy Part `kind` values**: corrected from PascalCase (`"kind":
"TextPart"`, `"kind": "FilePart"`, `"kind": "DataPart"`) to lowercase
(`"kind": "text"`, `"kind": "file"`, `"kind": "data"`), consistent with
what `whats-new-v1.md` documents as the v0.3.0 format
- **Legacy FilePart structure**: added the missing nested `file` object
wrapper
- **Legacy streaming event `kind` values**: corrected from PascalCase
(`TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`) to camelCase
(`taskStatusUpdate`, `taskArtifactUpdate`)
- **Current `DataPart` migration target**: removed incorrect
double-wrapping (`{ "data": { "data": {...} } }` → `{ "data": {...},
"mediaType": "application/json" }`)
- **Current streaming event member names**: aligned with
`whats-new-v1.md` (`taskStatusUpdate` / `taskArtifactUpdate`)
### `docs/topics/key-concepts.md`
- Updated Part description to use v1.0 terminology, removing references
to the removed `TextPart`, `FilePart`, and `DataPart` types
### `docs/tutorials/python/8-next-steps.md`
- Replaced reference to removed `DataPart` type with v1.0 Part field
names
### `CONTRIBUTING.md`
- Added **Documentation Guidelines** section with correct v1.0 Part
examples (member-presence pattern) and guidance on the correct v0.3.x
lowercase `kind` discriminator values for migration docs
## Related
- Closes#1365
- External community site fix:
https://github.com/sing1ee/a2a-directory/pull/12🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Gijs Walraven <gijs.walraven@delaware.pro>
In the future, we should probably explore refactoring the docs set to
avoid these becoming out of sync going forward
This pull request updates the project documentation to align with the
v1.0 Agent2Agent (A2A) Protocol Specification defined in
specification/a2a.proto. It ensures that all conceptual guides,
summaries, and tutorials reflect the current normative definitions,
RPC method names, and wire formats.
Summary of Changes
1. RPC Method Naming Updates
Standardized all method references to use the v1.0 PascalCase naming
convention:
* `message/send` → `SendMessage`
* `message/stream` → `SendStreamingMessage`
* `tasks/get` → `GetTask`
* `tasks/list` → `ListTasks`
* `tasks/cancel` → `CancelTask`
* `tasks/pushNotificationConfig/set` →
`CreateTaskPushNotificationConfig`
* `tasks/resubscribe` → `SubscribeToTask`
* `agent/getAuthenticatedExtendedCard` → `GetExtendedAgentCard`
2. JSON Example & Wire Format Corrections
Updated examples across all "Topic" files and the Python Quickstart to
match v1.0 breaking changes:
* Removed `kind` discriminators: Examples for Message, Task, Part, and
StreamResponse now use member-based polymorphism (e.g.,
{"text": "..."} instead of {"kind": "text", "text": "..."}).
* Enum Standardization: Changed role and state enums from
kebab-case/lowercase to SCREAMING_SNAKE_CASE with type prefixes (e.g.,
`"ROLE_USER"`, `"TASK_STATE_COMPLETED"`).
* Response Wrapping: Updated examples to reflect that `SendMessage` and
`SendStreamingMessage` return a unified response object where
the message or task is nested within the result.
3. LLM Context (`docs/llms.txt`)
* Completely refreshed the protocol summary and RPC method list to
ensure LLM-based tools (like Gemini CLI) have an accurate
representation of the v1.0 API surface and error codes.
4. Link & Anchor Maintenance
* Updated internal documentation links and spans to point to the correct
sections in the specification.md (e.g., correcting the
anchor for GetExtendedAgentCard).
Why this is needed
The v1.0 release introduced significant structural improvements for
ProtoJSON compliance and architectural consistency. Documentation
examples were previously showing v0.3.0 patterns which would cause
integration errors for developers using the latest SDKs.
Terminal states (COMPLETED, FAILED, CANCELLED, REJECTED) already
indicate task completion, making the final field redundant. This creates
consistency across streaming, polling, and push notification
communication patterns.
Changes:
- Removed final field (field 4) from TaskStatusUpdateEvent in proto
- Updated examples to remove final: true references
- Clarified that streams close upon terminal states
- Added migration guidance in Appendix A.2.2
Fixes#1232
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
The files __main__.py and test_client.py are located in
a2a-samples/samples/python/agents/langgraph/app/, not in the root
directory a2a-samples/samples/python/agents/langgraph/.
# Description
This PR updates the Setup Your Environment documentation to correct the
location of the requirements.txt file used for Python SDK installation.
The file is located in the samples/python directory, and the updated
command reflects this.
No code changes or functionality modifications were made—this is a
documentation-only update for accuracy.
Fixes#698
- requires Python 3.13
- AgentAuthentication has been removed from the SDK with the
introduction of SecuritySchemes
Co-authored-by: Mike Smith <mikeas@google.com>
Made minor fix to pip command under step titled "Install the A2A SDK and
its dependencies:"
# Description
Noticed that the command in step 2 - to install a2a and it's
dependencies had a slight error. Fixed it.
- Structuring of Information Architecture
- Combine `specification/*.md` files into a single `specification.md` in
RFC format.
- Combine `documentation.md` into `index.md`
- Rename `push-notifications.md` into `streaming-and-async.md`
- Create `topics/key-concepts.md` and `topics/what-is-a2a.md`
- Remove duplicated content between README/index files.
- Hide Python Tutorial from Nav until SDK is released.
Use mkdocs style relative paths to file.md.
Fix several old paths.
Add redirects to mkdocs.
Replace HTML prev/next links with markdown.
Format markdown.