agentconnect.utils.interaction_control module

Interaction control for the AgentConnect framework.

This module provides rate limiting and interaction tracking for agents, including token-based rate limiting, automatic cooldown, and integration with LangChain and LangGraph.

class InteractionState(*values)

Bases: Enum

Enum for interaction states.

CONTINUE

Continue the interaction

STOP

Stop the interaction

WAIT

Wait before continuing the interaction

CONTINUE = 'continue'
STOP = 'stop'
WAIT = 'wait'
class RateLimitingCallbackHandler(max_tokens_per_minute=5500, max_tokens_per_hour=100000, cooldown_callback=None)

Bases: BaseCallbackHandler

Callback handler that implements rate limiting for LLM calls.

This handler tracks token usage and enforces rate limits for LLM calls, triggering cooldown periods when limits are reached.

Parameters:

  • max_tokens_per_minute (int)

  • max_tokens_per_hour (int)

  • cooldown_callback (Callable[[int], None] | None)

max_tokens_per_minute

Maximum tokens allowed per minute

max_tokens_per_hour

Maximum tokens allowed per hour

current_minute_tokens

Current token count for the minute

current_hour_tokens

Current token count for the hour

last_minute_reset

Timestamp of the last minute reset

last_hour_reset

Timestamp of the last hour reset

in_cooldown

Whether the handler is in cooldown

cooldown_until

Timestamp when cooldown ends

cooldown_callback

Optional callback function to call when cooldown is triggered

on_llm_start(serialized, prompts, **kwargs)

Handle LLM start event.

Parameters:

  • serialized (Dict[str, Any]) – Serialized LLM data

  • prompts (List[str]) – List of prompts

  • **kwargs (Any) – Additional arguments

Return type:

None

on_llm_end(response, **kwargs)

Handle LLM end event.

Parameters:

  • response – LLM response

  • **kwargs (Any) – Additional arguments

Return type:

None

on_chain_end(outputs, **kwargs)

Handle chain end event.

Parameters:

  • outputs (Dict[str, Any]) – Chain outputs

  • **kwargs (Any) – Additional arguments

Return type:

None

class TokenConfig(max_tokens_per_minute, max_tokens_per_hour, current_minute_tokens=0, current_hour_tokens=0, last_minute_reset=1743055959.313969, last_hour_reset=1743055959.3139696)

Bases: object

Configuration for token-based rate limiting.

Parameters:

  • max_tokens_per_minute (int)

  • max_tokens_per_hour (int)

  • current_minute_tokens (int)

  • current_hour_tokens (int)

  • last_minute_reset (float)

  • last_hour_reset (float)

max_tokens_per_minute

Maximum tokens allowed per minute

max_tokens_per_hour

Maximum tokens allowed per hour

current_minute_tokens

Current token count for the minute

current_hour_tokens

Current token count for the hour

last_minute_reset

Timestamp of the last minute reset

last_hour_reset

Timestamp of the last hour reset

max_tokens_per_minute: int
max_tokens_per_hour: int
current_minute_tokens: int = 0
current_hour_tokens: int = 0
last_minute_reset: float = 1743055959.313969
last_hour_reset: float = 1743055959.3139696
add_tokens(token_count)

Add tokens to the current count.

Parameters:

token_count (int) – Number of tokens to add

Return type:

None

get_cooldown_duration()

Get the cooldown duration in seconds if rate limits are exceeded.

Return type:

Optional[int]

Returns:

Cooldown duration in seconds, or None if no cooldown is needed

class InteractionControl(token_config, max_turns=20, current_turn=0, last_interaction_time=1743055959.3145032, _cooldown_callback=None, _conversation_stats=None)

Bases: object

High-level control for agent interactions.

This class provides rate limiting, turn tracking, and conversation statistics for agent interactions.

Parameters:
token_config

Configuration for token-based rate limiting

max_turns

Maximum number of turns in a conversation

current_turn

Current turn number

last_interaction_time

Timestamp of the last interaction

_cooldown_callback

Optional callback function to call when cooldown is triggered

_conversation_stats

Dictionary of conversation statistics

token_config: TokenConfig
max_turns: int = 20
current_turn: int = 0
last_interaction_time: float = 1743055959.3145032
__post_init__()

Initialize conversation stats dictionary.

async process_interaction(token_count, conversation_id=None)

Process an interaction and return the state.

Parameters:

  • token_count (int) – Number of tokens used in the interaction

  • conversation_id (Optional[str]) – Optional conversation ID for tracking stats

Return type:

InteractionState

Returns:

InteractionState indicating whether to continue, stop, or wait

set_cooldown_callback(callback)

Set a callback function to be called when cooldown is triggered.

Parameters:

callback (Callable[[int], None]) – Function that takes cooldown duration in seconds as argument

Return type:

None

reset_turn_counter()

Reset the turn counter to zero.

Return type:

None

get_conversation_stats(conversation_id=None)

Get statistics for a specific conversation or all conversations.

Parameters:

conversation_id (Optional[str]) – Optional ID of the conversation to get stats for

Return type:

Dict[str, Any]

Returns:

Dictionary of conversation statistics

get_callback_manager()

Create a callback manager with rate limiting for LangChain/LangGraph.

Return type:

CallbackManager

Returns:

CallbackManager with rate limiting callbacks

On this page
Edit on GitHub