Package com.tnsai.annotations

Annotation Interface Variant

@Retention(RUNTIME)
@Target(METHOD)
public @interface Variant

Overrides the agent's default variant for a specific action.

Use this annotation when an action requires a different quality tier than the agent's default. For example, a simple utility action might use MINI for speed, while a critical analysis action might require HIGH for accuracy.

Agent Variants

Variant	Quality	Speed	Cost	Use Case
HIGH	Max	Slow	High	Critical tasks, code review, security
MEDIUM	Balanced	Normal	Medium	Regular development tasks
MINI	Basic	Fast	Low	Quick fixes, simple queries
AUTO	Adaptive	Adaptive	Optimal	Let framework decide

Usage

 // Agent default is MEDIUM, but this action always uses HIGH
 @ActionSpec(type = ActionType.LLM, description = "Security analysis")
 @Variant(AgentVariant.HIGH)
 public String analyzeSecurityRisks(String code) {
     return "Analyze security: " + code;
 }

 // Quick utility action uses MINI for speed
 @ActionSpec(type = ActionType.LOCAL, description = "Format text")
 @Variant(AgentVariant.MINI)
 public String formatText(String text) {
     return text.trim();
 }

 // Let the framework decide based on input complexity
 @ActionSpec(type = ActionType.LLM, description = "Code review")
 @Variant(value = AgentVariant.AUTO, reason = "Complexity varies by input size")
 public String reviewCode(String code) {
     return "Review: " + code;
 }
 

Inheritance

Actions without @Variant use the agent's current variant. The @Variant annotation only affects the specific action it decorates.

Runtime Behavior

When an action with @Variant is executed:

1. Framework detects the variant override
2. Temporarily switches to the specified variant
3. Executes the action with variant-specific settings (model, tokens, timeout)
4. Restores the previous variant after completion

Author:

TnsAI Team

See Also:

• AgentVariant
• invalid reference

  Action

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
AgentVariant	value	The variant to use for this action.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
AgentVariant	fallback	Fallback variant if the primary variant is unavailable.
String	reason	Optional reason for using this variant.
boolean	recordStats	Whether to record variant usage for statistics.

Element Details

value

AgentVariant value

The variant to use for this action.

Returns:

the agent variant

reason

String reason

Optional reason for using this variant. Useful for documentation and debugging.

Returns:

explanation for variant choice

Default:

""

recordStats

boolean recordStats

Whether to record variant usage for statistics. When true, the framework tracks how often this variant is used.

Returns:

true to record usage statistics

Default:

true

fallback

AgentVariant fallback

Fallback variant if the primary variant is unavailable. The framework will try the fallback if the primary model is not accessible.

Returns:

fallback variant, or AUTO to let framework decide

Default:

MEDIUM