aip-agents-binary 0.5.22__py3-none-any.whl → 0.5.24__py3-none-any.whl

aip_agents/utils/pii/pii_handler.pyi

@@ -1,96 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger import LoggerManager as LoggerManager
-from aip_agents.utils.pii.uuid_deanonymizer_mapping import UUIDDeanonymizerMapping as UUIDDeanonymizerMapping
-from enum import Enum
-from gllm_privacy.pii_detector import TextAnalyzer, TextAnonymizer
-from typing import Any
-
-TextAnalyzer = Any
-TextAnonymizer = Any
-GDPLabsNerApiRemoteRecognizer = Any
-
-class _Operation(str, Enum):
-    ANONYMIZE: str
-    DEANONYMIZE: str
-
-logger: Incomplete
-NER_API_URL_ENV_VAR: str
-NER_API_KEY_ENV_VAR: str
-NER_API_TIMEOUT: int
-EXCLUDED_ENTITIES: Incomplete
-DEFAULT_SUPPORTED_ENTITIES: Incomplete
-
-class ToolPIIHandler:
-    """Handles PII masking/demasking for tool calling.
-
-    Tag replacement based on runner-provided mappings always works. Optional
-    NER-powered masking/de-masking is only enabled when NER_API_URL and
-    NER_API_KEY environment variables are set.
-
-    Attributes:
-        flat_pii_mapping: Flat mapping from runner service (tag → value)
-        text_analyzer: GLLM Privacy TextAnalyzer instance
-        text_anonymizer: GLLM Privacy TextAnonymizer instance
-        enable_ner: Whether NER is enabled
-    """
-    flat_pii_mapping: dict[str, str]
-    enable_ner: bool
-    text_analyzer: TextAnalyzer | None
-    text_anonymizer: TextAnonymizer | None
-    def __init__(self, pii_mapping: dict[str, str] | None = None, ner_api_url: str | None = None, ner_api_key: str | None = None) -> None:
-        """Initialize PII handler (private - use create_if_enabled() instead).
-
-        Initializes GLLM Privacy components (TextAnalyzer, TextAnonymizer) if NER credentials
-        are provided. Creates dual recognizers for Indonesian and English languages.
-        Pre-loads any existing PII mappings into the anonymizer's internal state.
-
-        Args:
-            pii_mapping: Existing PII mapping from runner service (flat format: tag -> value)
-            ner_api_url: NER API endpoint URL
-            ner_api_key: NER API authentication key
-        """
-    @classmethod
-    def create_if_enabled(cls, pii_mapping: dict[str, str] | None = None) -> ToolPIIHandler | None:
-        """Create ToolPIIHandler when mappings or NER configuration exist.
-
-        Args:
-            pii_mapping: Existing PII mapping from runner service
-
-        Returns:
-            ToolPIIHandler instance when mapping or NER config is available, None otherwise
-        """
-    @classmethod
-    def create_mapping_only(cls, pii_mapping: dict[str, str] | None = None) -> ToolPIIHandler | None:
-        """Create ToolPIIHandler in mapping-only mode (no NER).
-
-        Args:
-            pii_mapping: Existing PII mapping from runner service
-
-        Returns:
-            ToolPIIHandler instance when mapping exists, None otherwise
-        """
-    def deanonymize_tool_args(self, args: dict[str, Any]) -> dict[str, Any]:
-        """Replace PII tags in tool arguments with real values.
-
-        Recursively processes dictionaries, lists, and strings to replace all PII tags
-        (e.g., '<EMAIL_1>') with their corresponding real values from flat_pii_mapping.
-
-        Args:
-            args: Tool arguments that may contain PII tags
-
-        Returns:
-            Arguments with tags replaced by real values
-        """
-    def anonymize_tool_output(self, output: Any) -> tuple[Any, dict[str, str]]:
-        """Mask PII values in tool output.
-
-        Handles string and dictionary outputs. For strings, uses two-phase anonymization:
-        first masks known PII, then detects new PII via NER. For dictionaries, recursively
-        processes all string values. Returns updated mapping with any newly discovered PII.
-
-        Args:
-            output: Tool output that may contain PII values (string, dict, or other)
-
-        Returns:
-            Tuple of (anonymized_output, updated_flat_pii_mapping)
-        """

aip_agents/utils/pii/pii_helper.pyi

@@ -1,78 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger import LoggerManager as LoggerManager
-from typing import Any
-
-logger: Incomplete
-
-def normalize_enable_pii(enable_pii: Any) -> bool | None:
-    """Normalize enable_pii value from agent configuration.
-
-    Args:
-        enable_pii: Raw enable_pii value from agent configuration.
-
-    Returns:
-        The normalized enable_pii flag when explicitly set (True/False), otherwise None.
-    """
-def add_pii_mappings(left: dict[str, str] | None, right: dict[str, str] | None) -> dict[str, str]:
-    """Reducer function to merge PII mappings from multiple sources.
-
-    This is a LangGraph reducer function that merges PII mappings from:
-    - Parent agent's initial mapping
-    - Tool outputs with newly discovered PII
-    - Subagent responses with their discovered PII
-
-    Args:
-        left: Existing PII mapping (or None)
-        right: New PII mapping to merge (or None)
-
-    Returns:
-        Merged PII mapping dictionary
-
-    Note:
-        - Right (new) mappings take precedence over left (existing)
-        - Handles None/non-dict cases gracefully
-        - Preserves all unique PII tags
-        - Returns empty dict if both inputs are None/empty
-    """
-def extract_pii_mapping_from_agent_response(result: Any) -> dict[str, str] | None:
-    """Extract PII mapping from subagent response.
-
-    Used by DelegationToolManager to propagate PII mappings from subagents
-    back to parent agents.
-
-    Args:
-        result: The result returned by the delegated agent
-
-    Returns:
-        PII mapping dictionary if found, None otherwise
-
-    Note:
-        - Checks if result is a dict
-        - Extracts 'full_final_state' from result
-        - Extracts 'pii_mapping' from full_final_state
-        - Validates mapping is a non-empty dict
-        - Returns None if any step fails
-    """
-def deanonymize_final_response_content(content: str, is_final_response: bool, metadata: dict[str, Any] | None) -> str:
-    """Deanonymize final response content using PII mapping from metadata.
-
-    Args:
-        content: Final response content that may contain PII tags.
-        is_final_response: Flag indicating whether this message is a final response.
-        metadata: Optional metadata dict (or event payload containing ``metadata``) with
-            ``pii_mapping`` tag-to-value mapping.
-
-    Returns:
-        Content string with PII tags replaced by real values when applicable.
-    """
-def anonymize_final_response_content(content: str, metadata: dict[str, Any] | None) -> str:
-    """Anonymize final response content using PII mapping from metadata.
-
-    Args:
-        content: Final response content that may contain real PII values.
-        metadata: Metadata dict (or event payload containing ``metadata``) with
-            ``pii_mapping`` tag-to-value mapping.
-
-    Returns:
-        Content string with real PII values replaced by their PII tags when mapping is present.
-    """

aip_agents/utils/pii/uuid_deanonymizer_mapping.pyi

@@ -1,73 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.constants import DEFAULT_PII_TAG_NAMESPACE as DEFAULT_PII_TAG_NAMESPACE
-from gllm_privacy.pii_detector.utils.deanonymizer_mapping import DeanonymizerMapping, MappingDataType
-from typing import Any
-
-MappingDataType = dict[str, dict[str, str]]
-
-class DeanonymizerMapping:
-    """Fallback deanonymizer mapping when optional dependency is missing.
-
-        This class exists only to keep the module importable when `gllm-privacy`
-        is not installed.
-        """
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        """Initialize the mapping.
-
-            Raises:
-                ImportError: Always raised because `gllm-privacy` is required.
-            """
-
-logger: Incomplete
-
-def format_operator_with_uuid(operator_name: str, uuid_suffix: str) -> str:
-    """Format the operator name with a UUID suffix.
-
-    Args:
-        operator_name: The operator name.
-        uuid_suffix: The UUID suffix to append.
-
-    Returns:
-        The formatted operator name with UUID suffix.
-    """
-
-class UUIDDeanonymizerMapping(DeanonymizerMapping):
-    """Class to store the deanonymizer mapping with UUID suffixes.
-
-    This class extends DeanonymizerMapping to use UUID suffixes instead of
-    sequential numbers for differentiating multiple entities of the same type.
-
-    Attributes:
-        mapping: The deanonymizer mapping.
-        skip_format_duplicates: Whether to skip formatting duplicated operators.
-        uuid_length: The length of the UUID suffix to use (default: 8).
-    """
-    mapping: Incomplete
-    skip_format_duplicates: Incomplete
-    uuid_length: Incomplete
-    def __init__(self, mapping: MappingDataType | None = None, skip_format_duplicates: bool = False, uuid_length: int = 8) -> None:
-        """Initialize UUIDDeanonymizerMapping.
-
-        Args:
-            mapping: The deanonymizer mapping. If None, creates an empty defaultdict(dict).
-            skip_format_duplicates: Whether to skip formatting duplicated operators.
-            uuid_length: The length of the UUID suffix to use (default: 8).
-        """
-    def update(self, new_mapping: MappingDataType, use_uuid_suffix: bool | None = None) -> None:
-        """Update the deanonymizer mapping with new values using UUID suffixes.
-
-        Duplicated values will not be added. If there are multiple entities of the same type,
-        the mapping will include a UUID suffix to differentiate them. For example, if there are
-        two names in the input text, the mapping will include NAME_<uuid1> and NAME_<uuid2>.
-
-        Args:
-            new_mapping: The new mapping to be added to the existing deanonymizer mapping.
-            use_uuid_suffix: Whether to apply UUID suffixes to keys.
-                If True, keys will always be formatted with UUID suffixes.
-                If False, keys will be used as-is without UUID formatting.
-                If None, behavior falls back to the instance configuration via
-                skip_format_duplicates (preserving existing behavior).
-
-        Returns:
-            None
-        """

aip_agents/utils/reference_helper.pyi

@@ -1,81 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger import get_logger as get_logger
-from aip_agents.utils.metadata_helper import MetadataFieldKeys as MetadataFieldKeys
-from gllm_core.schema import Chunk
-from langgraph.types import Command
-from typing import Any
-
-logger: Incomplete
-SAVE_OUTPUT_HISTORY_ATTR: str
-FORMAT_AGENT_REFERENCE: str
-
-def extract_references_from_tool(tool: Any, tool_output: Any) -> list[Chunk]:
-    """Extract reference data from tools that support it.
-
-    Extraction priority:
-    1. Direct tool references via _format_agent_reference (preferred)
-    2. Command.update references (fallback for delegation tools)
-
-    Args:
-        tool: The tool instance to extract references from
-        tool_output: The output from the tool execution
-    Returns:
-        List of deduplicated Chunk objects containing reference data
-
-    Note:
-        - Never raises exceptions; logs warnings for issues
-        - Direct tool references take precedence over Command references
-    """
-def extract_references_from_command_update(command: Command) -> list[Any]:
-    """Extract references from a Command object's update dictionary.
-
-    Args:
-        command: A Command object potentially containing references in its update dict.
-
-    Returns:
-        List of reference data (not yet validated/deduplicated)
-
-    Note:
-        - Never raises exceptions; logs warnings for malformed data
-        - Skips non-Chunk items with warning log
-    """
-def validate_references(references: list[Any]) -> list[Chunk]:
-    """Validate and deduplicate reference data.
-
-    Args:
-        references: List of reference data (expected to be Chunk objects).
-
-    Returns:
-        List of validated, deduplicated Chunk objects by content.
-    """
-def serialize_references_for_metadata(references: list[Any]) -> list[dict[str, Any]]:
-    """Serialize references for inclusion in A2A metadata.
-
-    Args:
-        references: List of reference objects (typically Chunk objects).
-
-    Returns:
-        List of serialized reference dictionaries.
-    """
-def add_references_chunks(left: list[Chunk], right: list[Chunk]) -> list[Chunk]:
-    """Reducer function to accumulate reference data from multiple tool calls.
-
-    This is a LangGraph reducer function that should be forgiving and handle
-    edge cases gracefully. Non-Chunk items are filtered out.
-
-    Args:
-        left: Existing list of reference chunks (or None/non-list)
-        right: New list of reference chunks to add (or None/non-list)
-
-    Returns:
-        Combined list of valid Chunk objects
-    """
-def extract_references_from_agent_response(result: Any) -> list[dict[str, Any]] | None:
-    """Extract references from agent response for delegation tools.
-
-    Args:
-        result: The result returned by the delegated agent.
-
-    Returns:
-        List of reference chunks if found, None otherwise.
-    """

aip_agents/utils/sse_chunk_transformer.pyi

@@ -1,166 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.schema.a2a import A2AEvent
-from collections.abc import AsyncGenerator
-from enum import StrEnum
-from typing import Any
-
-__all__ = ['SSEChunkTransformer', 'TaskState', 'ChunkStatus', 'ChunkReason', 'ChunkFieldKeys']
-
-class TaskState(StrEnum):
-    """Task state values for SSE chunks."""
-    WORKING: str
-    COMPLETED: str
-    FAILED: str
-
-class ChunkStatus(StrEnum):
-    """Status values for SSE chunks."""
-    SUCCESS: str
-    ERROR: str
-
-class ChunkReason(StrEnum):
-    """Reason codes for special chunk states."""
-    EMPTY_PAYLOAD: str
-
-class ChunkFieldKeys(StrEnum):
-    """Field name constants for SSE chunk structure."""
-    STATUS: str
-    TASK_STATE: str
-    CONTENT: str
-    EVENT_TYPE: str
-    FINAL: str
-    METADATA: str
-    TIMESTAMP: str
-    TASK_ID: str
-    CONTEXT_ID: str
-    ARTIFACTS: str
-    REASON: str
-
-class SSEChunkTransformer:
-    '''Transforms A2AEvent stream to SSE-compatible output.
-
-    This class converts events from arun_a2a_stream into the normalized dict format
-    matching A2AConnector.astream_to_agent output.
-
-    Lifecycle:
-        Single-stream instance. Must NOT be reused across concurrent streams.
-        Each arun_sse_stream call creates a fresh instance.
-
-    Attributes:
-        task_id: Optional task identifier for the stream.
-        context_id: Optional context identifier for the stream.
-
-    Example:
-        >>> transformer = SSEChunkTransformer(task_id="task-123")
-        >>> async for chunk in transformer.transform_stream(agent.arun_a2a_stream("query")):
-        ...     print(chunk)
-    '''
-    task_id: Incomplete
-    context_id: Incomplete
-    def __init__(self, task_id: str | None = None, context_id: str | None = None, pii_mapping: dict[str, str] | None = None) -> None:
-        """Initialize the transformer with optional task and context IDs.
-
-        Args:
-            task_id: Optional task identifier for the stream.
-            context_id: Optional context identifier for the stream.
-            pii_mapping: Optional PII mapping to inject into each chunk's metadata.
-        """
-    @staticmethod
-    def normalize_metadata_enums(data: Any) -> Any:
-        """Recursively convert enum keys/values to their string values.
-
-        This is a pure normalization utility that converts any enum instances
-        (MetadataFieldKeys, Kind, Status, etc.) to their .value strings.
-
-        Args:
-            data: Dict, list, or value that may contain enum keys/values.
-
-        Returns:
-            Normalized data with all enums converted to their .value strings.
-        """
-    @staticmethod
-    def normalize_event_type_value(event_type: Any) -> str | None:
-        """Convert A2AStreamEventType enum to string.
-
-        Args:
-            event_type: Event type (enum, string, or None).
-
-        Returns:
-            String value of the event type, or None if invalid.
-        """
-    @staticmethod
-    def create_artifact_hash(artifact: dict[str, Any]) -> str:
-        """Create a stable hash for artifact deduplication.
-
-        Uses name, content_type, mime_type, and file_data for hashing,
-        excluding artifact_id which may be randomly generated.
-
-        Args:
-            artifact: Artifact dict with name, content_type, mime_type, and optionally file_data.
-
-        Returns:
-            SHA256 hexdigest hash string for deduplication.
-        """
-    @staticmethod
-    def extract_tool_outputs(tool_calls: list[dict[str, Any]]) -> list[str]:
-        """Extract human-readable output strings from tool calls.
-
-        Args:
-            tool_calls: List of tool call dictionaries.
-
-        Returns:
-            List of human-readable output strings.
-        """
-    @staticmethod
-    def format_tool_output(output: Any, tool_name: str) -> str:
-        """Format a single tool output for display.
-
-        Args:
-            output: The tool output to format.
-            tool_name: The name of the tool.
-
-        Returns:
-            The formatted output string.
-        """
-    @staticmethod
-    def apply_hitl_content_override(content: str | None, event_type_str: str, metadata: dict[str, Any]) -> str | None:
-        """Apply HITL content override when HITL is active and tool results are available.
-
-        This method overrides the content with human-readable tool output when HITL
-        is active, matching A2AConnector behavior.
-
-        Args:
-            content: The original content/status message.
-            event_type_str: The type of event being processed (normalized string).
-            metadata: The metadata dictionary containing tool_info and hitl flag.
-
-        Returns:
-            The original content or human-readable tool output if HITL is active.
-        """
-    def transform_event(self, event: A2AEvent) -> dict[str, Any]:
-        """Transform a single A2AEvent to SSE chunk format.
-
-        Converts the A2AEvent structure to the normalized SSE chunk format,
-        relocating fields like tool_info and thinking_and_activity_info into
-        metadata, and normalizing enum values to strings.
-
-        Args:
-            event: Single A2AEvent dict from arun_a2a_stream.
-
-        Returns:
-            SSEChunk dict with normalized structure.
-        """
-    async def transform_stream(self, stream: AsyncGenerator[A2AEvent, None]) -> AsyncGenerator[dict[str, Any], None]:
-        """Transform A2AEvent stream to SSE-compatible chunks.
-
-        Wraps the input stream and transforms each event, handling artifact
-        deduplication and time tracking across the stream.
-
-        Args:
-            stream: Async generator yielding A2AEvent dicts.
-
-        Yields:
-            SSEChunk dicts with normalized structure.
-
-        Raises:
-            Exceptions from underlying stream propagate to caller.
-        """

aip_agents/utils/step_limit_manager.pyi

@@ -1,112 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.schema.step_limit import MaxDelegationDepthExceededError as MaxDelegationDepthExceededError, MaxStepsExceededError as MaxStepsExceededError, StepLimitConfig as StepLimitConfig, StepLimitErrorResponse as StepLimitErrorResponse, StepLimitErrorType as StepLimitErrorType
-from dataclasses import dataclass, field
-from typing import Any
-
-@dataclass
-class StepExecutionContext:
-    """Runtime context for tracking step execution and delegation depth.
-
-    Attributes:
-        current_step: Current step number (0-indexed).
-        delegation_depth: Current depth in delegation chain (0 for root agent).
-        remaining_step_budget: Steps remaining before limit is hit.
-        delegation_chain: List of agent names in the delegation chain.
-    """
-    current_step: int = ...
-    delegation_depth: int = ...
-    remaining_step_budget: int | None = ...
-    delegation_chain: list[str] = field(default_factory=list)
-
-class StepLimitManager:
-    """Manages step and delegation limit enforcement during agent execution.
-
-    This manager integrates with LangGraph's existing step mechanisms and adds
-    delegation depth tracking and budget propagation.
-
-    Attributes:
-        config: Step limit configuration.
-        context: Current execution context.
-    """
-    config: Incomplete
-    context: Incomplete
-    def __init__(self, config: StepLimitConfig | None = None, initial_delegation_depth: int = 0, parent_step_budget: int | None = None) -> None:
-        """Initialize step limit manager.
-
-        Args:
-            config: Optional step limit configuration. Uses defaults if None.
-            initial_delegation_depth: Starting delegation depth (from parent).
-            parent_step_budget: Remaining step budget inherited from parent agent.
-        """
-    def check_step_limit(self, agent_name: str = 'agent', count: int = 1) -> None:
-        """Check if taking 'count' steps would exceed limit.
-
-        Args:
-            agent_name: Name of the agent to identify in error message.
-            count: Number of steps to check (useful for parallel tool batches).
-
-        Raises:
-            MaxStepsExceededError: If max_steps limit is exceeded.
-        """
-    def check_delegation_depth(self, target_agent_name: str) -> None:
-        """Check if delegation to target agent would exceed depth limit.
-
-        Args:
-            target_agent_name: Name of the agent to delegate to.
-
-        Raises:
-            MaxDelegationDepthExceededError: If delegation depth limit exceeded.
-        """
-    def increment_step(self, count: int = 1) -> None:
-        """Increment step counter and update remaining budget.
-
-        Args:
-            count: Number of steps to consume (defaults to 1).
-        """
-    def get_child_budget(self, child_max_steps: int | None = None) -> int:
-        """Calculate step budget to allocate to child agent.
-
-        Algorithm:
-        1. If remaining_step_budget is None (root with no limit), use config.max_steps - 1
-        2. If remaining_step_budget <= 1, return 0 (no budget left for child)
-        3. Calculate child_budget = remaining_step_budget - 1 (reserve 1 for parent)
-        4. If child has own max_steps config, return min(child_budget, child.max_steps)
-        5. Otherwise return child_budget
-
-        Args:
-            child_max_steps: Optional child agent's own max_steps limit.
-
-        Returns:
-            Step budget for child agent, accounting for parent's continuation.
-            Returns 0 if no budget available for child.
-
-        Edge Cases:
-            - remaining=1: Returns 0 (parent needs the last step)
-            - remaining=None: Uses config.max_steps - 1
-            - child has own limit: Returns min(calculated_budget, child_limit)
-        """
-    def add_to_delegation_chain(self, agent_name: str) -> None:
-        """Add agent to delegation chain for tracking.
-
-        Args:
-            agent_name: Name of the agent being delegated to.
-        """
-    @classmethod
-    def from_state(cls, state: dict[str, Any], config: StepLimitConfig | None = None) -> StepLimitManager:
-        """Create manager from LangGraph state.
-
-        Args:
-            state: LangGraph agent state containing remaining_steps, etc.
-            config: Optional step limit configuration.
-
-        Returns:
-            Initialized step limit manager.
-        """
-    def set_context(self) -> None:
-        """Set context variables for downstream consumption (e.g. by delegation tools)."""
-    def to_state_update(self) -> dict[str, Any]:
-        """Convert current context to LangGraph state update.
-
-        Returns:
-            Dictionary of state fields to update.
-        """

aip_agents/utils/token_usage_helper.pyi

@@ -1,60 +0,0 @@
-from langchain_core.messages.ai import AIMessage, UsageMetadata
-from langchain_core.messages.tool import ToolMessage as ToolMessage
-from langgraph.types import Command
-from typing import Any
-
-USAGE_METADATA_KEY: str
-TOTAL_USAGE_KEY: str
-STEP_USAGE_KEY: str
-
-def add_usage_metadata(cur_accumulated_token_usage: UsageMetadata | None, new_token_usage: UsageMetadata | None) -> UsageMetadata | None:
-    """Reducer function to accumulate UsageMetadata across agent runs.
-
-    Args:
-        cur_accumulated_token_usage: The current accumulated token usage metadata.
-        new_token_usage: New token usage metadata to add.
-
-    Returns:
-        Accumulated usage metadata or None if both inputs are None.
-    """
-def extract_and_update_token_usage_from_ai_message(ai_message: AIMessage) -> dict[str, Any]:
-    """Extract token usage from AI message and prepare state update.
-
-    Args:
-        ai_message: The AI message containing usage metadata.
-
-    Returns:
-        Dictionary with accumulated_usage_metadata update if usage metadata is available.
-    """
-def extract_token_usage_from_tool_output(tool_output: Any) -> UsageMetadata | None:
-    """Extract token usage from various tool output formats.
-
-    Supports multiple tool output formats:
-    1. Dictionary with 'usage_metadata' field
-    2. Command with 'usage_metadata' attribute
-    3. Any object with 'usage_metadata' attribute
-
-    Args:
-        tool_output: The output from a tool execution.
-
-    Returns:
-        UsageMetadata if found, None otherwise.
-    """
-def extract_token_usage_from_command(command: Command) -> UsageMetadata | None:
-    """Extract token usage from Command object.
-
-    Args:
-        command: The Command object to extract token usage from.
-
-    Returns:
-        UsageMetadata if found, None otherwise.
-    """
-def extract_token_usage_from_agent_response(agent_response: dict[str, Any]) -> UsageMetadata | None:
-    """Extract accumulated token usage from agent response.
-
-    Args:
-        agent_response: The agent response to extract token usage from.
-
-    Returns:
-        UsageMetadata if found, None otherwise.
-    """