aip-agents-binary 0.5.25b8__py3-none-any.whl → 0.6.0__py3-none-any.whl

aip_agents/utils/event_handler_registry.pyi

@@ -0,0 +1,23 @@
+from _typeshed import Incomplete
+from aip_agents.schema.a2a import A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import Any
+
+logger: Incomplete
+
+class EventHandlerRegistry:
+    """Registry for tracking known streaming events with pass-through behaviour."""
+    def __init__(self) -> None:
+        """Initialize the event handler registry with known event types."""
+    def handle(self, event_type: A2AStreamEventType | str | None, payload: dict[str, Any]) -> dict[str, Any]:
+        """Return the payload unchanged while logging unknown events.
+
+        Args:
+            event_type (A2AStreamEventType | str | None): The type of the streaming event.
+            payload (dict[str, Any]): The event payload data.
+
+        Returns:
+            dict[str, Any]: The payload unchanged (pass-through).
+        """
+
+DEFAULT_EVENT_HANDLER_REGISTRY: Incomplete

aip_agents/utils/file_prompt_utils.pyi

@@ -0,0 +1,21 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+FILE_PATH_SYSTEM_NOTE: str
+FILE_PATH_INACCESSIBLE_NOTE: str
+FILE_URL_SYSTEM_NOTE: str
+
+def augment_query_with_file_paths(query: str, files: list[str | dict[str, object]]) -> str:
+    """Augment query with file path system notes.
+
+    Args:
+        query: The original user query string.
+        files: List of local filesystem paths or file metadata dicts to include.
+
+    Returns:
+        The query with system notes appended for each file path.
+
+    Raises:
+        ValueError: If files is not a list of strings or metadata dicts.
+    """

aip_agents/utils/final_response_builder.pyi

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+__all__ = ['FinalResponseMetadataOptions', 'assemble_final_response']
+
+@dataclass(slots=True)
+class FinalResponseMetadataOptions:
+    """Container for optional metadata fields on final response events."""
+    step_id: str | None = ...
+    previous_step_ids: list[str] | None = ...
+    tool_info: dict[str, Any] | None = ...
+    thinking_and_activity_info: dict[str, Any] | None = ...
+    completion_reason: str | None = ...
+    timeout_seconds: float | None = ...
+    message: dict[str, Any] | None = ...
+    partial_result: str | None = ...
+    metadata_extra: dict[str, Any] | None = ...
+
+def assemble_final_response(*, content: str, artifacts: list[dict[str, Any]] | None = None, metadata_options: FinalResponseMetadataOptions | None = None, status: str = 'success', task_state: str = 'completed', extra_fields: dict[str, Any] | None = None, timestamp: datetime | None = None) -> dict[str, Any]:
+    '''Create a final response event with optional artifacts and overrides.
+
+    Args:
+        content: Human readable message for the final response.
+        artifacts: Optional list of artifact dictionaries to attach.
+        metadata_options: Metadata overrides passed through to the underlying builder.
+        status: Top-level status string; defaults to ``"success"``.
+        task_state: State string describing the task; defaults to ``"completed"``.
+        extra_fields: Additional top-level fields to merge onto the event.
+        timestamp: Explicit timestamp for the event. Defaults to ``datetime.now(UTC)``.
+
+    Returns:
+        dict[str, Any]: Final response event payload ready for downstream streaming.
+    '''

aip_agents/utils/formatter_llm_client.pyi

@@ -0,0 +1,71 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from collections.abc import Awaitable as Awaitable
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from typing import Any, TypeVar
+
+logger: Incomplete
+FORMATTER_ENV_VAR: str
+T = TypeVar('T')
+
+class FormatterInvokerUnavailableError(RuntimeError):
+    """Raised when no formatter LLM invoker can be resolved."""
+class FormatterInvocationError(RuntimeError):
+    """Raised when invoking the formatter LLM fails."""
+
+class FormatterLLMClient:
+    """Stateful helper that manages formatter invoker resolution and execution."""
+    def __init__(self) -> None:
+        """Initialize the formatter LLM client with caching and thread safety."""
+    def seed_default(self, default_model_id: str | None) -> None:
+        """Populate ``DEFAULT_MODEL_FORMATTER`` when unset.
+
+        Args:
+            default_model_id: Preferred formatter model id to use as a fallback.
+        """
+    def resolve_invoker(self, *, reset_cache: bool = False) -> BaseLMInvoker | None:
+        """Return the cached formatter invoker, optionally refreshing it.
+
+        Args:
+            reset_cache: When True, clear the cached invoker before resolving.
+
+        Returns:
+            BaseLMInvoker | None: Cached invoker if the formatter is configured, otherwise None.
+        """
+    async def invoke(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
+        """Dispatch formatter prompts asynchronously with timeout/error handling.
+
+        Args:
+            *args: Positional arguments forwarded to the invoker.
+            invoker: Explicit invoker instance to reuse instead of resolving one.
+            timeout: Optional timeout (seconds) enforced with ``asyncio.timeout``.
+            **kwargs: Keyword arguments forwarded to the invoker.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+
+        Raises:
+            FormatterInvokerUnavailableError: If no formatter model is configured.
+            FormatterInvocationError: When the invocation fails or exceeds the timeout.
+        """
+    def invoke_blocking(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
+        """Invoke the formatter LLM from synchronous contexts.
+
+        Args:
+            *args: Positional arguments forwarded to ``invoke``.
+            invoker: Optional invoker to reuse.
+            timeout: Optional timeout (seconds) for the async invocation.
+            **kwargs: Keyword arguments forwarded to ``invoke``.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+        """
+
+def get_formatter_llm_client() -> FormatterLLMClient:
+    """Return the process-wide formatter LLM client."""
+def seed_formatter_llm_default(default_model_id: str | None) -> None:
+    """Convenience wrapper for seeding the formatter default model.
+
+    Args:
+        default_model_id: Formatter model identifier to seed when missing.
+    """

aip_agents/utils/langgraph/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.utils.langgraph.converter import convert_gllm_tool_call_to_langchain_tool_call as convert_gllm_tool_call_to_langchain_tool_call, convert_langchain_messages_to_gllm_messages as convert_langchain_messages_to_gllm_messages, convert_langchain_tool_call_to_gllm_tool_call as convert_langchain_tool_call_to_gllm_tool_call, convert_lm_output_to_langchain_message as convert_lm_output_to_langchain_message
+
+__all__ = ['convert_gllm_tool_call_to_langchain_tool_call', 'convert_langchain_tool_call_to_gllm_tool_call', 'convert_lm_output_to_langchain_message', 'convert_langchain_messages_to_gllm_messages']

aip_agents/utils/langgraph/converter.pyi

@@ -0,0 +1,49 @@
+from collections.abc import Sequence
+from gllm_inference.schema import LMOutput, Message, ToolCall as GllmToolCall
+from langchain_core.messages import AIMessage, BaseMessage as BaseMessage
+from langchain_core.messages.tool import ToolCall as LangChainToolCall
+
+def convert_langchain_messages_to_gllm_messages(messages: Sequence[BaseMessage], instruction: str) -> list[Message]:
+    """Convert LangChain messages to gllm-inference Message format.
+
+    This function transforms a sequence of LangChain messages into the Message
+    format expected by LM Invoker. It handles system messages, human messages, AI messages
+    with tool calls, and tool result messages.
+
+    Args:
+        messages: Sequence of LangChain BaseMessage objects to convert.
+        instruction: System instruction to prepend if not already present in messages.
+
+    Returns:
+        List of Message objects containing the converted message sequence.
+    """
+def convert_lm_output_to_langchain_message(response: LMOutput | str) -> AIMessage:
+    """Convert LM Invoker output to LangChain AIMessage.
+
+    This function transforms the output from LM Invoker back into LangChain's
+    AIMessage format, handling both text responses and tool calls.
+
+    Args:
+        response: The response from LM Invoker (MultimodalOutput).
+
+    Returns:
+        AIMessage containing the converted response.
+    """
+def convert_langchain_tool_call_to_gllm_tool_call(lc_tool_call: LangChainToolCall) -> GllmToolCall:
+    """Convert LangChain tool call to gllm ToolCall.
+
+    Args:
+        lc_tool_call: LangChain ToolCall (TypedDict).
+
+    Returns:
+        GllmToolCall object for gllm-inference.
+    """
+def convert_gllm_tool_call_to_langchain_tool_call(gllm_tool_call: GllmToolCall) -> LangChainToolCall:
+    """Convert gllm ToolCall to LangChain ToolCall format.
+
+    Args:
+        gllm_tool_call: GllmToolCall object from gllm-inference.
+
+    Returns:
+        LangChain ToolCall (TypedDict) with proper type annotation.
+    """

aip_agents/utils/langgraph/tool_managers/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.utils.langgraph.tool_managers.a2a_tool_manager import A2AToolManager as A2AToolManager
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
+from aip_agents.utils.langgraph.tool_managers.delegation_tool_manager import DelegationToolManager as DelegationToolManager
+
+__all__ = ['BaseLangGraphToolManager', 'A2AToolManager', 'DelegationToolManager']

aip_agents/utils/langgraph/tool_managers/a2a_tool_manager.pyi

@@ -0,0 +1,35 @@
+from _typeshed import Incomplete
+from a2a.types import AgentCard as AgentCard
+from aip_agents.utils.a2a_connector import A2AConnector as A2AConnector
+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 langchain_core.tools import BaseTool
+
+logger: Incomplete
+
+class A2AToolManager(BaseLangGraphToolManager):
+    """Manages A2A communication tools for LangGraph agents.
+
+    This tool manager converts A2A agent cards into LangChain tools that can
+    be used in a unified ToolNode within LangGraph agents. Each A2A agent
+    becomes a tool that the LLM can call for external communication.
+    """
+    registered_agents: list
+    def __init__(self) -> None:
+        """Initialize the A2A tool manager."""
+    created_tools: Incomplete
+    def register_resources(self, agent_cards: list[AgentCard]) -> list[BaseTool]:
+        """Register A2A agents and convert them to LangChain tools.
+
+        Args:
+            agent_cards: List of AgentCard instances for external communication.
+
+        Returns:
+            List of created A2A communication tools.
+        """
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered A2A agents.
+
+        Returns:
+            list[str]: A list of names of all registered A2A agents.
+        """

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.py

@@ -134,7 +134,19 @@ class DelegationToolManager(BaseLangGraphToolManager):
             Returns:
                 The result from the delegated agent, including artifacts if any.
             """
-            writer: StreamWriter = get_stream_writer()
+            try:
+                writer: StreamWriter = get_stream_writer()
+            except Exception as exc:
+                logger.warning(
+                    "DelegationToolManager: Stream writer unavailable; delegation streaming disabled.",
+                    extra={"error": str(exc), "error_type": type(exc).__name__},
+                )
+
+                def _noop_writer(_: Any) -> None:
+                    """No-op writer for non-graph execution contexts."""
+                    return None
+
+                writer = _noop_writer
 
             try:
                 # Check delegation depth limit before executing
@@ -295,6 +307,19 @@ class DelegationToolManager(BaseLangGraphToolManager):
             cfg_conf = cfg.get("configurable") if isinstance(cfg, dict) else None
             if isinstance(cfg_conf, dict):
                 parent_step_id = cfg_conf.get("parent_step_id")
+                if not parent_step_id:
+                    metadata = cfg.get("metadata") or {}
+                    tool_call_id = (
+                        cfg_conf.get("tool_call_id")
+                        or metadata.get("tool_call_id")
+                        or metadata.get("id")
+                        or (metadata.get("tool_call") or {}).get("id")
+                    )
+                    if tool_call_id and self.parent_agent is not None:
+                        thread_key = getattr(self.parent_agent, "thread_id_key", "thread_id")
+                        thread_id = cfg_conf.get(thread_key)
+                        parent_map = self.parent_agent._tool_parent_map_by_thread.get(str(thread_id), {})
+                        parent_step_id = parent_map.get(str(tool_call_id))
             _DELEGATION_PARENT_STEP_ID_CVAR.set(parent_step_id)
         except Exception:
             _DELEGATION_PARENT_STEP_ID_CVAR.set(None)

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.py

@@ -471,6 +471,86 @@ class ToolOutputManager:
         """
         return self._generate_json_summary(thread_id, max_entries)
 
+    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.
+        """
+        try:
+            summary = json.loads(self.generate_summary(thread_id, max_entries=1))
+        except Exception as exc:
+            logger.debug("Failed to parse tool output summary: %s", exc)
+            return None
+
+        if not summary:
+            return None
+        latest = summary[0].get("reference")
+        return latest if isinstance(latest, str) and latest else None
+
+    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.
+        """
+        if isinstance(value, str):
+            return value.startswith(TOOL_OUTPUT_REFERENCE_PREFIX)
+        if isinstance(value, dict):
+            return any(self.has_reference(item) for item in value.values())
+        if isinstance(value, list):
+            return any(self.has_reference(item) for item in value)
+        return False
+
+    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.
+        """
+        if isinstance(value, dict | list | tuple):
+            return True
+        if isinstance(value, str):
+            return len(value) > DATA_PREVIEW_TRUNCATION_LENGTH
+        return False
+
+    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.
+        """
+        if not self.has_outputs(thread_id):
+            return args
+        if self.has_reference(args):
+            return args
+
+        latest_reference = self.get_latest_reference(thread_id)
+        if not latest_reference:
+            return args
+
+        updated_args = dict(args)
+        replaced_any = False
+        for key, value in args.items():
+            if self.should_replace_with_reference(value):
+                updated_args[key] = latest_reference
+                replaced_any = True
+
+        return updated_args if replaced_any else args
+
     def _generate_json_summary(self, thread_id: str, max_entries: int) -> str:
         """Generate simplified JSON summary optimized for LLM prompts.