Repository navigation
docs(guides): add the server guide - #568
chopmob-cloud wants to merge 3 commits into
Conversation
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>
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
left a comment
There was a problem hiding this comment.
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.
- The
TaskVersionbullet overstates the contract. Nothing reads the version:save_taskandstart_executiondiscard whatcreateandupdatereturn (handler.rs:329-336,:962), andStoredTaskis 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. - The Crate column names packages that are not ours.
a2a-serverdoes not exist on crates.io, anda2ais an unrelated crate (0.1.0). The packages area2a-server-lfanda2a-lf, as on the next-steps page. - The
MAX_PAGE_SIZElink points atfn.resolve_page_size.html.pagination/constant.MAX_PAGE_SIZE.htmlexists. - 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 itFailedwhen the executor errors or mixes aMessagewith task events, and refuses a new message to a terminal task;InMemoryTaskStorekeeps every task unlesswith_terminal_task_limitis 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;Refsalready 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>
|
All four are addressed.
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:
|
Serves #530 (part of #521). Adds
docs/guides/server.mdand a Guides nav section.What it covers
DefaultRequestHandler, and that both routes share one handler and one store.TaskStatevalues in a table with the terminal ones marked, howis_terminaldecides, and a link to Life of a task for the protocol side.Submittedbeforeexecuteis called; the first terminal event ends the run; an executor error, a failed store write or aMessagemixed with task events all persistFailedand publish it; a terminal task refuses a new message with "has already reached a terminal state".InMemoryTaskStorekeeps every task unlesswith_terminal_task_limitis set.TaskStoretrait, plus whatTaskVersionis actually used for (nothing in the SDK reads it today), whybegin_cancelexists, andgetreturningOption.DEFAULT_PAGE_SIZE/MAX_PAGE_SIZE/resolve_page_size, and the footgun that a store ignoringpage_sizeloses tasks.Snippets
All from compiled files via
pymdownx.snippetswithcheck_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.mdno 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 hostpub trait TaskStore,DefaultRequestHandler::newandDEFAULT_PAGE_SIZEare present in the built page, and no--8<--marker leaks into it