feat(agentscope): support AgentScope v2

[sipercai]

Description

Fixes #207

This PR makes the AgentScope instrumentation version-aware and adds AgentScope v2 support while preserving the existing AgentScope v1 path.

The v1 monkey-patch implementation is kept behind lazy imports and continues to run for agentscope >= 1.0.0, < 2.0.0. AgentScope v2 uses the framework's Agent middleware hooks to emit LoongSuite GenAI telemetry for agent replies, model calls, and tool execution through opentelemetry.util.genai helpers.

It also adds a dedicated v2 tox environment with VCR-recorded e2e coverage for non-streaming, streaming, and concurrent Agent calls.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

• tox -e precommit
• uvx tox -c tox-loongsuite.ini -e py311-test-loongsuite-instrumentation-agentscopev2
• uvx tox -c tox-loongsuite.ini -e py311-test-loongsuite-instrumentation-agentscope-latest
• uvx tox -c tox-loongsuite.ini -e lint-loongsuite-instrumentation-agentscope

Does This PR Require a Core Repo Change?

• Yes. - Link to PR:
• No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added
• Documentation has been updated

[ralf0131]

Review by github-manager-bot

Summary

Makes the AgentScope instrumentor version-aware: detects agentscope major version via importlib.metadata, preserves the v1 monkey-patch path for agentscope >= 1.0.0, < 2.0.0, and adds v2 middleware-based instrumentation for agentscope >= 2.0.0. The v2 approach hooks into AgentScope's own middleware system (before_agent_reply, after_model_invoked, before_tool_execution, etc.) instead of monkey-patching.

Findings

• [Info] __init__.py:145-165 — _instrument_v1 correctly uses lazy imports (from ._wrapper import ...) inside the method, avoiding import errors when only v2 is installed. The del kwargs + self._agentscope_major tracking in _uninstrument ensures consistent teardown.
• [Info] _v2_middleware.py:54-79 — append_loongsuite_middleware and _append_once correctly handle both kwargs and positional args for the middlewares parameter. The _append_once guard prevents duplicate LoongSuite middleware instances if Agent.__init__ is called multiple times.
• [Info] _v2_middleware.py — The middleware class covers all telemetry signals: agent invocation (ENTRY/AGENT), LLM calls (LLM), tool execution (TOOL), and ReAct steps (STEP). The streaming first-token detection via _FIRST_TOKEN_EVENT_TYPES is a good approach.
• [Warning] _v2_middleware.py:118 — The AgentScopeV2Middleware constructor takes handler as a Callable[[], ExtendedTelemetryHandler]. This is a factory pattern to avoid capturing a stale handler reference. However, in _instrument_v2 (line 360), the handler is lambda: self._handler which captures self (the instrumentor instance). If _uninstrument is called and then _instrument is called again, the lambda will return the new self._handler. This is correct but worth documenting to prevent confusion.
• [Info] pyproject.toml — Adding packaging >= 18.0 as a runtime dependency for version parsing, and bumping vcrpy >= 8.1.1 for v2 test cassettes. The agentscope version constraint < 3.0.0 is forward-looking.
• [Info] Tests — VCR-recorded cassettes for non-streaming, streaming, and concurrent e2e tests. Good coverage.

LGTM. Clean, well-architected version-aware instrumentation with excellent test coverage.

---

Automated review by github-manager-bot