Use decorators to track activities in your agent system
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 |
@tool | Track tool usage and cost in agent operations | TOOL span |
@guardrail | Track guardrail input and output | GUARDRAIL span |
The decorators create spans that form a hierarchy:
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.
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.
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:
The @workflow
decorator tracks a sequence of operations that work together:
Workflows help you organize related operations and see their collective performance.
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.
The @tool
decorator tracks tool usage within agent operations and supports cost tracking. It works with all function types: synchronous, asynchronous, generator, and async generator.
The tool decorator provides:
The @guardrail
decorator tracks guardrail input and output. You can specify the guardrail type ("input"
or "output"
) with the spec
parameter.
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"} |
Here’s a complete example using all the decorators together:
In this example:
@session
decorator wraps the entire interaction@agent
decorator defines multiple agent classes@workflow
decorator creates a workflow that coordinates agents@operation
and @task
decorators track individual operationsNote that LLM and TOOL spans are automatically created when you use compatible LLM libraries or tool integrations.
In the AgentOps dashboard, decorators create spans that appear in:
This visualization helps you understand the flow and performance of your agent system.
Use decorators to track activities in your agent system
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 |
@tool | Track tool usage and cost in agent operations | TOOL span |
@guardrail | Track guardrail input and output | GUARDRAIL span |
The decorators create spans that form a hierarchy:
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.
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.
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:
The @workflow
decorator tracks a sequence of operations that work together:
Workflows help you organize related operations and see their collective performance.
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.
The @tool
decorator tracks tool usage within agent operations and supports cost tracking. It works with all function types: synchronous, asynchronous, generator, and async generator.
The tool decorator provides:
The @guardrail
decorator tracks guardrail input and output. You can specify the guardrail type ("input"
or "output"
) with the spec
parameter.
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"} |
Here’s a complete example using all the decorators together:
In this example:
@session
decorator wraps the entire interaction@agent
decorator defines multiple agent classes@workflow
decorator creates a workflow that coordinates agents@operation
and @task
decorators track individual operationsNote that LLM and TOOL spans are automatically created when you use compatible LLM libraries or tool integrations.
In the AgentOps dashboard, decorators create spans that appear in:
This visualization helps you understand the flow and performance of your agent system.