Metadata-Version: 2.4
Name: loongsuite-instrumentation-claude-agent-sdk
Version: 0.4.0
Summary: LoongSuite Claude Agent SDK instrumentation
Project-URL: Homepage, https://github.com/alibaba/loongsuite-python-agent/tree/main/instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk
Project-URL: Repository, https://github.com/alibaba/loongsuite-python-agent
Author-email: Shipeng Cai <caishipeng.csp@alibaba-inc.com>, OpenTelemetry Authors <cncf-opentelemetry-contributors@lists.cncf.io>
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: loongsuite-util-genai~=0.4.0
Requires-Dist: opentelemetry-api~=1.37
Requires-Dist: opentelemetry-instrumentation~=0.58b0
Requires-Dist: opentelemetry-semantic-conventions~=0.58b0
Provides-Extra: instruments
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'instruments'
Description-Content-Type: text/x-rst

LoongSuite Instrumentation for Claude Agent SDK
================================================

This library provides automatic instrumentation for the `Claude Agent SDK
<https://github.com/anthropics/claude-agent-sdk-python>`_, adding OpenTelemetry
tracing and metrics for agent conversations, LLM calls, and tool executions.

.. note::
   This package is currently in development and must be installed from source.
   PyPI release is planned for future versions.

Installation
------------

::

    pip install opentelemetry-distro opentelemetry-exporter-otlp
    opentelemetry-bootstrap -a install

    pip install claude-agent-sdk

    # Install this instrumentation
    pip install ./instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk

    # Note: This instrumentation uses ExtendedTelemetryHandler from opentelemetry-util-genai
    pip install ./util/opentelemetry-util-genai

Usage
-----

Auto-instrumentation
~~~~~~~~~~~~~~~~~~~~

Use the ``opentelemetry-instrument`` wrapper:

::

    opentelemetry-instrument \
        --traces_exporter console \
        --metrics_exporter console \
        python your_claude_agent_app.py

Manual Instrumentation
~~~~~~~~~~~~~~~~~~~~~~

::

    from opentelemetry.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor
    from claude_agent_sdk import query
    from claude_agent_sdk.types import ClaudeAgentOptions

    ClaudeAgentSDKInstrumentor().instrument()

    options = ClaudeAgentOptions(model="claude-3-5-sonnet-20241022", max_turns=5)
    
    async def run_agent():
        async for message in query(prompt="Hello!", options=options):
            print(message)

    ClaudeAgentSDKInstrumentor().uninstrument()

Configuration
-------------

Export to OTLP Backend
~~~~~~~~~~~~~~~~~~~~~~

::

    export OTEL_SERVICE_NAME=my-claude-agent-app
    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<trace_endpoint>
    export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=<metrics_endpoint>

    opentelemetry-instrument python your_app.py

Content Capture
~~~~~~~~~~~~~~~

Control message content capture using environment variables:

::

    # Enable experimental GenAI semantic conventions
    export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

    # Capture content in spans only
    export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

    # Capture content in events only
    export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=EVENT_ONLY

    # Capture in both spans and events
    export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT

    # Disable content capture (default)
    export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT

Using with Alibaba Cloud DashScope
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This instrumentation works with Alibaba Cloud's DashScope service via the
Anthropic-compatible API endpoint:

::

    import os
    
    # Set environment variables for DashScope
    os.environ["ANTHROPIC_BASE_URL"] = "https://dashscope.aliyuncs.com/apps/anthropic"
    os.environ["ANTHROPIC_API_KEY"] = "your-dashscope-api-key"

Supported Components
--------------------

- **Agent Sessions**: ``query`` function for conversational agent interactions
- **Tool Executions**: Automatic tracing via PreToolUse/PostToolUse hooks
- **Token Tracking**: Via MessageComplete hook
- **Context Compaction**: Via PreCompact hook

Visualization
-------------

Export telemetry data to:

- `Alibaba Cloud Managed Service for OpenTelemetry <https://www.aliyun.com/product/xtrace>`_
- Any OpenTelemetry-compatible backend (Jaeger, Zipkin, etc.)

Span Hierarchy
--------------

::

    invoke_agent (parent span)
      ├── User prompt event
      ├── execute_tool (child span)
      │   ├── gen_ai.tool.input.* attributes
      │   └── gen_ai.tool.response.* attributes
      ├── execute_tool (child span)
      │   └── ...
      └── Agent completed event

Examples
--------

See the `main README <https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md>`_ for complete usage examples.

License
-------

Apache License 2.0

References
----------

- `OpenTelemetry GenAI Semantic Conventions <https://opentelemetry.io/docs/specs/semconv/gen-ai/>`_
- `Claude Agent SDK <https://github.com/anthropics/claude-agent-sdk-python>`_
- `Alibaba Cloud DashScope Anthropic API <https://help.aliyun.com/zh/model-studio/anthropic-api-messages>`_

