v0.3 Documentation Update (#422)

ultmaster · web-flow · commit 22b80b38bf75 · 2025-12-18T01:12:50.000+08:00
diff --git a/agentlightning/emitter/object.py b/agentlightning/emitter/object.py
@@ -40,7 +40,7 @@ def emit_object(object: Any, attributes: Optional[Dict[str, Any]] = None, propag
     if propagate:
         tracer = get_active_tracer()
         if tracer is None:
-            raise RuntimeError("No active tracer found. Cannot emit annotation span.")
+            raise RuntimeError("No active tracer found. Cannot emit object span.")
     else:
         # Do not actually propagate to any store or tracer backend.
         tracer = DummyTracer()
diff --git a/agentlightning/litagent/litagent.py b/agentlightning/litagent/litagent.py
@@ -198,6 +198,7 @@ def rollout(self, task: T, resources: NamedResources, rollout: Rollout) -> Rollo
             * `float` representing the final reward.
             * `List[ReadableSpan]` with OpenTelemetry spans.
             * `List[Span]` with Agent Lightning spans.
+            * `List[SpanCoreFields]` with Agent Lightning spans.
         """
         raise NotImplementedError("Agents must implement the `rollout` method.")
 
diff --git a/agentlightning/utils/id.py b/agentlightning/utils/id.py
@@ -7,4 +7,12 @@
 
 
 def generate_id(length: int) -> str:
+    """Generate a random ID of the given length.
+
+    Args:
+        length: The length of the ID to generate.
+
+    Returns:
+        A random ID of the given length.
+    """
     return hashlib.sha1(uuid.uuid4().bytes).hexdigest()[:length]
diff --git a/agentlightning/utils/otel.py b/agentlightning/utils/otel.py
@@ -38,6 +38,11 @@
     "filter_and_unflatten_attributes",
     "flatten_attributes",
     "unflatten_attributes",
+    "sanitize_attribute_value",
+    "sanitize_attributes",
+    "sanitize_list_attribute_sanity",
+    "check_attributes_sanity",
+    "format_exception_attributes",
 ]
 
 T_SpanLike = TypeVar("T_SpanLike", bound=SpanLike)
diff --git a/agentlightning/utils/system_snapshot.py b/agentlightning/utils/system_snapshot.py
@@ -13,6 +13,14 @@
 
 
 def system_snapshot(include_gpu: bool = False) -> Dict[str, Any]:
+    """Capture a snapshot of the system's hardware and software information.
+
+    Args:
+        include_gpu: Whether to include GPU information.
+
+    Returns:
+        A dictionary containing the system's hardware and software information.
+    """
     # CPU
     cpu = {
         "cpu_name": platform.processor(),
diff --git a/docs/assets/dashboard-page-rollouts.png b/docs/assets/dashboard-page-rollouts.png
diff --git a/docs/assets/dashboard-page-traces.png b/docs/assets/dashboard-page-traces.png
diff --git a/docs/how-to/examples-catalog.md b/docs/how-to/examples-catalog.md
@@ -62,14 +62,6 @@
 
     [:octicons-repo-24: Browse source]({{ src("examples/rag") }})
 
--   :material-magnify:{ .lg .middle } __Search-R1 RL__
-
-    ---
-
-    Reproduction of the Search-R1 workflow that prepares its own retrieval backend, runs the rollout script, and coordinates GRPO-style training without extra orchestration layers (last validated on v0.1.x).
-
-    [:octicons-repo-24: Browse source]({{ src("examples/search_r1") }})
-
 -   :material-database:{ .lg .middle } __Spider SQL agent__
 
     ---
diff --git a/docs/how-to/train-sql-agent.md b/docs/how-to/train-sql-agent.md
@@ -1,6 +1,6 @@
 # Train SQL Agent with Agent-lightning and VERL
 
-This walkthrough builds upon the **Agent-lightning v0.2 SQL Agent** example and explains how the system components integrate: a **LangGraph-based SQL agent** wrapped as a [`LitAgent`][agentlightning.LitAgent], the **[`VERL`][agentlightning.algorithm.verl.VERL] reinforcement learning (RL) algorithm**, and the **[`Trainer`][agentlightning.Trainer]**, which coordinates both training and debugging.
+This walkthrough builds upon the **Agent-lightning SQL Agent** example and explains how the system components integrate: a **LangGraph-based SQL agent** wrapped as a [`LitAgent`][agentlightning.LitAgent], the **[`VERL`][agentlightning.algorithm.verl.VERL] reinforcement learning (RL) algorithm**, and the **[`Trainer`][agentlightning.Trainer]**, which coordinates both training and debugging.
 
 The command-line interface in [`examples/spider/train_sql_agent.py`]({{ src("examples/spider/train_sql_agent.py") }}) provides a complete runnable example. However, this document focuses on understanding the underlying architecture so you can effectively adapt the workflow to your own agents.
 
diff --git a/docs/reference/internal.md b/docs/reference/internal.md
@@ -54,56 +54,6 @@
 
 ::: agentlightning.tracer.otel.LightningSpanProcessor
 
-## Utilities
-
-::: agentlightning.utils.metrics.MetricsBackend
-
-::: agentlightning.utils.metrics.ConsoleMetricsBackend
-
-::: agentlightning.utils.metrics.PrometheusMetricsBackend
-
-::: agentlightning.utils.metrics.MultiMetricsBackend
-
-::: agentlightning.utils.metrics.setup_multiprocess_prometheus
-
-::: agentlightning.utils.metrics.get_prometheus_registry
-
-::: agentlightning.utils.metrics.shutdown_metrics
-
-::: agentlightning.utils.server_launcher.PythonServerLauncher
-
-::: agentlightning.utils.server_launcher.PythonServerLauncherArgs
-
-::: agentlightning.utils.server_launcher.LaunchMode
-
-::: agentlightning.utils.otel.full_qualified_name
-
-::: agentlightning.utils.otel.get_tracer_provider
-
-::: agentlightning.utils.otel.get_tracer
-
-::: agentlightning.utils.otel.make_tag_attributes
-
-::: agentlightning.utils.otel.extract_tags_from_attributes
-
-::: agentlightning.utils.otel.make_link_attributes
-
-::: agentlightning.utils.otel.query_linked_spans
-
-::: agentlightning.utils.otel.extract_links_from_attributes
-
-::: agentlightning.utils.otel.filter_attributes
-
-::: agentlightning.utils.otel.filter_and_unflatten_attributes
-
-::: agentlightning.utils.otel.flatten_attributes
-
-::: agentlightning.utils.otel.unflatten_attributes
-
-::: agentlightning.utils.otlp.handle_otlp_export
-
-::: agentlightning.utils.otlp.spans_from_proto
-
 ## Deprecated APIs
 
 ::: agentlightning.emitter.reward.reward
diff --git a/docs/reference/runner.md b/docs/reference/runner.md
@@ -27,3 +27,5 @@
 ::: agentlightning.get_active_tracer
 
 ::: agentlightning.clear_active_tracer
+
+::: agentlightning.tracer.weave.WeaveTracer
diff --git a/docs/reference/semconv.md b/docs/reference/semconv.md
@@ -0,0 +1,3 @@
+# Semantic Conventions
+
+::: agentlightning.semconv
diff --git a/docs/reference/types.md b/docs/reference/types.md
@@ -86,10 +86,6 @@
 
 ::: agentlightning.SpanRecordingContext
 
-## Semantic Conventions
-
-::: agentlightning.semconv
-
 ## Environment Variables
 
 ::: agentlightning.LightningEnvVar
diff --git a/docs/reference/utilities.md b/docs/reference/utilities.md
@@ -0,0 +1,75 @@
+# Utility References
+
+## ID
+
+::: agentlightning.utils.id.generate_id
+
+## Metrics
+
+::: agentlightning.utils.metrics.MetricsBackend
+
+::: agentlightning.utils.metrics.ConsoleMetricsBackend
+
+::: agentlightning.utils.metrics.PrometheusMetricsBackend
+
+::: agentlightning.utils.metrics.MultiMetricsBackend
+
+::: agentlightning.utils.metrics.setup_multiprocess_prometheus
+
+::: agentlightning.utils.metrics.get_prometheus_registry
+
+::: agentlightning.utils.metrics.shutdown_metrics
+
+## Server Launcher
+
+::: agentlightning.utils.server_launcher.PythonServerLauncher
+
+::: agentlightning.utils.server_launcher.PythonServerLauncherArgs
+
+::: agentlightning.utils.server_launcher.LaunchMode
+
+## OpenTelemetry
+
+::: agentlightning.utils.otel.full_qualified_name
+
+::: agentlightning.utils.otel.get_tracer_provider
+
+::: agentlightning.utils.otel.get_tracer
+
+::: agentlightning.utils.otel.make_tag_attributes
+
+::: agentlightning.utils.otel.extract_tags_from_attributes
+
+::: agentlightning.utils.otel.make_link_attributes
+
+::: agentlightning.utils.otel.query_linked_spans
+
+::: agentlightning.utils.otel.extract_links_from_attributes
+
+::: agentlightning.utils.otel.filter_attributes
+
+::: agentlightning.utils.otel.filter_and_unflatten_attributes
+
+::: agentlightning.utils.otel.flatten_attributes
+
+::: agentlightning.utils.otel.unflatten_attributes
+
+::: agentlightning.utils.otel.sanitize_attribute_value
+
+::: agentlightning.utils.otel.sanitize_attributes
+
+::: agentlightning.utils.otel.sanitize_list_attribute_sanity
+
+::: agentlightning.utils.otel.check_attributes_sanity
+
+::: agentlightning.utils.otel.format_exception_attributes
+
+## OTLP
+
+::: agentlightning.utils.otlp.handle_otlp_export
+
+::: agentlightning.utils.otlp.spans_from_proto
+
+## System Snapshot
+
+::: agentlightning.utils.system_snapshot.system_snapshot
diff --git a/docs/tutorials/debug.md b/docs/tutorials/debug.md
@@ -2,6 +2,42 @@
 
 When you train your own agent with Agent-lightning, most failures surface because the agent logic is brittle or simply incorrect. Debugging becomes easier when you peel back the stack: start by driving the rollout logic on its own, dry-run the trainer loop, and only then bring the full algorithm and runner topology online. The [`examples/apo/apo_debug.py`]({{ src("examples/apo/apo_debug.py") }}) script demonstrates these techniques; this guide expands on each approach and helps you decide when to reach for them.
 
+## Debugging with Dashboard
+
+When you launch an experiment with [`Trainer.fit`][agentlightning.Trainer.fit] or start an isolated store via [`agl store`](../reference/cli.md), the terminal prints a message similar to:
+
+```text
+INFO     Agent-lightning dashboard will be available at http://192.168.0.107:4747
+```
+
+Visit that URL, and you will see the Agent-lightning dashboard:
+
+![Dashboard](../assets/dashboard-page-rollouts.png)
+
+The dashboard surfaces everything stored inside [the store](../deep-dive/store.md). Because the store mediates interactions between algorithms and runners, inspecting it often reveals which side is causing issues such as stale rollouts, unresponsive workers, or empty traces.
+
+For example, the VERL algorithm may receive no token IDs and emit `cannot reshape tensor of 0 elements into shape [1, 0, -1, 128] because the unspecified dimension size -1 can be any value and is ambiguous` ([Issue #50](https://github.com/microsoft/agent-lightning/issues/50), [Issue #76](https://github.com/microsoft/agent-lightning/issues/76)). Several scenarios can produce that error: the runner might not produce trace spans at all, it might produce spans without token IDs, or the IDs may be present but formatted incorrectly. Inspecting the dashboard traces helps you pinpoint which condition applies.
+
+![Dashboard Traces Page](../assets/dashboard-page-traces.png)
+
+By checking whether the trace span is empty and whether token IDs appear in the span attributes, you can narrow the issue to either the runner (agent) side or the algorithm side. Then apply the techniques below to debug the faulty component.
+
+## Debug-level Logging
+
+Starting from v0.3, detailed signals such as store server access logs, runner lifecycle logs, and span payloads only appear when the log level is `DEBUG` so the default output stays readable. Enable debug-level logging by adding the following snippet near the top of your script:
+
+```python
+import agentlightning as agl
+
+agl.setup_logging("DEBUG")
+```
+
+Set the log level on every process if your setup involves multiple workers. For example, when [running stores in isolation][debug-with-external-store], configure the store process explicitly:
+
+```bash
+agl store --port 4747 --log-level DEBUG
+```
+
 ## Using [`Runner`][agentlightning.Runner] in Isolation
 
 [`Runner`][agentlightning.Runner] is a long-lived worker that wraps your [`LitAgent`][agentlightning.LitAgent], coordinates tracing, and talks to the [`LightningStore`][agentlightning.LightningStore]. In typical training flows the trainer manages runners for you, but being able to spin one up manually is invaluable while debugging.
@@ -255,6 +291,8 @@ In a separate terminal, start the store:
 agl store --port 4747
 ```
 
+Add `--log-level DEBUG` to the command to see the detailed logs.
+
 Then, in your training script, create a [`LightningStoreClient`][agentlightning.LightningStoreClient] and pass it to the trainer:
 
 ```python
diff --git a/docs/tutorials/emitter.md b/docs/tutorials/emitter.md
diff --git a/docs/tutorials/traces.md b/docs/tutorials/traces.md
diff --git a/docs/tutorials/write-agents.md b/docs/tutorials/write-agents.md
diff --git a/mkdocs.yml b/mkdocs.yml
