Skip to content

docs(guides): add the server guide - #568

Open
chopmob-cloud wants to merge 3 commits into
a2aproject:mainfrom
chopmob-cloud:docs/530-server-guide
Open

chopmob-cloud wants to merge 3 commits into
a2aproject:mainfrom
chopmob-cloud:docs/530-server-guide

Conversation

@chopmob-cloud

@chopmob-cloud chopmob-cloud commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Serves #530 (part of #521). Adds docs/guides/server.md and a Guides nav section.

What it covers

  • Executor and handler. The executor is a link to the quickstart; the page keeps DefaultRequestHandler, and that both routes share one handler and one store.
  • Task lifecycle. All nine TaskState values in a table with the terminal ones marked, how is_terminal decides, and a link to Life of a task for the protocol side.
  • How the handler drives a task. The SDK behaviour, which the protocol table does not describe: the task is created and persisted as Submitted before execute is called; the first terminal event ends the run; an executor error, a failed store write or a Message mixed with task events all persist Failed and publish it; a terminal task refuses a new message with "has already reached a terminal state". InMemoryTaskStore keeps every task unless with_terminal_task_limit is set.
  • Task store. The full TaskStore trait, plus what TaskVersion is actually used for (nothing in the SDK reads it today), why begin_cancel exists, and get returning Option.
  • Task listing and pagination. DEFAULT_PAGE_SIZE/MAX_PAGE_SIZE/resolve_page_size, and the footgun that a store ignoring page_size loses tasks.
  • What the page leaves out. A worked custom store; task: write the server guide: executor, task lifecycle and stores #530 stays open for it.

Snippets

All from compiled files via pymdownx.snippets with check_paths: true:

  • examples/src/quickstart/server.rs:main (existing region)
  • a2a-server/src/task_store/store.rs:task-store (new marker, the trait where the contract lives)
  • a2a-server/src/pagination.rs:page-size (new marker)

API reference

Every type links to its docs.rs page, under the published crate names (a2a-server-lf, a2a-lf). All 17 external links on the page and in the touched README row return 200.

Second commit: two pre-existing dead links

SPEC.md no longer exists in a2a-cli, and the READMEs pointed at it. Both now point at the published a2a-cli documentation. The one at line 479 sat outside every included region, so the snippet path check could not see it.

Verification

  • mkdocs build --strict: exit 0 on a clean Linux host
  • Every snippet renders: pub trait TaskStore, DefaultRequestHandler::new and DEFAULT_PAGE_SIZE are present in the built page, and no --8<-- marker leaks into it
  • External links: 17 of 17 return an accepted status
  • The Rust tree is unchanged from the head CI already ran green; this commit touches two Markdown files only

Serves a2aproject#530 (part of a2aproject#521). Covers the executor and handler wiring, the task
lifecycle, the TaskStore trait, and task listing with pagination.

Every snippet is included from a compiled file through pymdownx.snippets with
check_paths on: the handler from the quickstart server, and the TaskStore trait
and pagination bounds from the a2a-server source, which is where that contract
lives. Each type links to its docs.rs page, and every one of those links was
checked to resolve.

Two details are called out because the code documents them and they are easy to
get wrong: begin_cancel must close the check-then-act race between concurrent
cancels, and a store that ignores page_size loses tasks, because the handler
truncates the response to MAX_PAGE_SIZE and cannot synthesise a continuation
token for a paging scheme it does not own.

Verified: mkdocs build --strict passes and the rendered page contains each
snippet; a missing snippet section fails the build (negative control). cargo
check -p a2a-server-lf -p examples and cargo fmt -p a2a-server-lf --check are
clean.

Note for the merge: this adds a Guides nav section, as the transports guide
does, so whichever lands second needs a one-line resolve.

Signed-off-by: AlgoVoi <chopmob@gmail.com>
@chopmob-cloud
chopmob-cloud requested a review from a team as a code owner November 19, 2026 21:16
@codecov

codecov Bot commented Nov 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

a2aproject/a2a-cli removed specification/SPEC.md in a2aproject#161, so the link in the
vendored README returns 404 and fails the docs link check.

The link is pre-existing and unrelated to the server guide, but it fails the same
Docs workflow this branch touches, so it is fixed here rather than left red.
Point at the published a2a-cli documentation, which is where the command
reference now lives.

Signed-off-by: AlgoVoi <chopmob@gmail.com>

@muscariello muscariello left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I checked each claim against the code at ce151d3 and fetched every link. The lifecycle table matches TaskState and is_terminal, and the listing section matches list_tasks (clamp, then truncate). Docs and DCO checks are green. Three corrections and one scope question.

  1. The TaskVersion bullet overstates the contract. Nothing reads the version: save_task and start_execution discard what create and update return (handler.rs:329-336, :962), and StoredTask is unused outside its module. "A store must increment it on every write" is not a requirement today. Say what the number is for, or drop the bullet.
  2. The Crate column names packages that are not ours. a2a-server does not exist on crates.io, and a2a is an unrelated crate (0.1.0). The packages are a2a-server-lf and a2a-lf, as on the next-steps page.
  3. The MAX_PAGE_SIZE link points at fn.resolve_page_size.html. pagination/constant.MAX_PAGE_SIZE.html exists.
  4. Scope against #530. The issue asks for "the events an executor emits" and the lifecycle "as the SDK implements it". The state table is the protocol's. The SDK's behaviour is missing: the handler creates the task as Submitted, stops at the first terminal event, marks it Failed when the executor errors or mixes a Message with task events, and refuses a new message to a terminal task; InMemoryTaskStore keeps every task unless with_terminal_task_limit is set. The executor section repeats the quickstart page, so a link would free the room. If this is meant as part one, say what is left; Refs already keeps #530 open.

Nit: the second commit fixes a2acli/README.md:85, but line 479 still links the deleted SPEC.md (404). It sits outside the included region, so the link check cannot see it.

Answer the review on this pull request.

- Add the SDK behaviour a2aproject#530 asked for: the task starts in Submitted, the first
  terminal event ends the run, a failure persists Failed, and a terminal task
  refuses a new message. Link the executor section to the quickstart instead of
  repeating it.
- Say what TaskVersion is for: nothing in the SDK reads it today.
- Name the published crates, a2a-server-lf and a2a-lf.
- Point MAX_PAGE_SIZE at the constant rather than at resolve_page_size.
- Fix the a2acli README link to SPEC.md, which no longer exists, and say what
  a2aproject#530 still leaves open.

Signed-off-by: AlgoVoi <chopmob@gmail.com>
@chopmob-cloud

chopmob-cloud commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author

All four are addressed.

  1. TaskVersion. You are right that nothing reads it: save_task matches on Ok(_) and discards the value from update, prepare_task_for_execution drops the one from create with ?, and StoredTask is only referenced by its own module's re-export. The bullet now says that, and calls the type the hook a store would build optimistic concurrency on rather than a counter the handler enforces.
  2. Crate names. Both rows now say a2a-server-lf and a2a-lf. a2a-server does not resolve on docs.rs, and a2a is the unrelated 0.1.0 crate.
  3. MAX_PAGE_SIZE link. Now points at pagination/constant.MAX_PAGE_SIZE.html.
  4. Scope against task: write the server guide: executor, task lifecycle and stores #530. The SDK behaviour is now on the page under "How the handler drives a task": the task is created and persisted as Submitted before execute is called; the first terminal event stops the run; an executor error, a failed store write or a Message mixed with task events all persist Failed and publish it; a terminal task refuses a new message with "has already reached a terminal state". InMemoryTaskStore is described as keeping every task unless with_terminal_task_limit is set, and the page says what it still leaves out (a worked custom store) so task: write the server guide: executor, task lifecycle and stores #530 stays open for that.

The executor section is now two sentences and a link to the quickstart, which freed the room for the above.

The nit is fixed too: a2acli/README.md line 479 linked the deleted SPEC.md from outside every included region, where the snippet path check cannot see it. It now points at the published a2a-cli documentation, like line 85 already did.

mkdocs build --strict exits 0, the page renders all three snippets with no --8<-- markers, and the constant and crate-name changes are visible in the rendered HTML.

This branch has not been deployed

No deployments
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