Skip to content

chore(docs): document strict AgentExecutor streaming rules in v1.0 guide#1014

Merged
sokoliva merged 2 commits intoa2aproject:mainfrom
sokoliva:migration-doc
Apr 23, 2026
Merged

chore(docs): document strict AgentExecutor streaming rules in v1.0 guide#1014
sokoliva merged 2 commits intoa2aproject:mainfrom
sokoliva:migration-doc

Conversation

@sokoliva
Copy link
Copy Markdown
Member

@sokoliva sokoliva commented Apr 23, 2026

Description

  • Adds a new section "Server: AgentExecutor Streaming Rules" to the v0.3 → v1.0 migration guide, covering the breaking change introduced in feat!: Raise errors on invalid AgentExecutor behavior. #979 where the server now strictly enforces the A2A spec rules for message/stream.
  • Documents the four InvalidAgentResponseError cases (mixing Message and Task events, multiple Messages, updates before the initial Task) with a clear table mapped to the actual error messages from active_task.py.
  • Provides before/after migration examples — including the message-only pattern and the full task lifecycle pattern (Task → WORKING → invoke agent → artifact → COMPLETED) — plus a quick migration checklist.
  • Links to the updated helloworld/agent_executor.py in a2a-samples#474 as a working reference.
  • Adds a corresponding bullet to the "Summary of Key Changes" section

Why

Existing v0.3 executors that mixed Message and Task events were silently tolerated. After #979 they fail at runtime with InvalidAgentResponseError, which is easy to hit and hard to diagnose without guidance. This section gives users a clear path to migrate.

@sokoliva sokoliva requested a review from a team as a code owner April 23, 2026 09:15
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 updates the v1.0 migration documentation to include new sections on AgentExecutor streaming rules and corrects various cross-references and typos. The documentation now explicitly details the strict enforcement of streaming patterns, requiring either a single message or a task-first lifecycle. One minor improvement was suggested to generalize a violation description in the streaming rules table to cover all task update events.

Comment thread docs/migrations/v1_0/README.md
Comment thread docs/migrations/v1_0/README.md Outdated
@ishymko ishymko changed the title docs(migrations): document strict AgentExecutor streaming rules in v1.0 guide chore(docs): document strict AgentExecutor streaming rules in v1.0 guide Apr 23, 2026
@sokoliva sokoliva merged commit d02ae4e into a2aproject:main Apr 23, 2026
3 checks passed
@sokoliva sokoliva deleted the migration-doc branch April 23, 2026 09:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants