Skip to content

context

agent_cover.context

Context management utilities for tracking Agent execution scope.

This module provides the mechanism to distinguish between: 1. Test Logic: Code running in your test function (setup, assertions). 2. Agent Logic: Code running inside the agent's execution loop.

It utilizes contextvars to ensure async-safety. This means even if multiple agents run in parallel (e.g., pytest-xdist or asyncio.gather), the coverage tracking remains isolated and accurate for each execution flow.

🔗 Architectural Relationships

To ensure accurate coverage metrics without false positives, different instrumentation components interact with this manager in specific ways:

1. Scope Providers (The Activators)
  • Agents: These components act as the entry point. They call set_active(True) to signal that the "Agent Logic" loop has started.
2. Scope Consumers (The Gatekeepers)
  • Tools & Prompts: These objects are ambiguous—they can be executed by the agent or manually by your test setup code (e.g., formatting a prompt to assert against a string).
  • Behavior: They explicitly check this manager. If is_active() returns False, they ignore the execution to prevent polluting the coverage report with test setup data.
3. Context-Agnostic Components (The Bypassers)
  • LLM Providers, Callbacks, PromptFlow: These components do not check this context.
  • Reason: Their execution implies inherent relevance.
    • An LLM Call is an expensive I/O operation representing the agent's output/decision.
    • Framework Callbacks and PromptFlow internals are structurally bound to the framework's lifecycle. Therefore, they are tracked unconditionally, regardless of the context state.

Classes

AgentContextManager

Manages the execution context using a thread-safe/async-safe ContextVar.

This manager acts as a switch. When an agent starts (e.g. agent.invoke()), the instrumentor calls set_active(True). Only when this switch is True does AgentCover record executions.

This prevents false positives, such as recording an LLM call made during test setup as "Agent Coverage".

Attributes:

Name Type Description
_var

A contextvars.ContextVar that stores the boolean state of the agent context (defaults to False).

Methods:

Name Description
set_active

Sets the agent context to the specified boolean value.
reset

Resets the agent context to its previous state.
is_active

Returns whether the agent context is currently active.
Source code in src/agent_cover/context.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class AgentContextManager:
    """Manages the execution context using a thread-safe/async-safe ContextVar.

    This manager acts as a switch. When an agent starts (e.g. `agent.invoke()`),
    the instrumentor calls `set_active(True)`. Only when this switch is True
    does AgentCover record executions.

    This prevents false positives, such as recording an LLM call made during
    test setup as "Agent Coverage".

    Attributes:
        _var: A contextvars.ContextVar that stores the boolean state of the
            agent context (defaults to False).

    Methods:
        set_active(active): Sets the agent context to the specified boolean value.
        reset(token): Resets the agent context to its previous state.
        is_active(): Returns whether the agent context is currently active.
    """

    def __init__(self):
        """Initializes a new AgentContextManager instance."""
        # contextvars.ContextVar to store the agent context state.
        # Defaults to False (not in agent context).
        self._var = contextvars.ContextVar("agent_context", default=False)

    def set_active(self, active: bool) -> contextvars.Token:
        """Sets the agent context to active or inactive.

        Args:
            active: True to activate the agent context, False to deactivate.

        Returns:
            A contextvars.Token that can be used to reset the context to its
            previous state.
        """
        return self._var.set(active)

    def reset(self, token: contextvars.Token):
        """Resets the agent context to its previous state using a token.

        Args:
            token: The token returned by `set_active()` used to restore the
                context.
        """
        self._var.reset(token)

    def is_active(self) -> bool:
        """Checks if the agent context is currently active.

        Returns:
            True if the agent context is active, False otherwise.
        """
        return self._var.get()
Functions
__init__()

Initializes a new AgentContextManager instance.

Source code in src/agent_cover/context.py 
57
58
59
60
61
def __init__(self):
    """Initializes a new AgentContextManager instance."""
    # contextvars.ContextVar to store the agent context state.
    # Defaults to False (not in agent context).
    self._var = contextvars.ContextVar("agent_context", default=False)
is_active()

Checks if the agent context is currently active.

Returns:

Type Description
bool

True if the agent context is active, False otherwise.
Source code in src/agent_cover/context.py 
84
85
86
87
88
89
90
def is_active(self) -> bool:
    """Checks if the agent context is currently active.

    Returns:
        True if the agent context is active, False otherwise.
    """
    return self._var.get()
reset(token)

Resets the agent context to its previous state using a token.

Parameters:

Name Type Description Default
token Token

The token returned by set_active() used to restore the context.

 required
Source code in src/agent_cover/context.py 
75
76
77
78
79
80
81
82
def reset(self, token: contextvars.Token):
    """Resets the agent context to its previous state using a token.

    Args:
        token: The token returned by `set_active()` used to restore the
            context.
    """
    self._var.reset(token)
set_active(active)

Sets the agent context to active or inactive.

Parameters:

Name Type Description Default
active bool

True to activate the agent context, False to deactivate.

 required

Returns:

Type Description
Token

A contextvars.Token that can be used to reset the context to its
Token

previous state.
Source code in src/agent_cover/context.py 
63
64
65
66
67
68
69
70
71
72
73
def set_active(self, active: bool) -> contextvars.Token:
    """Sets the agent context to active or inactive.

    Args:
        active: True to activate the agent context, False to deactivate.

    Returns:
        A contextvars.Token that can be used to reset the context to its
        previous state.
    """
    return self._var.set(active)

Functions

get_global_context_manager()

Retrieves the global AgentContextManager instance.

This function is provided for backward compatibility and allows accessing the default context manager instance.

Returns:

Type Description
AgentContextManager

The global AgentContextManager singleton instance.
Source code in src/agent_cover/context.py 
139
140
141
142
143
144
145
146
147
148
def get_global_context_manager() -> AgentContextManager:
    """Retrieves the global AgentContextManager instance.

    This function is provided for backward compatibility and allows
    accessing the default context manager instance.

    Returns:
        The global AgentContextManager singleton instance.
    """
    return _global_context_manager

is_in_agent_context()

Checks if the global agent context is currently active.

This function is provided for backward compatibility and uses the default global context manager instance.

Returns:

Type Description
bool

True if the agent context is active, False otherwise.
Source code in src/agent_cover/context.py 
127
128
129
130
131
132
133
134
135
136
def is_in_agent_context() -> bool:
    """Checks if the global agent context is currently active.

    This function is provided for backward compatibility and uses the
    default global context manager instance.

    Returns:
        True if the agent context is active, False otherwise.
    """
    return _global_context_manager.is_active()

reset_agent_context(token)

Resets the global agent context to its previous state.

This function is provided for backward compatibility and uses the default global context manager instance.

Parameters:

Name Type Description Default
token Token

The token returned by set_agent_context() to reset the context.

 required
Source code in src/agent_cover/context.py 
115
116
117
118
119
120
121
122
123
124
def reset_agent_context(token: contextvars.Token):
    """Resets the global agent context to its previous state.

    This function is provided for backward compatibility and uses the
    default global context manager instance.

    Args:
        token: The token returned by `set_agent_context()` to reset the context.
    """
    _global_context_manager.reset(token)

set_agent_context(active)

Sets the global agent context to active or inactive.

This function is provided for backward compatibility and uses the default global context manager instance.

Parameters:

Name Type Description Default
active bool

True to activate the agent context, False to deactivate.

 required

Returns:

Type Description
Token

A contextvars.Token that can be used to reset the context.
Source code in src/agent_cover/context.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
def set_agent_context(active: bool) -> contextvars.Token:
    """Sets the global agent context to active or inactive.

    This function is provided for backward compatibility and uses the
    default global context manager instance.

    Args:
        active: True to activate the agent context, False to deactivate.

    Returns:
        A contextvars.Token that can be used to reset the context.
    """
    return _global_context_manager.set_active(active)