[Enhancement]: Model DeepAgents orchestrator and local subagents as nested Relay Agent scopes

[bbednarski9]

Affected area

• Framework integrations
• Observability or exporters
• Documentation or examples

Problem

The maintained DeepAgents integration captures managed model and tool calls and emits DeepAgents configuration marks, but it does not create semantic Relay Agent scopes for the orchestrator or delegated local subagents. Consumers therefore cannot reconstruct the DeepAgents agent topology without application-specific instrumentation.

This is an enhancement to the maintained integration, not a pricing defect. Managed framework calls with preserved response model and usage metadata already support Relay pricing.

Verified behavior

• NemoRelayDeepAgentsMiddleware.before_agent emits configuration marks only; it does not open or close Relay scopes.
• The helper adds Relay middleware to caller-provided dictionary subagents, so their managed model and tool calls are captured, but the agent relationship is not represented as a semantic scope hierarchy.
• Existing LangChain callbacks create generic run scopes and already handle deferred LIFO closure for concurrent runs.
• DeepAgents supports declarative local subagents, compiled subagent runnables, and remote async subagents. The latter two have different instrumentation boundaries.

Proposed direction

Extend the DeepAgents integration so that:

• Each top-level DeepAgents invocation has an identifiable semantic Agent scope.
• Supported in-process declarative subagents appear as nested semantic Agent scopes with their configured name and role.
• Scope lifecycle uses the callback run lifecycle for normal completion and error handling, rather than relying solely on middleware before_agent / after_agent hooks.
• Existing DeepAgents marks remain configuration and milestone metadata; they do not substitute for scopes.
• Existing managed LLM and tool wrapping remains unchanged.

Runtime contract

• Cover synchronous and asynchronous in-process DeepAgents runs, including caller-provided dictionary subagents and the automatically created general-purpose subagent where identifiable.
• Preserve strict LIFO closure and correct parentage under nested or concurrent runs.
• Do not promise capture of internal LLM and tool calls for compiled subagent graphs unless those graphs are separately instrumented.
• Do not promise capture inside remote async subagent processes; document that they require Relay instrumentation in the remote graph or process.
• No public Relay API or pricing behavior needs to change.

Alternatives considered

• Application-specific custom middleware can create scopes today, but duplicates integration lifecycle logic and risks incorrect closure under error, interruption, or concurrency.
• Generic LangGraph callback scopes alone capture framework runs but do not reliably express the DeepAgents orchestrator/subagent semantic topology.
• Retaining configuration marks alone does not provide an ownership boundary for nested agent work.

Acceptance criteria

• E2E tests show nested scope topology for a top-level DeepAgents agent and supported local subagents.
• Model and tool events remain children of the intended semantic agent scope.
• Normal completion, error closure, and concurrent/nested runs maintain valid LIFO scope closure.
• Existing skill, subagent, and human-in-the-loop marks remain available.
• The DeepAgents guide documents the supported local boundary and the compiled/remote instrumentation boundary.