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

[apucacao]

Replaces one flat span per call with the tree the TypeScript SDK emits, for langchain-agents. This is the last of the six handlers.

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

The per-turn data was already being summed from each message's usage_metadata; it now drives a span per turn.

The same two provider-attribute fixes as #34

gen_ai.system is now the literal string langchain rather than the configured provider name: the key names the instrumentation, and here that is the framework.

gen_ai.provider.name is new and is a binary choice rather than a passthrough. It names who served the model, so it follows the client actually instantiated: anthropic when the config says so, openai for everything else, including Bedrock, Azure and an unset value. That mirrors the handler's own model resolution.

Other changes

• Cached tokens are read from usage_metadata.input_token_details and reported per turn, not added to the input figure, which LangChain already reports inclusive of them.
• Finish reasons go through the shared LangChain helper rather than being dropped, so a turn that stopped to call a tool is distinguishable from one that finished.
• The streaming path gets a finally, so a consumer that stops reading no longer leaves the root span unended and unexported.

The graph span is untouched. ld.ai.graph and its two attributes already matched the TypeScript SDK and are out of scope.

Breaking change

The span is renamed from langchain.agent 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. The oracle above (#36) needs all six.

Tests: 824 to 844.

---

Note

Overview
Replaces one flat langchain.agent span with the shared agent span tree: an invoke_agent root, one chat {model} child per model turn, and sibling execute_tool {name} spans per tool call. Span bookkeeping moves into a new spans.py module driven by LangChain's callback protocol.

Breaking changes: the root span is renamed from langchain.agent to invoke_agent; gen_ai.system is now always langchain (with a new binary gen_ai.provider.name of anthropic or openai); prompt/completion content is off by default and requires capture_content=True.

Also adds a streaming finally so abandoned consumers still end and export every open span (marked abandoned, not ERROR), reports per-turn finish reasons and cache token details, and rewrites telemetry tests against a real LangGraph agent.

^{Reviewed by Cursor Bugbot for commit 65fc5f8. 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]

Zero tokens dropped in usage fallback

Low Severity

extract_llm_usage maps llm_output token fields with or, so a real 0 for prompt_tokens or completion_tokens is treated as missing. When both are zero, the result becomes all-None, lang_chain_span_usage returns None, and RunUsage never marks the turn as reported even though the provider sent an empty bag.

 

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

[apucacao]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ 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 65fc5f8. Configure here.}

[cursor]

Usage recorded after content capture

Medium Severity

In on_llm_end, output content is written before usage is extracted and added to run_usage. If content serialization raises with capture_content=True, the turn’s tokens never reach the run accumulator, so the failure path’s root span omits spend that was already billed.

 

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