Python: Add OpenTelemetry instrumentation to ClaudeAgent (#4278) (#4326)

* Python: Add OpenTelemetry instrumentation to ClaudeAgent (#4278)

Add inline telemetry to ClaudeAgent.run() so that enable_instrumentation()
emits invoke_agent spans and metrics. Covers both streaming and
non-streaming paths using the same observability helpers as
AgentTelemetryLayer. Adds 5 unit tests for telemetry behavior.

Co-Authored-By: amitmukh <amimukherjee@microsoft.com>

* Address PR review feedback for ClaudeAgent telemetry

- Add justification comment for private observability API imports
- Pass system_instructions to capture_messages for system prompt capture
- Use monkeypatch instead of try/finally for test global state isolation

Co-Authored-By: amitmukh <amitmukh@users.noreply.github.com>
Co-Authored-By: Claude <noreply@anthropic.com>

* Adopt AgentTelemetryLayer instead of inline telemetry

Restructure ClaudeAgent to inherit from AgentTelemetryLayer via a
_ClaudeAgentRunImpl mixin, eliminating duplicated telemetry code and
private API imports.

MRO: ClaudeAgent → AgentTelemetryLayer → _ClaudeAgentRunImpl → BaseAgent

- Remove inline _run_with_telemetry / _run_with_telemetry_stream methods
- Remove private observability helper imports (_capture_messages, etc.)
- Add default_options property mapping system_prompt → instructions
- Net -105 lines by reusing core telemetry layer

Co-Authored-By: amitmukh <amitmukh@users.noreply.github.com>
Co-Authored-By: Claude <noreply@anthropic.com>

* Fix mypy: align _ClaudeAgentRunImpl.run() signature with AgentTelemetryLayer.run()

Remove explicit `options` parameter from mixin's run() signature and
extract it from **kwargs to match AgentTelemetryLayer's signature.
Also align overload return types (ResponseStream, Awaitable) to match.

Co-Authored-By: Claude <noreply@anthropic.com>

* Introduce RawClaudeAgent following framework's RawAgent/Agent pattern

Replace private _ClaudeAgentRunImpl mixin with public RawClaudeAgent
class that contains all core logic (init, run, lifecycle, tools).
ClaudeAgent becomes a thin wrapper that adds AgentTelemetryLayer.

- RawClaudeAgent(BaseAgent): full implementation without telemetry
- ClaudeAgent(AgentTelemetryLayer, RawClaudeAgent): adds OTel tracing
- Export RawClaudeAgent from package __init__.py

Users who want to skip telemetry or provide their own can use
RawClaudeAgent directly.

Co-Authored-By: Claude <noreply@anthropic.com>

* Address review nits: trim RawClaudeAgent docstring, fix import paths

- Simplify RawClaudeAgent docstring to a single basic example (not the
  primary entry point for most users)
- Use agent_framework.anthropic import path in docstrings instead of
  direct agent_framework_claude path
- Add RawClaudeAgent to agent_framework.anthropic lazy re-exports

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Amit Mukherjee <amimukherjee@microsoft.com>
Co-authored-by: amitmukh <amitmukh@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Dmytro Struk <13853051+dmytrostruk@users.noreply.github.com>

python/packages/core/agent_framework/anthropic/__init__.py

@@ -11,6 +11,7 @@ Supported classes:
 - AnthropicChatOptions
 - ClaudeAgent
 - ClaudeAgentOptions
+- RawClaudeAgent
 """
 
 import importlib
@@ -21,6 +22,7 @@ _IMPORTS: dict[str, tuple[str, str]] = {
     "AnthropicChatOptions": ("agent_framework_anthropic", "agent-framework-anthropic"),
     "ClaudeAgent": ("agent_framework_claude", "agent-framework-claude"),
     "ClaudeAgentOptions": ("agent_framework_claude", "agent-framework-claude"),
+    "RawClaudeAgent": ("agent_framework_claude", "agent-framework-claude"),
 }