agentscope-otel

Python SDK for AgentScope -- AI Agent Observability.

Installation

pip install agentscope-otel

Quick Start

from agentscope_otel import AgentScope

# Initialize once at startup (3 lines!)
scope = AgentScope.init(
    endpoint="http://localhost:3001",
    project_id="my-project",
)

# Use decorators for automatic span management
@scope.wrap_agent("my-agent", agent_name="researcher", agent_task="Answer questions")
async def run_agent(question: str):
    # Nested tool call -- auto-linked via context propagation
    with scope.trace_tool("web-search") as span:
        results = await search(question)

    # LLM call with auto token tracking
    @scope.wrap_llm_call("generate", model="claude-sonnet-4-5")
    async def call_llm(prompt):
        return await llm.complete(prompt)  # should have input_tokens, output_tokens attrs

    return await call_llm(f"Summarize: {results}")

# Run and clean up
import asyncio
asyncio.run(run_agent("What is AgentScope?"))
scope.flush()

API

Initialization

scope = AgentScope.init(
    endpoint="http://localhost:3001",
    project_id="my-project",
    tenant_id="default",         # optional
    api_key="sk-...",            # optional
    service_name="my-service",   # optional
    debug=True,                  # optional
)

Decorators

@scope.wrap_agent("name", agent_name="...", agent_task="...")
@scope.wrap_tool("name", agent_name="...")
@scope.wrap_step("name")
@scope.wrap_llm_call("name", model="claude-sonnet-4-5")

Context Managers

with scope.trace_agent("name") as span:
    ...
with scope.trace_tool("name") as span:
    ...
with scope.trace_step("name") as span:
    ...

Manual Span Control

span = scope.create_agent_span("name", agent_name="...")
# ... work ...
span.end()

llm_span = scope.create_llm_span("name", model="claude-sonnet-4-5")
# ... call LLM ...
scope.end_llm_span(llm_span, LLMResult(input_tokens=100, output_tokens=50))

Cost Calculation

from agentscope_otel import calculate_cost, MODEL_PRICING

cost = calculate_cost("claude-sonnet-4-5", input_tokens=1000, output_tokens=500)

Supported Models

Span Types

• session -- Top-level session grouping
• agent_run -- Agent execution
• step -- Generic step within an agent
• tool_call -- Tool invocation
• llm_call -- LLM API call
• sub_agent -- Nested agent invocation

Example

A runnable quickstart is included in examples/quickstart.py:

python examples/quickstart.py

Requirements

• Python 3.10+
• OpenTelemetry Python SDK

License

MIT