Decorators
Use decorators to track activities in your agent system
Available Decorators
AgentOps provides the following decorators:
Decorator | Purpose | Creates |
---|---|---|
@session | Track an entire user interaction | SESSION span |
@agent | Track agent classes and their lifecycle | AGENT span |
@operation | Track discrete operations performed by agents | OPERATION span |
@workflow | Track a sequence of operations | WORKFLOW span |
@task | Track smaller units of work (similar to operations) | TASK span |
Decorator Hierarchy
The decorators create spans that form a hierarchy:
Using Decorators
@session
The @session
decorator tracks an entire user interaction from start to finish:
Each @session
function call creates a new session span that contains all the agents, operations, and workflows used during that interaction.
@agent
The @agent
decorator instruments a class to track its lifecycle and operations:
When an agent-decorated class is instantiated within a session, an AGENT span is created automatically.
@operation
The @operation
decorator tracks discrete functions performed by an agent:
Operations represent the smallest meaningful units of work in your agent system. Each operation creates an OPERATION span with:
- Inputs (function arguments)
- Output (return value)
- Duration
- Success/failure status
@workflow
The @workflow
decorator tracks a sequence of operations that work together:
Workflows help you organize related operations and see their collective performance.
@task
The @task
decorator is similar to @operation
but can be used for smaller units of work:
The @task
and @operation
decorators function identically (they are aliases in the codebase), and you can choose the one that best fits your semantic needs.
Decorator Attributes
You can pass additional attributes to decorators:
Common attributes include:
Attribute | Description | Example |
---|---|---|
name | Custom name for the span | name="weather_forecast" |
attributes | Dictionary of custom attributes | attributes={"model": "gpt-4"} |
Complete Example
Here’s a complete example using all the decorators together:
In this example:
- The
@session
decorator wraps the entire interaction - The
@agent
decorator defines multiple agent classes - The
@workflow
decorator creates a workflow that coordinates agents - The
@operation
and@task
decorators track individual operations - All spans are properly nested in the hierarchy
Note that LLM and TOOL spans are automatically created when you use compatible LLM libraries or tool integrations.
Best Practices
- Use @session for top-level functions that represent complete user interactions
- Apply @agent to classes that represent distinct components of your system
- Use @operation for significant functions that represent complete units of work
- Use @task for smaller functions that are part of larger operations
- Apply @workflow to methods that coordinate multiple operations
- Keep decorator nesting consistent with the logical hierarchy of your code
- Add custom attributes to provide additional context for analysis
- Use meaningful names for all decorated components
Dashboard Visualization
In the AgentOps dashboard, decorators create spans that appear in:
- Timeline View: Shows the execution sequence and duration
- Hierarchy View: Displays the parent-child relationships
- Detail Panels: Shows inputs, outputs, and attributes
- Performance Metrics: Tracks execution times and success rates
This visualization helps you understand the flow and performance of your agent system.