aip-agents-binary 0.6.2__py3-none-any.whl → 0.6.3__py3-none-any.whl

aip_agents/utils/langgraph/tool_managers/base_tool_manager.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.tools import BaseTool as BaseTool
+from typing import Any
+
+logger: Incomplete
+
+class BaseLangGraphToolManager(ABC):
+    """Base class for managing specialized tools in LangGraph agents.
+
+    This abstract base class provides a common interface for tool managers
+    that convert different types of capabilities into LangChain tools for
+    use in LangGraph agents.
+
+    The design follows a simple pattern:
+    1. Register resources (agents, cards, etc.)
+    2. Convert resources to LangChain tools
+    3. Provide access to created tools
+    """
+    created_tools: list[BaseTool]
+    def __init__(self) -> None:
+        """Initialize the tool manager."""
+    @abstractmethod
+    def register_resources(self, resources: list[Any]) -> list[BaseTool]:
+        """Register resources and convert them to LangChain tools.
+
+        Args:
+            resources: List of resources to convert to tools.
+
+        Returns:
+            List of created tools.
+        """
+    def get_tools(self) -> list[BaseTool]:
+        """Get all created tools.
+
+        Returns:
+            Copy of created tools list.
+        """
+    def clear_tools(self) -> None:
+        """Clear all created tools."""
+    @abstractmethod
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered resources.
+
+        Returns:
+            List of resource names.
+        """

aip_agents/utils/langgraph/tool_managers/delegation_tool_manager.pyi

@@ -0,0 +1,56 @@
+from _typeshed import Incomplete
+from aip_agents.agent.base_agent import BaseAgent as BaseAgent
+from aip_agents.schema.step_limit import MaxDelegationDepthExceededError as MaxDelegationDepthExceededError
+from aip_agents.types import A2AEvent as A2AEvent, A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils.artifact_helpers import extract_artifacts_from_agent_response as extract_artifacts_from_agent_response
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata_helper import MetadataFieldKeys as MetadataFieldKeys, get_next_step_number as get_next_step_number
+from aip_agents.utils.pii.pii_helper import anonymize_final_response_content as anonymize_final_response_content, extract_pii_mapping_from_agent_response as extract_pii_mapping_from_agent_response
+from aip_agents.utils.reference_helper import extract_references_from_agent_response as extract_references_from_agent_response
+from aip_agents.utils.step_limit_manager import StepLimitManager as StepLimitManager
+from aip_agents.utils.token_usage_helper import STEP_USAGE_KEY as STEP_USAGE_KEY, TOTAL_USAGE_KEY as TOTAL_USAGE_KEY, USAGE_METADATA_KEY as USAGE_METADATA_KEY, extract_token_usage_from_agent_response as extract_token_usage_from_agent_response
+from langchain_core.tools import BaseTool
+
+logger: Incomplete
+OUTPUT_KEY: str
+RESULT_KEY: str
+ARTIFACTS_KEY: str
+METADATA_KEY: str
+METADATA_INTERNAL_PREFIXES: Incomplete
+METADATA_INTERNAL_KEYS: Incomplete
+AGENT_RUN_A2A_STREAMING_METHOD: str
+
+class DelegationToolManager(BaseLangGraphToolManager):
+    """Manages internal agent delegation tools for LangGraph agents.
+
+    This tool manager converts internal agent instances into LangChain tools
+    that can be used for task delegation within a unified ToolNode. Each
+    delegated agent becomes a tool that the coordinator can call.
+
+    Simplified version following legacy BaseLangChainAgent patterns.
+    """
+    registered_agents: list[BaseAgent]
+    parent_agent: Incomplete
+    def __init__(self, parent_agent: BaseAgent | None = None) -> None:
+        """Initialize the delegation tool manager.
+
+        Args:
+            parent_agent: The parent agent that creates delegation tools, used for parent step lookup.
+        """
+    created_tools: Incomplete
+    def register_resources(self, agents: list[BaseAgent]) -> list[BaseTool]:
+        """Register internal agents for delegation and convert them to tools.
+
+        Args:
+            agents: List of BaseAgent instances for internal task delegation.
+
+        Returns:
+            List of created delegation tools.
+        """
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered delegation agents.
+
+        Returns:
+            list[str]: A list of names of all registered delegation agents.
+        """

aip_agents/utils/langgraph/tool_output_management.pyi

@@ -0,0 +1,329 @@
+from _typeshed import Incomplete
+from aip_agents.storage.providers.base import BaseStorageProvider as BaseStorageProvider, StorageError as StorageError
+from aip_agents.storage.providers.memory import InMemoryStorageProvider as InMemoryStorageProvider
+from aip_agents.utils.logger import get_logger as get_logger
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any
+
+logger: Incomplete
+STRING_TRUNCATION_LENGTH: int
+MAX_TOOL_ARGS_DISPLAY: int
+DATA_PREVIEW_TRUNCATION_LENGTH: int
+TOOL_OUTPUT_REFERENCE_PREFIX: str
+
+class ToolReferenceError(Exception):
+    """Specialized exception for tool output reference resolution errors.
+
+    This exception is raised when there are issues with resolving tool output references,
+    such as invalid reference syntax, missing outputs, or security violations.
+
+    Attributes:
+        reference: The original reference string that caused the error.
+        call_id: The call ID that was attempted to be resolved, if applicable.
+        details: Additional error details for debugging.
+    """
+    reference: Incomplete
+    call_id: Incomplete
+    details: Incomplete
+    def __init__(self, message: str, reference: str | None = None, call_id: str | None = None, details: dict[str, Any] | None = None) -> None:
+        """Initialize a ToolReferenceError.
+
+        Args:
+            message: Human-readable error message describing what went wrong.
+            reference: The original reference string that caused the error, if applicable.
+            call_id: The call ID that was attempted to be resolved, if applicable.
+            details: Additional error details for debugging, if applicable.
+        """
+
+@dataclass
+class ToolOutputConfig:
+    """Configuration for tool output management system.
+
+    This class defines the operational parameters for the tool output management
+    system, including storage limits, cleanup intervals, and lifecycle policies.
+
+    Attributes:
+        max_stored_outputs: Maximum number of tool outputs to store simultaneously.
+            When this limit is reached, oldest outputs are evicted. Defaults to 100.
+        max_age_minutes: Maximum age in minutes for stored outputs before they
+            become eligible for cleanup. Defaults to 60 minutes.
+        cleanup_interval: Number of tool calls between automatic cleanup operations.
+            Set to 0 to disable automatic cleanup. Defaults to 20.
+        storage_provider: Optional storage provider for persistent storage.
+            If None, uses in-memory storage (backward compatible). Defaults to None.
+    """
+    max_stored_outputs: int = ...
+    max_age_minutes: int = ...
+    cleanup_interval: int = ...
+    storage_provider: BaseStorageProvider | None = ...
+
+@dataclass
+class ToolOutput:
+    """Container for tool outputs with optional data payload.
+
+    This class represents tool output metadata and optionally the actual data.
+    When used as metadata only, the data field is None and must be retrieved
+    from storage. When loaded with data, it contains the complete output.
+
+    Attributes:
+        call_id: Unique identifier for this tool call, used for reference resolution.
+        tool_name: Name of the tool that produced this output.
+        timestamp: When this output was created and stored.
+        size_bytes: Approximate size of the stored data in bytes for memory management.
+        tool_args: Input arguments that were passed to the tool for this call.
+        data: Optional actual output data. None when used as metadata only.
+        data_description: Optional human-readable description of the data content,
+            typically provided by the tool itself.
+        tags: Optional list of tags for categorization and filtering.
+        agent_name: Name of the agent that created this output, for multi-agent context.
+    """
+    call_id: str
+    tool_name: str
+    timestamp: datetime
+    size_bytes: int
+    tool_args: dict[str, Any]
+    data: Any | None = ...
+    data_description: str | None = ...
+    tags: list[str] | None = ...
+    agent_name: str | None = ...
+    @property
+    def is_metadata_only(self) -> bool:
+        """Check if this instance contains only metadata without data."""
+    def is_expired(self, max_age: timedelta) -> bool:
+        """Check if this output has expired based on the given maximum age.
+
+        Args:
+            max_age (timedelta): The maximum age allowed before expiration.
+
+        Returns:
+            bool: True if the output has expired, False otherwise.
+        """
+    def get_data_preview(self, max_length: int = 200, storage_provider: BaseStorageProvider | None = None, thread_id: str | None = None) -> str | None:
+        """Get a truncated string representation of the stored data.
+
+        Args:
+            max_length: Maximum length of the preview string.
+            storage_provider: Required only if data is not loaded.
+            thread_id: Thread ID required for proper storage key generation.
+
+        Returns:
+            A string representation of the data, truncated if necessary. None if data is not found.
+        """
+    def with_data(self, data: Any) -> ToolOutput:
+        """Create a new instance with data populated.
+
+        Returns a new ToolOutput instance with the same metadata but with
+        data field populated. Useful for converting metadata-only instances
+        to complete instances.
+
+        Args:
+            data (Any): The actual output data to populate.
+
+        Returns:
+            ToolOutput: A new instance with data populated.
+        """
+
+@dataclass
+class StoreOutputParams:
+    """Parameters for storing tool outputs.
+
+    Reduces the number of arguments passed to store_output method.
+
+    Attributes:
+        call_id: Unique identifier for this tool call.
+        tool_name: Name of the tool that produced the output.
+        data: The actual output data to store.
+        tool_args: Input arguments used for the tool call.
+        thread_id: Thread/conversation ID to organize outputs by conversation.
+        description: Optional human-readable description of the output.
+        tags: Optional list of tags for categorization.
+        agent_name: Name of the agent that created this output.
+    """
+    call_id: str
+    tool_name: str
+    data: Any
+    tool_args: dict[str, Any]
+    thread_id: str
+    description: str | None = ...
+    tags: list[str] | None = ...
+    agent_name: str | None = ...
+
+class ToolOutputManager:
+    """Production-ready tool output manager with comprehensive lifecycle management.
+
+    This class provides centralized management of tool outputs including storage,
+    retrieval, lifecycle management, and LLM-friendly summarization. It handles
+    memory management through configurable cleanup policies and provides secure
+    access to stored outputs.
+
+    Key Features:
+    - Automatic and manual storage of tool outputs with metadata
+    - Configurable lifecycle management with age and size-based eviction
+    - LLM-friendly summary generation with data previews and context
+    - Memory management with size tracking and cleanup
+    - Thread-safe operations with proper error handling and locking
+    - Concurrent access support for multi-agent and parallel processing scenarios
+
+    Attributes:
+        config: Configuration object defining operational parameters.
+    """
+    config: Incomplete
+    def __init__(self, config: ToolOutputConfig) -> None:
+        """Initialize the ToolOutputManager with the given configuration.
+
+        Args:
+            config: Configuration object defining storage limits and cleanup policies.
+        """
+    def store_output(self, params: StoreOutputParams) -> None:
+        """Store a tool output with automatic cleanup and size management.
+
+        This method stores a tool output along with its metadata, automatically
+        handling size limits, cleanup, and memory management. If the same call_id
+        is used multiple times within the same thread, the previous output will be overwritten.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            params: StoreOutputParams containing all necessary parameters including thread_id.
+
+        Raises:
+            Exception: If storage operation fails for any reason.
+        """
+    def get_output(self, call_id: str, thread_id: str) -> ToolOutput | None:
+        """Retrieve a stored tool output by its call ID and thread ID.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            call_id: The unique identifier for the tool call.
+            thread_id: The thread/conversation ID to search in.
+
+        Returns:
+            The ToolOutput object with data if found, None otherwise.
+        """
+    def has_outputs(self, thread_id: str | None = None) -> bool:
+        """Check if any outputs are currently stored.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            thread_id: Optional thread ID to check for outputs in a specific thread.
+                If None, checks across all threads.
+
+        Returns:
+            True if there are stored outputs, False otherwise.
+        """
+    def generate_summary(self, thread_id: str, max_entries: int = 10) -> str:
+        """Generate an LLM-friendly structured summary as JSON.
+
+        This method creates a comprehensive, structured summary of stored outputs that
+        can be easily parsed by LLMs and other systems. The JSON format provides rich
+        metadata and context about each tool output.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            thread_id: Thread ID to generate summary for.
+            max_entries: Maximum number of entries to include in the summary.
+                Defaults to 10.
+
+        Returns:
+            A JSON string containing structured data about tool outputs. Always returns
+            valid JSON, even when no outputs are stored (empty entries list).
+        """
+    def get_latest_reference(self, thread_id: str) -> str | None:
+        """Return the most recent tool output reference for a thread.
+
+        Args:
+            thread_id: Thread ID to retrieve the latest output reference for.
+
+        Returns:
+            Latest tool output reference string or None when unavailable.
+        """
+    def has_reference(self, value: Any) -> bool:
+        """Check whether a value contains a tool output reference.
+
+        Args:
+            value: Value to inspect for tool output references.
+
+        Returns:
+            True if any tool output reference is present.
+        """
+    def should_replace_with_reference(self, value: Any) -> bool:
+        """Check whether a tool argument value should use a tool output reference.
+
+        Args:
+            value: Value to evaluate for replacement.
+
+        Returns:
+            True if the value should be replaced with a reference.
+        """
+    def rewrite_args_with_latest_reference(self, args: dict[str, Any], thread_id: str) -> dict[str, Any]:
+        """Rewrite tool args to use the latest tool output reference when appropriate.
+
+        Args:
+            args: Tool arguments to rewrite.
+            thread_id: Thread ID used for resolving stored outputs.
+
+        Returns:
+            Updated args dictionary with references substituted when needed.
+        """
+    def clear_all(self) -> None:
+        """Clear all stored outputs from both metadata and storage.
+
+        Warning:
+            This operation is irreversible and will remove all stored tool outputs.
+        """
+    def get_storage_stats(self) -> dict[str, Any]:
+        """Get storage statistics for monitoring and debugging.
+
+        Returns:
+            Dictionary containing storage statistics.
+        """
+
+class ToolReferenceResolver:
+    """Secure and efficient tool output reference resolution system.
+
+    This class handles the resolution of tool output references in a secure manner,
+    preventing injection attacks while providing simple and reliable access to
+    stored tool outputs. It uses a whitelist approach with regex validation to
+    ensure only safe references are processed.
+
+    Security Features:
+    - Strict regex pattern matching for reference syntax
+    - Whitelist-based validation to prevent injection attacks
+    - Fail-fast error handling with detailed error messages
+    - Input sanitization and validation at multiple levels
+
+    Supported Reference Syntax:
+    - $tool_output.<call_id> - Direct reference to a tool output by call ID
+
+    Attributes:
+        config: Configuration object for operational parameters.
+    """
+    config: Incomplete
+    def __init__(self, config: ToolOutputConfig) -> None:
+        """Initialize the ToolReferenceResolver with security configuration.
+
+        Args:
+            config: Configuration object defining operational parameters.
+        """
+    def resolve_references(self, args: dict[str, Any], manager: ToolOutputManager, thread_id: str | None = None) -> dict[str, Any]:
+        """Resolve all tool output references in the given arguments dictionary.
+
+        This method recursively processes a dictionary of tool arguments, finding
+        and resolving any tool output references. It supports nested dictionaries
+        and lists, providing comprehensive reference resolution.
+
+        Args:
+            args: Dictionary of tool arguments that may contain references.
+            manager: ToolOutputManager instance to resolve references against.
+            thread_id: Optional thread ID for context-aware resolution.
+
+        Returns:
+            New dictionary with all references resolved to their actual values.
+
+        Raises:
+            ToolReferenceError: If any reference is invalid or cannot be resolved.
+        """

aip_agents/utils/logger.pyi

@@ -0,0 +1,60 @@
+import logging
+from _typeshed import Incomplete
+
+LOGGER_NAME: str
+LOG_LEVEL: Incomplete
+
+class _GoogleAdkLogFilter(logging.Filter):
+    """Suppress noisy Google ADK model registry logs.
+
+    Google ADK emits a burst of INFO logs when registering Gemini model patterns.
+    They are redundant (class is unchanged) and clutter our startup output, so we
+    drop them at the logging infrastructure level instead of touching ADK internals.
+    """
+    SUPPRESSED_PREFIX: str
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Return False when the log should be discarded.
+
+        Args:
+            record (logging.LogRecord): The log record to filter.
+
+        Returns:
+            bool: True if the log should be processed, False if it should be discarded.
+        """
+
+LOG_FILTERS: Incomplete
+logger_manager: Incomplete
+root_logger: Incomplete
+
+def get_logger(name: str = ..., level: int = ...) -> logging.Logger:
+    """Get a logger instance.
+
+    Args:
+        name (str): The name of the logger. Defaults to AIPAgentsLogger.
+        level (int): The level of the logger. Defaults to INFO.
+
+    Returns:
+        logging.Logger: The logger instance.
+    """
+
+logger: Incomplete
+THIRD_PARTY_LOGGER_NAMES: Incomplete
+
+class LoggerManager:
+    """A singleton class to manage logging configuration.
+
+    This class is deprecated and will be removed in a future version.
+    Use get_logger() function directly instead.
+    """
+    def __new__(cls):
+        """Initialize the singleton instance."""
+    def get_logger(self, name: str = ..., level: int = ...) -> logging.Logger:
+        """Get a logger instance.
+
+        Args:
+            name (str): The name of the logger. Defaults to AIPAgentsLogger.
+            level (int): The level of the logger. Defaults to INFO.
+
+        Returns:
+            logging.Logger: The logger instance.
+        """

aip_agents/utils/metadata/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.utils.metadata.activity_metadata_helper import DEFAULT_ACTIVITY_INFO as DEFAULT_ACTIVITY_INFO, _format_tool_or_subagent_name as _format_tool_or_subagent_name, create_tool_activity_info as create_tool_activity_info
+from aip_agents.utils.metadata.schemas import Activity as Activity, ActivityDataType as ActivityDataType, Thinking as Thinking
+from aip_agents.utils.metadata.thinking_metadata_helper import FINAL_THINKING_INFO as FINAL_THINKING_INFO
+
+__all__ = ['Activity', 'ActivityDataType', 'Thinking', 'create_tool_activity_info', 'DEFAULT_ACTIVITY_INFO', '_format_tool_or_subagent_name', 'FINAL_THINKING_INFO']

aip_agents/utils/metadata/activity_metadata_helper.pyi

@@ -0,0 +1,25 @@
+from _typeshed import Incomplete
+from aip_agents.schema.hitl import ApprovalDecisionType as ApprovalDecisionType
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata.activity_narrative import ActivityNarrativeBuilder as ActivityNarrativeBuilder, DELEGATE_PREFIX as DELEGATE_PREFIX, HITL_DECISION_MESSAGES as HITL_DECISION_MESSAGES, HITL_PENDING_DESCRIPTION as HITL_PENDING_DESCRIPTION, HITL_PENDING_TITLE as HITL_PENDING_TITLE
+from aip_agents.utils.metadata.schemas.activity_schema import Activity as Activity
+from typing import Any
+
+logger: Incomplete
+DEFAULT_ACTIVITY_MESSAGE: str
+TOOL_EXECUTION_RUNNING_TEMPLATE: str
+TOOL_EXECUTION_COMPLETE_TEMPLATE: str
+SUBAGENT_DELEGATION_TEMPLATE: str
+SUBAGENT_COMPLETE_TEMPLATE: str
+MIXED_EXECUTION_TEMPLATE: str
+DEFAULT_ACTIVITY_INFO: Incomplete
+
+def create_tool_activity_info(original_metadata: dict[str, Any] | None) -> dict[str, str]:
+    '''Create activity info payload with optional LLM narrative overrides.
+
+    Args:
+        original_metadata: The original metadata dictionary containing tool_info and hitl data.
+
+    Returns:
+        A dict with data_type="activity" and data_value as a JSON string.
+    '''

aip_agents/utils/metadata/activity_narrative/__init__.pyi

@@ -0,0 +1,7 @@
+from aip_agents.utils.metadata.activity_narrative.builder import ActivityNarrativeBuilder as ActivityNarrativeBuilder, _formatter_llm_client as _formatter_llm_client
+from aip_agents.utils.metadata.activity_narrative.constants import DELEGATE_PREFIX as DELEGATE_PREFIX, HITL_DECISION_MESSAGES as HITL_DECISION_MESSAGES, HITL_PENDING_DESCRIPTION as HITL_PENDING_DESCRIPTION, HITL_PENDING_TITLE as HITL_PENDING_TITLE, OUTPUT_EXCERPT_MAX_CHARS as OUTPUT_EXCERPT_MAX_CHARS, SYSTEM_PROMPT as SYSTEM_PROMPT
+from aip_agents.utils.metadata.activity_narrative.context import ActivityContext as ActivityContext, ActivityPhase as ActivityPhase
+from aip_agents.utils.metadata.activity_narrative.formatters import ArgsFormatter as ArgsFormatter, OutputFormatter as OutputFormatter, SensitiveInfoFilter as SensitiveInfoFilter
+from aip_agents.utils.metadata.activity_narrative.utils import _format_tool_or_subagent_name as _format_tool_or_subagent_name
+
+__all__ = ['ActivityNarrativeBuilder', 'ActivityContext', 'ActivityPhase', 'ArgsFormatter', 'OutputFormatter', 'SensitiveInfoFilter', 'DELEGATE_PREFIX', 'HITL_DECISION_MESSAGES', 'HITL_PENDING_DESCRIPTION', 'HITL_PENDING_TITLE', 'OUTPUT_EXCERPT_MAX_CHARS', 'SYSTEM_PROMPT', '_format_tool_or_subagent_name', '_formatter_llm_client']

aip_agents/utils/metadata/activity_narrative/builder.pyi

@@ -0,0 +1,35 @@
+from _typeshed import Incomplete
+from aip_agents.schema.hitl import ApprovalDecisionType as ApprovalDecisionType, HitlMetadata as HitlMetadata
+from aip_agents.utils.formatter_llm_client import FormatterInvocationError as FormatterInvocationError, FormatterInvokerUnavailableError as FormatterInvokerUnavailableError, get_formatter_llm_client as get_formatter_llm_client
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata.activity_narrative.constants import DELEGATE_PREFIX as DELEGATE_PREFIX, HITL_DECISION_MESSAGES as HITL_DECISION_MESSAGES, HITL_PENDING_DESCRIPTION as HITL_PENDING_DESCRIPTION, HITL_PENDING_TITLE as HITL_PENDING_TITLE, OUTPUT_EXCERPT_MAX_CHARS as OUTPUT_EXCERPT_MAX_CHARS, SYSTEM_PROMPT as SYSTEM_PROMPT
+from aip_agents.utils.metadata.activity_narrative.context import ActivityContext as ActivityContext, ActivityPhase as ActivityPhase
+from aip_agents.utils.metadata.activity_narrative.formatters import ArgsFormatter as ArgsFormatter, OutputFormatter as OutputFormatter, SensitiveInfoFilter as SensitiveInfoFilter
+from typing import Any
+
+logger: Incomplete
+
+class ActivityNarrativeBuilder:
+    """Generate structured activity payloads via formatter LLM.
+
+    High-level flow:
+    1. Gather raw metadata about a tool/delegate event and normalize it into an ``ActivityContext``.
+    2. Sanitize arguments and outputs so no sensitive values reach downstream renderers or the formatter model.
+    3. Prompt the shared formatter with phase-specific instructions (e.g., describe intent on start, summarize results on end).
+    4. If the formatter responds with usable heading/body text, surface it; otherwise fall back to deterministic templates
+       built from the sanitized context.
+
+    This approach keeps SSE activity cards readable when the formatter is healthy while still providing sensible copy when
+    the formatter is unavailable or returns low-quality text.
+    """
+    def __init__(self) -> None:
+        """Initialize the activity narrative builder."""
+    def build_payload(self, metadata: dict[str, Any] | None) -> dict[str, Any] | None:
+        """Build enriched payload for the provided metadata.
+
+        Args:
+            metadata: The metadata dictionary containing tool_info, hitl, and other context.
+
+        Returns:
+            Dictionary payload with a rendered message, or None when not available.
+        """

aip_agents/utils/metadata/activity_narrative/constants.pyi

@@ -0,0 +1,10 @@
+from aip_agents.schema.hitl import ApprovalDecisionType
+
+__all__ = ['SYSTEM_PROMPT', 'DELEGATE_PREFIX', 'OUTPUT_EXCERPT_MAX_CHARS', 'HITL_PENDING_TITLE', 'HITL_PENDING_DESCRIPTION', 'HITL_DECISION_MESSAGES']
+
+SYSTEM_PROMPT: str
+DELEGATE_PREFIX: str
+OUTPUT_EXCERPT_MAX_CHARS: int
+HITL_PENDING_TITLE: str
+HITL_PENDING_DESCRIPTION: str
+HITL_DECISION_MESSAGES: dict[ApprovalDecisionType, tuple[str, str]]

aip_agents/utils/metadata/activity_narrative/context.pyi

@@ -0,0 +1,32 @@
+from aip_agents.schema.hitl import ApprovalDecisionType, HitlMetadata
+from dataclasses import dataclass
+from enum import StrEnum
+
+__all__ = ['ActivityContext', 'ActivityPhase']
+
+class ActivityPhase(StrEnum):
+    """Lifecycle phases for tool, delegate, and HITL events."""
+    TOOL_START: str
+    TOOL_END: str
+    DELEGATE_START: str
+    DELEGATE_END: str
+    HITL_PENDING: str
+    HITL_RESOLVED: str
+JSONScalar = str | int | float | bool | None
+
+@dataclass
+class ActivityContext:
+    """Structured representation of an activity event."""
+    phase: ActivityPhase
+    agent_name: str | None
+    subject_name: str | None
+    sanitized_args: dict[str, JSONValue] | None
+    sanitized_output: JSONValue | None
+    arguments_excerpt: str | None
+    output_excerpt: str | None
+    error_excerpt: str | None
+    step_id: str | None = ...
+    is_delegate: bool = ...
+    hitl_metadata: HitlMetadata | None = ...
+    hitl_decision: ApprovalDecisionType | None = ...
+    default_heading: str | None = ...

aip_agents/utils/metadata/activity_narrative/formatters.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from collections.abc import Callable
+
+__all__ = ['ArgsFormatter', 'OutputFormatter', 'SensitiveInfoFilter']
+
+JSONScalar = str | int | float | bool | None
+
+class SensitiveInfoFilter:
+    """Redact sensitive argument/output values before rendering or sending to LLMs."""
+    REDACTED: str
+    SENSITIVE_KEY_PATTERNS: Incomplete
+    def __init__(self) -> None:
+        """Initialize the sensitive info filter."""
+    def sanitize(self, args: dict[str, JSONValue] | None, output: JSONValue | None, tool_sanitizer: Callable[[dict[str, JSONValue] | None, JSONValue | None], dict[str, JSONValue]] | None = None) -> tuple[dict[str, JSONValue] | None, JSONValue | None]:
+        """Return sanitized arguments/output with optional tool overrides.
+
+        Args:
+            args: Raw arguments dictionary emitted by the tool.
+            output: Raw tool output which may be nested JSON.
+            tool_sanitizer: Optional callable that can override sanitized values.
+
+        Returns:
+            tuple: Sanitized args and output payloads.
+        """
+
+class ArgsFormatter:
+    """Simple formatter that surfaces at most two argument key/value pairs."""
+    def format(self, args: dict[str, JSONValue] | None) -> str | None:
+        """Format tool arguments into a short excerpt.
+
+        Args:
+            args: Tool arguments dictionary.
+
+        Returns:
+            str | None: Concise representation of up to two key/value pairs.
+        """
+
+class OutputFormatter:
+    """Lightweight formatter that truncates serialized output."""
+    def format(self, output: JSONValue | None) -> str | None:
+        """Format tool output into a readable excerpt.
+
+        Args:
+            output: Raw tool output.
+
+        Returns:
+            str | None: Truncated representation suitable for logs.
+        """