alibaba / alibaba/loongsuite-python

AgentScope instrumentation should cap v1 and define v2 support strategy

Open
#207 1 comment 0 reactions 0 assignees View on GitHub
enhancement genai instrumentaion
Dominant language
Python
Stars
133
Forks
35
Avg merge
1d 12h
Merged PRs (30d)
5

Description

## Problem

`loongsuite-instrumentation-agentscope` currently declares `agentscope >= 1.0.0` without an upper bound. AgentScope has released `2.0.0` with `Requires-Python >=3.11`, so py311+ latest installs can resolve to v2 even though the current instrumentation targets v1 APIs.

The current instrumentation wraps v1 symbols such as `agentscope.agent.AgentBase`, `ReActAgent` hooks, `Toolkit.call_tool_function`, `TruncatedFormatterBase`, and `agentscope.tracing.*`. AgentScope v2 uses `agentscope.agent.Agent`, `reply/reply_stream`, middleware hooks, `Toolkit.call_tool`, and `agentscope.middleware._tracing.TracingMiddleware`; the top-level `agentscope.tracing` package is no longer present.

Current tests also import v1-only APIs, including `agentscope.tracing._trace`, so v2 can fail at import time or miss instrumentation coverage.

## Proposed Scope

1. Short-term: cap the existing v1 instrumentation to `agentscope >=1,<2` in package metadata and test requirements.
2. Add explicit test factors for AgentScope v1 and v2. v2 should run only on Python 3.11+.
3. Design v2 support as a middleware-first implementation instead of reusing v1 monkey patches directly.
4. Reuse `opentelemetry-util-genai` / `ExtendedTelemetryHandler` for LLM, agent, tool, embedding, content, token, error, TTFT, metrics, and ReActStep behavior. Framework-local code should only adapt AgentScope v2 objects and lifecycle hooks.
5. Evaluate duplicate-span behavior when users also enable AgentScope v2 native `TracingMiddleware`.

## Suggested v2 Contract Tests

- import smoke without `agentscope.tracing`
- agent reply/reply_stream span tree
- model call span attributes and token usage where available
- tool call spans and tool error handling
- content capture disabled/span/event modes
- error status and exception attributes
- ReAct reasoning/action step mapping if supported by stable v2 events
- concurrent agents/state isolation
- uninstrument restore
- coexistence with native `TracingMiddleware` without duplicate LoongSuite spans

Contributor guide

Open the contributing guide

Research direction

Start by inspecting the package metadata, current AgentScope instrumentation, and tests that import v1-only APIs such as agentscope.tracing._trace. Run the existing test suite against AgentScope v1, then define separate v1 and Python 3.11+ v2 factors. Done means v1 remains covered, v2 contract tests cover middleware behavior, and native TracingMiddleware does not create duplicate LoongSuite spans.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
ai, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.