Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation structure for v0.3, reorganizing content into more focused sections and improving API reference organization. The changes move emitter documentation to a dedicated tutorial page, extract utilities and semantic conventions into separate reference pages, and enhance code documentation.
Key changes:
- Reorganized documentation navigation with dedicated pages for emitters, utilities, and semantic conventions
- Moved emitter content from write-agents.md to a new standalone emitter.md tutorial
- Enhanced utility functions with docstrings for better API documentation
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Updated navigation structure with new pages for emitters, semantic conventions, and utilities; renamed existing navigation items for consistency |
| docs/tutorials/write-agents.md | Removed emitter section and updated link to point to new standalone emitter documentation |
| docs/tutorials/emitter.md | New comprehensive tutorial covering emitter functions, operations, and span linking with detailed examples |
| docs/reference/utilities.md | New reference page documenting utility functions for ID generation, metrics, server launcher, OpenTelemetry, OTLP, and system snapshots |
| docs/reference/types.md | Removed semantic conventions section (moved to dedicated page) |
| docs/reference/semconv.md | New dedicated reference page for semantic conventions |
| docs/reference/internal.md | Removed utilities section (promoted to public reference page) |
| docs/how-to/examples-catalog.md | Removed outdated Search-R1 RL example |
| agentlightning/utils/system_snapshot.py | Added docstring to system_snapshot function |
| agentlightning/utils/otel.py | Added missing functions to all exports list |
| agentlightning/utils/id.py | Added docstring to generate_id function |
| agentlightning/emitter/object.py | Fixed error message to correctly reference "object span" instead of "annotation span" |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/tutorials/emitter.md
Outdated
|
|
||
| Agent-lightning provides an **emitter** module that allows you to record custom spans from within your agent's logic. Like many common operations (like LLM calls) that are automatically instrumented by [Tracer][agentlightning.Tracer], the emitter will also send a [Span][agentlightning.Span] that records an Agent-lightning-specific operation. Then algorithms can query and read those spans later. See [Working with Traces](./traces.md) for more details. | ||
|
|
||
| For multi-step routines (function calls, tools, or adapters) you can wrap code with [`operation`][agentlightning.operation], either as a decorator or a context manager,to capture inputs, outputs, and metadata on a dedicated [`operation`][agentlightning.operation] span. This makes it easier to correlate downstream annotations (like rewards or messages) with the higher-level work that produced them. |
There was a problem hiding this comment.
Missing space after comma in the sentence. Should be "context manager, to capture" instead of "context manager,to capture".
docs/tutorials/emitter.md
Outdated
|
|
||
| ### Operations | ||
|
|
||
| The [`operation`][agentlightning.operation] helper tracks logical units of work within your agent, capturing inputs, outputs, timing, and success/failure status. Unlike point-in-time emitters, operations create a span representing a time interval. Use operations for tool calls, multi-step workflows, debugging, and performance monitoring. [`operation][agentlightning.operation] can be used either as a decorator or a context manager. |
There was a problem hiding this comment.
Typo in the markdown reference. Missing closing bracket before the link reference. Should be "[operation][agentlightning.operation]" instead of "[`operation][agentlightning.operation]".
| from opentelemetry.semconv.attributes import server_attributes | ||
| from agentlightning import emit_annotation | ||
|
|
||
| emit_object({ |
There was a problem hiding this comment.
Incorrect function call: using emit_object but importing and intending to use emit_annotation. The code imports emit_annotation on line 60 but then calls emit_object on line 62. This should be emit_annotation to match the import statement.
mkdocs.yml
Outdated
| - Debug: tutorials/debug.md | ||
| - Work with Traces: tutorials/traces.md | ||
| - Use Emitters: tutorials/emitter.md |
There was a problem hiding this comment.
Inconsistent naming pattern: The navigation items use inconsistent verb forms. "Debug" and "Write Agents" are in imperative form, while "Work with Traces" and "Use Emitters" include prepositions. Consider either using "Debugging" (gerund) or ensuring all use the imperative form without prepositions (e.g., "Debug", "Trace", "Emit").
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 16 out of 18 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/tutorials/emitter.md
Outdated
| ```python | ||
| with agl.operation(tool_name="web_search") as op: | ||
| op.set_input(query="latest AI research", filters={"date": "2024"}) | ||
| results = search_web(query, filters) |
There was a problem hiding this comment.
The example has a logic error. Line 157 calls op.set_input(query="latest AI research", filters={"date": "2024"}) which sets keyword arguments, but line 158 tries to use query and filters as variables in search_web(query, filters). These variables are not defined in the local scope. Either define them before the operation context or use string literals in the function call to fix this example.
| results = search_web(query, filters) | |
| results = search_web("latest AI research", {"date": "2024"}) |
1 participant
Documents TBD: