docs(tasks/get): remove non-existent include_result flag from polling examples#3127
Merged
Conversation
… examples The tasks/get request schema does not define include_result, and the response schema does not define a typed result field. Five doc files were inviting buyers to send include_result: true and read a typed completion payload off the polled response — neither is supported by the 3.0 spec. Removed the spurious parameter from polling examples and added a note in task-lifecycle.mdx stating that in 3.0 the completion payload (e.g. media_buy_id, packages from create_media_buy) is delivered via push_notification_config webhook; tasks/get polling reports terminal status only. Tracks #3123. Schema-additive fix (typed include_result + result projection) is out of scope per the patch policy in docs/reference/versioning.mdx and is targeted for 3.1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 tasks
bokelley
added a commit
that referenced
this pull request
Apr 25, 2026
…eset After patch #3127 landed, the four polling examples in async-operations.mdx, error-handling.mdx, orchestrator-design.mdx, and task-lifecycle.mdx no longer demonstrated include_result. Now that this PR makes the field spec-backed, restore include_result: true in those examples and replace the 3.0-only note in task-lifecycle.mdx with a description of the new field's semantics. Also tightens the changeset to match the schema's "completed only" constraint (was: "completed or failed") and lists the four doc files updated alongside calling-an-agent.mdx. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
added a commit
that referenced
this pull request
Apr 25, 2026
* feat(schema): add result and include_result to tasks/get (closes #3123) tasks/get response had no typed field for the completion payload. Buyers polling an async create_media_buy could see status: completed but had no schema-backed field to retrieve media_buy_id and packages. The push-notification webhook schema (mcp-webhook-payload.json) already defined result: $ref async-response-data.json; this PR mirrors that pattern on the polling API. Changes: - tasks-get-response.json: add optional result field ($ref async-response-data.json) Present when status is completed and include_result was true; absent otherwise. For failed tasks, use the error field. - tasks-get-request.json: add optional include_result boolean (default false). async-operations.mdx and task-lifecycle.mdx already referenced this parameter in code examples; this formalizes it in the schema. - docs/protocol/calling-an-agent.mdx: add completed tasks/get response example showing the result field, closing the documentation gap. - .changeset/tasks-get-result-field.md: minor bump (additive optional fields) Non-breaking: both fields are optional. Existing polling consumers continue to work; the typed field gives SDKs a stable, named key for the completion payload. Unblocks adcp-client#967 (polling-cycle hardening). https://claude.ai/code/session_013nAeRJTbEAmEdqvQit6Xmg * docs: re-introduce include_result in polling examples and align changeset After patch #3127 landed, the four polling examples in async-operations.mdx, error-handling.mdx, orchestrator-design.mdx, and task-lifecycle.mdx no longer demonstrated include_result. Now that this PR makes the field spec-backed, restore include_result: true in those examples and replace the 3.0-only note in task-lifecycle.mdx with a description of the new field's semantics. Also tightens the changeset to match the schema's "completed only" constraint (was: "completed or failed") and lists the four doc files updated alongside calling-an-agent.mdx. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
Merged
5 tasks
This was referenced Apr 28, 2026
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
1 participant
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.
Summary
The 3.0
tasks/getrequest schema does not define aninclude_resultfield, and the response schema does not define a typedresultfield. Five doc files were inviting buyers to sendinclude_result: trueand read a typed completion payload off the polled response — neither is supported by the spec we shipped.This patch corrects the docs to match what 3.0 actually ships:
include_result: truefrom the polling examples intask-lifecycle.mdx,async-operations.mdx(two call sites),error-handling.mdx, andorchestrator-design.mdx.task-lifecycle.mdxstating that the completion payload (e.g.media_buy_id,packagesfromcreate_media_buy) is delivered via the seller's push notification to the buyer's webhook URL configured inpush_notification_configon the original request. Buyers that need the completion payload MUST configure a webhook in 3.0; polling alone reports terminal status.Why patch (3.0.1) and not minor (3.1)
Per
docs/reference/versioning.mdx:This PR only removes diverging wording and clarifies the existing-3.0 retrieval path. The schema-additive fix (typed
include_resultrequest flag + documented response projection on completion) is the second half of the work and is intentionally out of scope here — see #3123 and the follow-up 3.1 PR.Test plan
npm run test:unitandnpm run typecheckpass via pre-commitgrep -rn "include_result" docs/ static/ server/src/returns only the new note intask-lifecycle.mdx(which references the planned 3.1 field by name)additionalProperties: trueCloses part of #3123. Schema-additive follow-up tracked separately for 3.1.
🤖 Generated with Claude Code