Skip to content

docs(sample): bilingual README for the observability sample (zh/en) - #76

Merged
zhangwenjun-huawei merged 8 commits into
project-openan:mainfrom
khunj:fix/ci-gates-and-sample-docs
Oct 23, 2026
Merged

docs(sample): bilingual README for the observability sample (zh/en)#76
zhangwenjun-huawei merged 8 commits into
project-openan:mainfrom
khunj:fix/ci-gates-and-sample-docs

Conversation

@khunj

@khunj khunj commented Oct 12, 2026 •
edited by zhangwenjun-huawei
Loading

Copy link
Copy Markdown
Contributor

What

Rewrites a2a-t-sample/observability-sample/README.md as a pair of friendly docs — \README.md\ (English) and \README-zh.md\ (Chinese) — in the same style as the container READMEs, and registers the sample in the container indexes.

Why

The previous README was a single Chinese-only file focused on internals (decorator names, span tables, spec references). This makes the sample approachable:

  • business-first scenario walkthroughs: ative\ (end-to-end task), \a2at\ (LLM prompt generation, mock by default), egotiation\ (real per-round timing: two offer rounds over bare messages, the task starts only after agreement)
  • a copy-paste quick start (two terminals, uv)
  • an optional Langfuse section: three env vars put every round + the task on one browsable trace
  • a plain-language cheat sheet (what you do -> what the SDK records) and a compact environment-variable table
  • deep technical details (span names, handler caveat, verification helpers) move to a short Notes section

Notes

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Other (corpus test-asset addition: input case JSONs only, no SDK source change)

Checklist

  • I have read the CONTRIBUTING guide
  • All commits are signed off (git commit -s) per the DCO
  • New and existing tests pass locally
  • I have added tests that prove my fix is effective or my feature works (if applicable)
  • I have added or updated documentation as needed
  • New source files include the SPDX license header

@khunj
docs(sample): bilingual README for observability-sample
53d941e 
Rewrite the observability-sample README as a pair of docs (README.md in
English, README-zh.md in Chinese) in the same friendly style as the
container README: business-first scenario walkthroughs (native / a2at /
negotiation with the real per-round timing), a quick start that works
copy-paste, an optional Langfuse section, a plain-language cheat sheet
of what gets recorded, and a compact environment-variable table. The
deep technical details (span names, handler caveat, verification
helpers) move to a short Notes section.

Also register the sample in the container READMEs (directory tree +
use-case table).

Signed-off-by: z00930736 <zoujie5@huawei.com>
@khunj
khunj requested a review from a team as a code owner October 12, 2026 06:18
khunj added 2 commits October 15, 2026 16:37
@khunj
feat(observability): native support for DefaultRequestHandlerV2 + sam…
db37a7c 
…ple doc updates

- decorator detects the V2 shape (_active_task_registry) and rebuilds the
  ActiveTaskRegistry with the decorated executor/push sender (D9): per-event
  and push spans now work on the OFFICIAL default handler
- push sender wrap: install the _dispatch_notification wrapper in the V2
  branch too (V2 pushes from the event pump via send_notification -> dispatch)
- send_notification forwards without a second span when the dispatch wrapper
  handles fanout (dedup); _warn_if_v2_handler replaced by the adaptive INFO
- sample server + E2E migrate to the official DefaultRequestHandler (V2
  protocol: executors enqueue the initial Task snapshot first); E2E updated
  for the +initial-task-snapshot event and task-kind event spans
- includes the continued review work: payload redaction order, config gates,
  log/trace plumbing adjustments and their tests

Signed-off-by: z00930736 <zoujie5@huawei.com>
@khunj
docs(sample): refresh observability-sample docs for the official defa…
c22b0da 
…ult handler

The Notes section now reflects the D9 behavior: the sample uses the
official default DefaultRequestHandler and the decorator auto-adapts to
the V2 shape (registry rebuilt with decorated collaborators). The
container README gains a Use Case section for the sample.

Signed-off-by: z00930736 <zoujie5@huawei.com>
khunj added a commit to khunj/a2a-t-sdk-python that referenced this pull request Oct 15, 2026
@khunj
fix(observability): review fixes for PR project-openan#76 - sample V2…
d0f507a 
… migration, push dedup, degradation test, smoke guard

- sample executors enqueue the initial Task snapshot first (V2 protocol
  requirement) - the sample was functionally broken on the official
  handler without this
- send_notification: skip the log and the extra span when the inner
  sender routes fanout through _dispatch_notification (V2 double-log)
- _wrap_legacy_collaborators: use the parameter instead of re-reading
  the attribute; V2 branch logs at debug when install_dispatch_wrapper
  is a no-op
- degradation test: assert the WARNING and that a request still yields
  the SERVER entry span (D9 test-plan item 5)
- E2E: smoke guard driving the sample app on the official handler;
  encoding cleanup (BOM/mojibake); debug print removed

Signed-off-by: z00930736 <zoujie5@huawei.com>
khunj added 5 commits October 15, 2026 18:12
@khunj
fix(observability): review fixes for PR project-openan#76 - sample V2…
3d3200a 
… migration, push dedup, degradation test, smoke guard

- sample executors enqueue the initial Task snapshot first (V2 protocol
  requirement) - the sample was functionally broken on the official
  handler without this
- send_notification: skip the log and the extra span when the inner
  sender routes fanout through _dispatch_notification (V2 double-log)
- _wrap_legacy_collaborators: use the parameter instead of re-reading
  the attribute; V2 branch logs at debug when install_dispatch_wrapper
  is a no-op
- degradation test: assert the WARNING and that a request still yields
  the SERVER entry span (D9 test-plan item 5)
- E2E: smoke guard driving the sample app on the official handler;
  encoding cleanup (BOM/mojibake); debug print removed

Signed-off-by: z00930736 <zoujie5@huawei.com>
@khunj
docs(sample): note the A2AT_SERVICE_NAME fallback in the env tables
7de4f1c 
Signed-off-by: z00930736 <zoujie5@huawei.com>
@khunj
fix(sample): mock resources path after the project-openan#74 director…
ce35465 
…y rename

The observability-sample mock_llm pointed at subscribe-incident/resources
(which was renamed to fault-management in project-openan#74) - the a2at/negotiation
scenarios crashed with FileNotFoundError on mock-response load. Both
directory names are now accepted.

Signed-off-by: z00930736 <zoujie5@huawei.com>
@khunj
fix(ci): drop the repo-level Tsinghua PyPI mirror
b2bdab3 
The [[tool.uv.index]] block pinned every uv resolution (including CI) to
pypi.tuna.tsinghua.edu.cn, which is intermittently unreachable from
GitHub Actions runners - the e2e job failed downloading babel through
it. Remove the repo-level mirror so CI resolves from official PyPI;
developers in mainland China can keep a fast mirror via their own uv
configuration (UV_DEFAULT_INDEX or ~/.config/uv/uv.toml) instead.

Signed-off-by: z00930736 <zoujie5@huawei.com>
@khunj
Merge remote-tracking branch 'origin/main' into fix/ci-gates-and-samp…
a64fad8 
…le-docs

# Conflicts:
#	a2a-t-sample/README-zh.md
#	a2a-t-sample/README.md
@zhangwenjun-huawei
zhangwenjun-huawei merged commit d6f4311 into project-openan:main Oct 23, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@khunj @zhangwenjun-huawei