fix(telemetry): use per-invocation usage in agent span attributes

[en-yao]

Description

In multi-turn sessions, end_agent_span reports accumulated_usage (session-lifetime cumulative tokens) instead of per-invocation usage, causing inflated token metrics in OTEL spans. The per-invocation usage is already tracked at response.metrics.latest_agent_invocation.usage — this PR points end_agent_span to the correct field.

Related Issues

Resolves #2010

Documentation PR

N/A

Type of Change

Bug fix

Testing

Updated existing agent span tests to distinguish between accumulated and per-invocation usage. Added dedicated tests verifying per-invocation values are reported and fallback behavior when no invocations exist.

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

[mkmeral]

/strands review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Assessment: Comment

The fix correctly identifies and addresses the root cause from #2010 — end_agent_span was reporting session-lifetime accumulated_usage instead of per-invocation usage. The implementation is clean, the fallback behavior with a warning when latest_agent_invocation is None is good (per poshinchen's earlier feedback), and the tests cover the key paths.

Review Themes

• Opt-in vs Default: The main design question is whether this bug fix should be opt-in (as implemented) or the default behavior. The issue reporter describes the current behavior as a bug causing inflated metrics for all multi-turn users. Gating the fix behind an env var means affected users must discover and set gen_ai_use_latest_invocation_tokens to get correct metrics.
• Env Var Namespace: gen_ai_use_latest_invocation_tokens is an SDK-specific value being placed in the OTEL standard OTEL_SEMCONV_STABILITY_OPT_IN env var alongside actual OTEL semconv values. This could benefit from clearer scoping or documentation.
• Test Coverage: The new tests cover the happy path and the None-fallback path well. Cache token fields could use additional coverage in the per-invocation path.

[mkmeral]

@en-yao CI is failing, can you run hatch fmt --formatter && hatch fmt --linter? https://github.com/strands-agents/sdk-python/actions/runs/24200518889/job/70644356740?pr=2017

[en-yao]

Ran hatch fmt --formatter && hatch fmt --linter locally, both pass. The lint failure is a mypy error on line 856 that's already on main — not from this PR.

[mkmeral]

I see, @en-yao can you merge from main then? This is a required workflow, so we need it to be passing before merging

[mkmeral]

actually no problem, i merged from main. once the CI passes, it will merge automatically. thank you for the contribution :)