docs: describe the span tree the SDK now emits

[apucacao]

Updates the docs to describe the span tree the SDK now emits.

README and AGENTS.md both still described one flat span per call with four attributes, which is what this SDK emitted before this stack and what neither SDK emits now. A reader following either document would have built the wrong thing.

README

• The span tree, and the rule that tool spans are siblings of chat rather than children.
• Why the root is the only span carrying the LaunchDarkly identity and the run total.
• What prompt caching does to the input count. The Anthropic example is the one worth keeping in mind: the provider reports an input of 3 for a turn that processed 23,554 tokens.
• That conversation content is off by default and how to turn it on, since that is the change most likely to surprise someone who was reading prompts off their spans.
• That an abandoned stream is marked rather than failed.

Also fixes an install command that named a package which does not exist: launchdarkly-ai rather than launchdarkly-ai-python.

AGENTS.md

Now points at TELEMETRY-CONTRACT.md as the authority rather than restating a summary that can drift from it, and lists the shared helpers with what each one writes.

The instruction that matters most is not to hand-write a span.set_attribute for anything a helper covers: six hand-rolled copies is how these spans drifted apart in the first place.

It also records the three things a new handler author would otherwise get wrong:

1. Cache folding belongs at the call site, not in the shared writer.
2. Finish reasons have three mechanisms, not one.
3. except Exception does not catch the GeneratorExit a streaming consumer triggers by breaking out of the loop.

Per-package docs

Each handler package's agents.md gets a four-line note with its span shape and a pointer to the contract, so someone opening one package sees it without reading the root document first.

Where this sits

Top of the stack. Docs only, no code.

---

Note

Overview
Replaces outdated flat-span telemetry docs with the three-level span tree every handler now emits (invoke_agent → chat / execute_tool siblings), so readers no longer build against the old one-span-per-call shape.

README now covers why LaunchDarkly identity and run totals live only on the root, how prompt-cache tokens fold into input_tokens, that conversation content is off unless capture_content=True, and that abandoned streams are marked rather than failed. Also corrects the OTel install package name to launchdarkly-ai-python.

AGENTS.md defers to TELEMETRY-CONTRACT.md as the authority, lists the shared span helpers, and records the pitfalls most likely to break a new handler: cache folding at the call site, three finish-reason mechanisms, and finally cleanup for streaming GeneratorExit. Each handler package's agents.md gets a short span-shape note pointing at the contract.

^{Reviewed by Cursor Bugbot for commit 619c8ef. Bugbot is set up for automated code reviews on this repo. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 2137167. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 73fa904. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1f5aa42. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 619c8ef. Configure here.}

[apucacao]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 619c8ef. Configure here.}