aip-agents-binary 0.0.0b2__py3-none-any.whl → 0.5.11__py3-none-any.whl

aip_agents/agent/hitl/manager.pyi

@@ -0,0 +1,199 @@
+from _typeshed import Incomplete
+from aip_agents.agent.hitl.config import ToolApprovalConfig as ToolApprovalConfig
+from aip_agents.agent.hitl.prompt import BasePromptHandler as BasePromptHandler, DeferredPromptHandler as DeferredPromptHandler
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest
+from collections.abc import Callable as Callable, Iterable
+from typing import Any
+
+MAX_ARGUMENTS_PREVIEW_LENGTH: int
+DECISION_MESSAGE_MAP: Incomplete
+TOOL_EXECUTION_BLOCKING_DECISIONS: Incomplete
+
+class ApprovalManager:
+    """Manages the HITL approval workflow for tools.
+
+    This class coordinates the approval process from configuration through
+    to final decision, handling timeouts and cleanup.
+    """
+    def __init__(self, prompt_handler: BasePromptHandler | None = None) -> None:
+        """Initialize the approval manager.
+
+        Args:
+            prompt_handler: Optional prompt handler for user interaction.
+                Defaults to DeferredPromptHandler which exposes pending requests
+                for out-of-band resolution.
+        """
+    def create_approval_request(self, tool_name: str, arguments: dict[str, Any], config: ToolApprovalConfig, context: dict[str, str] | None = None) -> ApprovalRequest:
+        """Create a new approval request for a tool call.
+
+        Args:
+            tool_name: Name of the tool being called.
+            arguments: Tool arguments (will be JSON serialized).
+            config: Approval configuration for this tool.
+            context: Optional context metadata. Defaults to None.
+
+        Returns:
+            The created approval request.
+        """
+    def get_pending_request(self, request_id: str) -> ApprovalRequest | None:
+        """Get a pending approval request by ID.
+
+        Args:
+            request_id: The unique identifier of the approval request.
+
+        Returns:
+            The pending approval request if found, None otherwise.
+        """
+    def approve_request(self, request: ApprovalRequest, operator_input: str = 'approved') -> ApprovalDecision:
+        '''Record an approval decision for a request.
+
+        This method creates an approval decision, calculates latency metrics,
+        and removes the request from the active requests queue.
+
+        Args:
+            request: The approval request to approve.
+            operator_input: Raw operator input that led to this decision. Defaults to "approved".
+
+        Returns:
+            The recorded approval decision.
+        '''
+    def reject_request(self, request: ApprovalRequest, operator_input: str = 'rejected') -> ApprovalDecision:
+        '''Record a rejection decision for a request.
+
+        This method creates a rejection decision, calculates latency metrics,
+        and removes the request from the active requests queue.
+
+        Args:
+            request: The approval request to reject.
+            operator_input: Raw operator input that led to this decision. Defaults to "rejected".
+
+        Returns:
+            The recorded rejection decision.
+        '''
+    def skip_request(self, request: ApprovalRequest, operator_input: str = 'skipped') -> ApprovalDecision:
+        '''Record a skip decision for a request.
+
+        This method creates a skip decision, calculates latency metrics,
+        and removes the request from the active requests queue.
+
+        Args:
+            request: The approval request to skip.
+            operator_input: Raw operator input that led to this decision. Defaults to "skipped".
+
+        Returns:
+            The recorded skip decision.
+        '''
+    def timeout_request(self, request: ApprovalRequest, operator_input: str = 'TIMEOUT') -> ApprovalDecision:
+        '''Record a timeout decision for a request, always skipping the tool.
+
+        Args:
+            request (ApprovalRequest): The approval request that timed out.
+            operator_input (str, optional): Input from the operator (defaults to "TIMEOUT").
+
+        Returns:
+            ApprovalDecision: The timeout decision.
+        '''
+    def check_timeout(self, request: ApprovalRequest) -> ApprovalDecision | None:
+        """Check if a request has timed out and return timeout decision if so.
+
+        Args:
+            request: The approval request to check.
+
+        Returns:
+            Timeout decision if timed out, None otherwise.
+        """
+    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
+        """Prompt for a decision using the configured handler.
+
+        This method delegates to the configured prompt handler to obtain
+        an approval decision from the operator. The handler may be interactive
+        (CLI) or deferred (programmatic, resume-in-place).
+
+        Args:
+            request: The approval request to prompt for.
+            timeout_seconds: How long to wait for input.
+            context_keys: Optional keys to display from context. Defaults to None.
+
+        Returns:
+            The operator's decision on the request.
+        """
+    def list_pending_requests(self) -> Iterable[ApprovalRequest]:
+        """Return a snapshot of currently pending requests.
+
+        This method provides a thread-safe snapshot of all currently active
+        approval requests that are waiting for operator decisions.
+
+        Returns:
+            An iterable of all pending approval requests.
+        """
+    def resolve_pending_request(self, request_id: str, decision: str, operator_input: str = '') -> ApprovalDecision:
+        '''Resolve a pending request with an explicit decision.
+
+        Args:
+            request_id: The unique identifier of the pending approval request.
+            decision: The decision string (e.g., "approved", "rejected", "skipped").
+            operator_input: Optional raw operator input, defaults to the decision string. Defaults to "".
+
+        Returns:
+            The recorded approval decision.
+
+        Raises:
+            KeyError: If no pending request exists with the given request_id.
+            ValueError: If the decision string is not supported.
+        '''
+    def create_log_entry(self, decision: ApprovalDecision, tool_name: str, agent_id: str | None = None, thread_id: str | None = None, additional_context: dict[str, Any] | None = None) -> ApprovalLogEntry:
+        """Create a log entry for a decision.
+
+        Args:
+            decision: The approval decision.
+            tool_name: Name of the tool.
+            agent_id: Optional agent identifier. Defaults to None.
+            thread_id: Optional thread/session identifier. Defaults to None.
+            additional_context: Optional additional logging context. Defaults to None.
+
+        Returns:
+            Structured log entry.
+        """
+    def cleanup_expired_requests(self) -> int:
+        """Clean up expired requests and return count of cleaned requests.
+
+        This method removes all approval requests that have exceeded their
+        timeout period from the active requests queue. This is typically
+        called periodically to prevent memory leaks from abandoned requests.
+
+        Returns:
+            The number of expired requests that were cleaned up.
+        """
+    def register_waiter(self, request_id: str, future: Any) -> None:
+        """Register a waiter future for an approval request.
+
+        Args:
+            request_id: The id for which to wait.
+            future: An asyncio.Future that will receive a tuple(decision, operator_input).
+        """
+    def unregister_waiter(self, request_id: str) -> None:
+        """Unregister a waiter if present (used on timeout/cancellation).
+
+        Args:
+            request_id (str): The ID of the request to unregister the waiter for.
+        """
+    async def wait_for_pending_decision(self, request: ApprovalRequest, timeout_seconds: int) -> ApprovalDecision:
+        """Wait for a pending request to be resolved and return the final decision.
+
+        Args:
+            request: The pending approval request to wait for.
+            timeout_seconds: Maximum time to wait before treating as timeout.
+
+        Returns:
+            The finalized approval decision.
+        """
+    @staticmethod
+    def get_decision_message(decision: ApprovalDecision) -> str:
+        """Get the appropriate message for a HITL decision.
+
+        Args:
+            decision: The approval decision to get a message for.
+
+        Returns:
+            A human-readable message explaining the decision outcome.
+        """

aip_agents/agent/hitl/models.py

@@ -0,0 +1,18 @@
+"""Backward-compatible exports for HITL approval schema.
+
+Prefer importing from ``aip_agents.schema.hitl`` in new code.
+"""
+
+from aip_agents.schema.hitl import (
+    ApprovalDecision,
+    ApprovalDecisionType,
+    ApprovalLogEntry,
+    ApprovalRequest,
+)
+
+__all__ = [
+    "ApprovalDecisionType",
+    "ApprovalRequest",
+    "ApprovalDecision",
+    "ApprovalLogEntry",
+]

aip_agents/agent/hitl/models.pyi

@@ -0,0 +1,3 @@
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest
+
+__all__ = ['ApprovalDecisionType', 'ApprovalRequest', 'ApprovalDecision', 'ApprovalLogEntry']

aip_agents/agent/hitl/prompt/__init__.py

@@ -0,0 +1,9 @@
+"""Prompt handler implementations for HITL approvals."""
+
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler
+from aip_agents.agent.hitl.prompt.deferred import DeferredPromptHandler
+
+__all__ = [
+    "BasePromptHandler",
+    "DeferredPromptHandler",
+]

aip_agents/agent/hitl/prompt/__init__.pyi

@@ -0,0 +1,4 @@
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler as BasePromptHandler
+from aip_agents.agent.hitl.prompt.deferred import DeferredPromptHandler as DeferredPromptHandler
+
+__all__ = ['BasePromptHandler', 'DeferredPromptHandler']

aip_agents/agent/hitl/prompt/base.py

@@ -0,0 +1,42 @@
+"""Shared base classes for HITL prompt handlers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from aip_agents.schema.hitl import ApprovalDecision, ApprovalRequest
+
+if TYPE_CHECKING:  # pragma: no cover - typing-only import
+    from aip_agents.agent.hitl.manager import ApprovalManager
+
+
+class BasePromptHandler(ABC):
+    """Abstract base class for prompt handlers used in HITL flows."""
+
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Optionally attach the ``ApprovalManager`` coordinating approvals.
+
+        Args:
+            manager (ApprovalManager): The approval manager instance to attach.
+        """
+        # Default implementation stores nothing; subclasses override as needed.
+        return None
+
+    @abstractmethod
+    async def prompt_for_decision(
+        self,
+        request: ApprovalRequest,
+        timeout_seconds: int,
+        context_keys: list[str] | None = None,
+    ) -> ApprovalDecision:
+        """Collect and return a decision for the given approval request.
+
+        Args:
+            request (ApprovalRequest): The approval request to prompt for.
+            timeout_seconds (int): Maximum time to wait for a decision in seconds.
+            context_keys (list[str] | None, optional): Optional keys for additional context. Defaults to None.
+
+        Returns:
+            ApprovalDecision: The decision made for the approval request.
+        """

aip_agents/agent/hitl/prompt/base.pyi

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalRequest as ApprovalRequest
+
+class BasePromptHandler(ABC):
+    """Abstract base class for prompt handlers used in HITL flows."""
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Optionally attach the ``ApprovalManager`` coordinating approvals.
+
+        Args:
+            manager (ApprovalManager): The approval manager instance to attach.
+        """
+    @abstractmethod
+    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
+        """Collect and return a decision for the given approval request.
+
+        Args:
+            request (ApprovalRequest): The approval request to prompt for.
+            timeout_seconds (int): Maximum time to wait for a decision in seconds.
+            context_keys (list[str] | None, optional): Optional keys for additional context. Defaults to None.
+
+        Returns:
+            ApprovalDecision: The decision made for the approval request.
+        """

aip_agents/agent/hitl/prompt/deferred.py

@@ -0,0 +1,73 @@
+"""Deferred prompt handler that waits for external approval resolution."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler
+from aip_agents.schema.hitl import ApprovalDecision, ApprovalDecisionType, ApprovalRequest
+
+if TYPE_CHECKING:  # pragma: no cover - typing-only import
+    from aip_agents.agent.hitl.manager import ApprovalManager
+
+
+class DeferredPromptHandler(BasePromptHandler):
+    """Prompt handler that defers tool execution until an external decision is received."""
+
+    def __init__(self, notify: Callable[[ApprovalRequest], None] | None = None) -> None:
+        """Initialize the deferred prompt handler.
+
+        Args:
+            notify: Optional callback function to notify when an approval request is made.
+        """
+        self._notify = notify
+        self._manager: ApprovalManager | None = None
+
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Attach the ApprovalManager orchestrating approvals.
+
+        Args:
+            manager: The ApprovalManager instance to attach for handling approval decisions.
+        """
+        self._manager = manager
+
+    async def prompt_for_decision(
+        self,
+        request: ApprovalRequest,
+        timeout_seconds: int,
+        context_keys: list[str] | None = None,
+    ) -> ApprovalDecision:
+        """Register a waiter and return a pending decision sentinel.
+
+        Args:
+            request: The approval request containing the tool call details and context.
+            timeout_seconds: Number of seconds to wait for approval before timing out.
+            context_keys: Optional list of context keys to include in the approval request.
+
+        Returns:
+            ApprovalDecision with PENDING status and registered waiter for external resolution.
+        """
+        if self._notify:
+            try:
+                self._notify(request)
+            except Exception:
+                pass
+
+        if self._manager is None:
+            return ApprovalDecision(
+                request_id=request.request_id,
+                decision=ApprovalDecisionType.PENDING,
+                operator_input="PENDING",
+            )
+
+        loop = asyncio.get_running_loop()
+        waiter = loop.create_future()
+        self._manager.register_waiter(request.request_id, waiter)
+
+        return ApprovalDecision(
+            request_id=request.request_id,
+            decision=ApprovalDecisionType.PENDING,
+            operator_input="PENDING",
+        )

aip_agents/agent/hitl/prompt/deferred.pyi

@@ -0,0 +1,30 @@
+from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler as BasePromptHandler
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalRequest as ApprovalRequest
+from collections.abc import Callable
+
+class DeferredPromptHandler(BasePromptHandler):
+    """Prompt handler that defers tool execution until an external decision is received."""
+    def __init__(self, notify: Callable[[ApprovalRequest], None] | None = None) -> None:
+        """Initialize the deferred prompt handler.
+
+        Args:
+            notify: Optional callback function to notify when an approval request is made.
+        """
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Attach the ApprovalManager orchestrating approvals.
+
+        Args:
+            manager: The ApprovalManager instance to attach for handling approval decisions.
+        """
+    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
+        """Register a waiter and return a pending decision sentinel.
+
+        Args:
+            request: The approval request containing the tool call details and context.
+            timeout_seconds: Number of seconds to wait for approval before timing out.
+            context_keys: Optional list of context keys to include in the approval request.
+
+        Returns:
+            ApprovalDecision with PENDING status and registered waiter for external resolution.
+        """

aip_agents/agent/interface.py

@@ -0,0 +1,138 @@
+"""Defines the abstract base class AgentInterface for all agent implementations, now with MCP and A2A support.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from a2a.types import AgentCard
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+
+from aip_agents.schema.agent import BaseAgentConfig
+
+
+class AgentInterface(ABC):
+    """A general and minimal interface for agent implementations.
+
+    Defines core execution methods (`__init__`, `run`, `arun`, `arun_stream`).
+    Concrete subclasses must implement all abstract methods.
+    """
+
+    name: str
+    instruction: str
+    description: str | None
+    mcp_config: dict[str, Any] = {}
+    lm_invoker: BaseLMInvoker | None = None
+    config: BaseAgentConfig | None = None
+
+    def __init__(
+        self,
+        name: str,
+        instruction: str,
+        description: str | None = None,
+        lm_invoker: BaseLMInvoker | None = None,
+        config: BaseAgentConfig | None = None,
+        **kwargs: Any,
+    ):
+        """Initializes the agent.
+
+        Args:
+            name: The name of the agent.
+            instruction: The core directive or system prompt for the agent.
+            description: Human-readable description. Defaults to instruction if not provided.
+            lm_invoker: The language model invoker to use for LLM interactions. Defaults to None.
+            config: Additional configuration for the agent.
+            **kwargs: Additional keyword arguments for concrete implementations.
+        """
+        self.name = name
+        self.instruction = instruction
+        self.description = description or self.instruction
+        self.lm_invoker = lm_invoker
+        self.config = config
+
+    @abstractmethod
+    def run(
+        self,
+        query: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Synchronously runs the agent.
+
+        Args:
+            query: The input query for the agent.
+            **kwargs: Additional keyword arguments for execution.
+
+        Returns:
+            Dict containing at least {'output': ...}.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'run' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    async def arun(
+        self,
+        query: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Asynchronously runs the agent.
+
+        Args:
+            query: The input query for the agent.
+            **kwargs: Additional keyword arguments for execution.
+
+        Returns:
+            Dict containing at least {'output': ...}.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'arun' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    async def arun_stream(
+        self,
+        query: str,
+        **kwargs: Any,
+    ) -> AsyncGenerator[str | dict[str, Any], None]:
+        """Asynchronously streams the agent's response.
+
+        Args:
+            query: The input query.
+            **kwargs: Extra parameters for execution.
+
+        Yields:
+            Chunks of output (strings or dicts).
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'arun_stream' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    def add_mcp_server(self, mcp_config: dict[str, dict[str, Any]]) -> None:
+        """Adds a new MCP server configuration.
+
+        Args:
+            mcp_config: Dictionary containing server name as key and its configuration as value.
+
+        Raises:
+            ValueError: If mcp_config is empty or None, or if any server configuration is invalid.
+            KeyError: If any server name already exists in the configuration.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'add_mcp_server' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    def register_a2a_agents(self, agents: list[AgentCard]):
+        """Registers A2A agents from a list of AgentCards.
+
+        Args:
+            agents: A list of AgentCard instances.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'register_a2a_agents' method."
+        )  # pragma: no cover

aip_agents/agent/interface.pyi

@@ -1,11 +1,11 @@
-import abc
 from a2a.types import AgentCard as AgentCard
 from abc import ABC, abstractmethod
-from aip_agents.agent.types import BaseAgentConfig as BaseAgentConfig
-from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker as BaseLMInvoker
-from typing import Any, AsyncGenerator
+from aip_agents.schema.agent import BaseAgentConfig as BaseAgentConfig
+from collections.abc import AsyncGenerator
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from typing import Any
 
-class AgentInterface(ABC, metaclass=abc.ABCMeta):
+class AgentInterface(ABC):
     """A general and minimal interface for agent implementations.
 
     Defines core execution methods (`__init__`, `run`, `arun`, `arun_stream`).

aip_agents/agent/interfaces.py

@@ -0,0 +1,65 @@
+"""Common agent-facing protocols used by A2A executors.
+
+These runtime-checkable protocols let executors validate agent instances
+without importing the concrete implementation classes, which avoids
+introducing circular import chains at runtime.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LangGraphAgentProtocol(Protocol):
+    """Minimal interface required by LangGraphA2AExecutor."""
+
+    name: str
+
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """
+
+
+@runtime_checkable
+class LangflowAgentProtocol(Protocol):
+    """Minimal interface required by LangflowA2AExecutor."""
+
+    name: str
+
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """
+
+
+@runtime_checkable
+class GoogleADKAgentProtocol(Protocol):
+    """Minimal interface required by GoogleADKExecutor."""
+
+    name: str
+
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """

aip_agents/agent/interfaces.pyi

@@ -0,0 +1,44 @@
+from collections.abc import AsyncIterator
+from typing import Any, Protocol
+
+class LangGraphAgentProtocol(Protocol):
+    """Minimal interface required by LangGraphA2AExecutor."""
+    name: str
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """
+
+class LangflowAgentProtocol(Protocol):
+    """Minimal interface required by LangflowA2AExecutor."""
+    name: str
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """
+
+class GoogleADKAgentProtocol(Protocol):
+    """Minimal interface required by GoogleADKExecutor."""
+    name: str
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """