feat(langchain-messages)!: emit invoke_agent, chat and execute_tool spans

[apucacao]

Replaces one flat span per call with the tree the TypeScript SDK emits, for langchain-messages.

invoke_agent                     one per call, carries the LD identity and the run total
├── chat {model}                 one per model turn, with that turn's own tokens
└── execute_tool {name}          one per tool call, a sibling of chat

Both provider attributes were wrong, in different ways

gen_ai.system was the configured provider name lower-cased, so an Anthropic-backed config reported anthropic where the TypeScript SDK reports langchain. That key names the instrumentation, and for the two LangChain handlers the instrumentation is the framework. It is now the literal string.

gen_ai.provider.name did not exist here at all, and it is not a passthrough of the configured name. It names who served the model, and its semantic-convention enum has no langchain member, so it follows the client the handler actually instantiates: ChatAnthropic for a configured provider of anthropic, ChatOpenAI for everything else.

A Bedrock or Azure config therefore reports openai. That looks wrong and is right, because an OpenAI client is what made the request. There is a test pinning it, because a passthrough reads as obviously correct.

Other changes

• Cached tokens are read from usage_metadata.input_token_details and reported per turn, without being added to the input figure, which LangChain already reports inclusive of them.
• Finish reasons go through the shared LangChain helper, which reads the reason from generation_info or response_metadata depending on which vendor answered. This handler is one of the places where the same code path serves either vendor, so an untranslated passthrough is least defensible here.
• The streaming path gets a finally. The per-chunk usage accumulation is a faithful port of the TypeScript, summing each field as chunks arrive rather than reading a single terminal figure.

Breaking change

The span is renamed from langchain.invoke to invoke_agent. Queries selecting on the old name will not match. gen_ai.system changes value, as above. Prompt and completion content is no longer on spans unless the caller passes capture_content=True.

Where this sits

Needs the usage layer (#28) and the content layer (#29). Independent of the other five handler PRs; the stack orders them only because gh stack is linear.

Tests: 799 to 824.

---

Note

Overview
Replaces one flat span per call with the TypeScript SDK's span tree for both blocking and streaming paths:

invoke_agent          # root: LD identity + run totals
├── chat {model}      # one per model turn
└── execute_tool {name}  # siblings of chat, not children

Breaking telemetry changes: span renamed from langchain.invoke to invoke_agent; gen_ai.system is now always the literal langchain (was the configured provider lower-cased); prompt/completion content is off by default and requires capture_content=True.

Also corrects gen_ai.provider.name to follow the client actually instantiated (anthropic only for Anthropic, otherwise openai), reports cache tokens and mapped finish reasons per turn, and adds streaming finally cleanup so abandoned streams still export spans without marking them ERROR.

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

[apucacao]

bugbot run

[apucacao]

bugbot run

[apucacao]

bugbot run

[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 c3de18e. Configure here.}

[apucacao]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

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

[cursor]

Structured turn can leak chat span

Medium Severity

In _run_structured_turn, only the model invoke is inside the try/fail_span guard. Output content writes and finish_model_span sit after it, so a raise while serializing parsed (especially with capture_content=True) leaves the chat span open. The tool-loop path in this same change already guards that work for this reason, and nothing else can recover this child span.

 

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

[cursor]

Stream error marks chat abandoned

Medium Severity

After the chunk loop, output content attribution and finish_model_span run outside the inner try that calls fail_span on the open chat span. A raise there leaves open_model_span set, so finally ends that span as abandoned instead of recording the real error.

 

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

[cursor]

Success writes zero root usage

Medium Severity

Successful blocking and streaming completions always call finish_root_span with run_usage.total, even when run_usage.reported is false. That writes all-zero root usage attributes and claims the run cost nothing when LangChain never supplied usage, which the failure path and telemetry contract both avoid.

Additional Locations (2)

• packages/langchain-messages/src/launchdarkly_ai_langchain_messages/handler.py#L502-L504
• packages/langchain-messages/src/launchdarkly_ai_langchain_messages/handler.py#L753-L756

 

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