fix agentops and add docs

Author: ultmaster

agentlightning/instrumentation/agentops.py

@@ -28,6 +28,12 @@
 _original_handle_response: Callable[..., Any] | None = None
 
 
+def _unwrap_legacy_response(response: Any) -> Any:
+    if hasattr(response, "parse") and callable(response.parse):
+        return response.parse()
+    return response
+
+
 def _patch_new_agentops():
     import agentops.instrumentation.providers.openai.stream_wrapper
     import agentops.instrumentation.providers.openai.wrappers.chat
@@ -44,6 +50,11 @@ def _patch_new_agentops():
     @no_type_check
     def _handle_chat_attributes_with_tokens(args=None, kwargs=None, return_value=None, **kws):  # type: ignore
         attributes = _original_handle_chat_attributes(args=args, kwargs=kwargs, return_value=return_value, **kws)
+
+        # In some cases, response is a openai._legacy_response.LegacyAPIResponse (e.g., LiteLLM, or LangChain),
+        # This is created by client.with_raw_response.create()
+        return_value = _unwrap_legacy_response(return_value)
+
         if (
             return_value is not None
             and hasattr(return_value, "prompt_token_ids")
@@ -89,20 +100,6 @@ def _handle_chat_attributes_with_tokens(args=None, kwargs=None, return_value=Non
                         [logprob.model_dump() for logprob in first_choice.logprobs.refusal]
                     )
 
-        # For LiteLLM, response is a openai._legacy_response.LegacyAPIResponse
-        if (
-            return_value is not None
-            and hasattr(return_value, "http_response")
-            and return_value.http_response is not None
-            and hasattr(return_value.http_response, "json")
-        ):
-            json_data = return_value.http_response.json()
-            if isinstance(json_data, dict):
-                if json_data.get("prompt_token_ids") is not None:
-                    attributes["prompt_token_ids"] = list(json_data["prompt_token_ids"])
-                if json_data.get("response_token_ids") is not None:
-                    attributes["response_token_ids"] = list(json_data["response_token_ids"][0])
-
         return attributes
 
     agentops.instrumentation.providers.openai.wrappers.chat.handle_chat_attributes = _handle_chat_attributes_with_tokens

docs/how-to/train-sql-agent.md

@@ -264,7 +264,7 @@ dev_data = pd.read_parquet("data/test_dev_500.parquet").to_dict("records")[:10]
 trainer.dev(agent, dev_dataset=dev_data)
 ```
 
-Run this in a Python session or adapt your script to include a `--dev` flag. Once the spans appear healthy and the rewards are non-zero, switch back to [`trainer.fit(...)`][agentlightning.Trainer.fit] for full RL training.
+Run this in a Python session or adapt your script to include a `--dev` flag. Once the spans appear healthy and the rewards are non-zero, switch back to [`trainer.fit(...)`][agentlightning.Trainer.fit] for full RL training. See the [debugging tutorial](../tutorials/debug.md) for more tips on how to debug the agent.
 
 ## Running the Sample Code
 

docs/tutorials/debug.md

@@ -66,6 +66,48 @@ Swap in an [`AgentOpsTracer`][agentlightning.AgentOpsTracer] instead of [`OtelTr
 
     You can also call [`Runner.step`][agentlightning.Runner.step] to inject ad-hoc rollouts into a running store being used by another algorithm, so that the rollouts can be consumed by the algorithms. This is very recently known as the paradigm of ["online RL"](https://cursor.com/blog/tab-rl). At the moment, no algorithm in the [algorithm zoo](../algorithm-zoo/index.md) consumes externally generated rollouts, but the data flow is available there if you need it.
 
+## Debug with LLM Proxy
+
+If you are dealing with LLM optimization like Reinforcement Learning, we generally recommend using an online stable LLM service for your debugging purposes, like `openai/gpt-4.1-nano`. After the debugging is done, you can switch to a local training endpoint.
+
+However, if you want to use a local LLM features like [getting the token IDs](../deep-dive/serving-llm.md), you can also manually start a local vLLM server by:
+
+```bash
+vllm serve Qwen/Qwen2.5-0.5B-Instruct --port 8080
+```
+
+Then start the LLM proxy via the following script:
+
+```python
+import agentlightning as agl
+
+llm_proxy = agl.LLMProxy(
+    port=8081,
+    model_list=[
+        {
+            "model_name": "Qwen/Qwen2.5-0.5B-Instruct",
+            "litellm_params": {
+                "model": "hosted_vllm/Qwen/Qwen2.5-0.5B-Instruct",
+                "api_base": "http://localhost:8080/v1",
+            },
+        }
+    ],
+    store=agl.InMemoryLightningStore(),
+)
+
+llm_proxy.start()
+time.sleep(1000000)
+```
+
+You can now use the LLM proxy by specifying environment variables:
+
+```bash
+export OPENAI_API_BASE=http://localhost:8081/v1
+export OPENAI_API_KEY=dummy
+```
+
+You might see warnings about `Missing or invalid rollout_id, attempt_id, or sequence_id` in the LLM proxy logs. This is fine because you don't have a rollout and attempt yet when you are debugging. When you started the training, the algorithm will create the rollouts for you and the warnings will go away.
+
 ## Hook into Runner's Lifecycle
 
 [`Runner.run_context`][agentlightning.Runner.run_context] accepts a `hooks` argument so you can observe or augment lifecycle events without editing your agent. Hooks subclass [`Hook`][agentlightning.Hook] and can respond to four asynchronous callbacks: [`on_trace_start`][agentlightning.Hook.on_trace_start], [`on_rollout_start`][agentlightning.Hook.on_rollout_start], [`on_rollout_end`][agentlightning.Hook.on_rollout_end], and [`on_trace_end`][agentlightning.Hook.on_trace_end]. This is useful for:

examples/calc_x/train_calc_agent.py

@@ -31,12 +31,10 @@
 import argparse
 import os
 from datetime import datetime
-from importlib.metadata import version
 from typing import Any, Dict, Optional, cast
 
 from calc_agent import MathProblem, calc_agent
 from datasets import Dataset as HuggingFaceDataset
-from packaging import version as packaging_version
 
 import agentlightning as agl