glaip-sdk 0.0.20__py3-none-any.whl → 0.7.7__py3-none-any.whl

glaip_sdk/client/agents.py

@@ -3,39 +3,49 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
+import asyncio
 import json
 import logging
 from collections.abc import AsyncGenerator, Callable, Iterator, Mapping
+from contextlib import asynccontextmanager
 from os import PathLike
 from pathlib import Path
-from typing import Any, BinaryIO
+from typing import TYPE_CHECKING, Any, BinaryIO
 
-import httpx
+if TYPE_CHECKING:
+    from glaip_sdk.client.schedules import ScheduleClient
+    from glaip_sdk.hitl.remote import RemoteHITLHandler
 
-from glaip_sdk.client._agent_payloads import (
+import httpx
+from glaip_sdk.agents import Agent
+from glaip_sdk.client.payloads.agent import (
     AgentCreateRequest,
     AgentListParams,
     AgentListResult,
     AgentUpdateRequest,
 )
+from glaip_sdk.client.agent_runs import AgentRunsClient
 from glaip_sdk.client.base import BaseClient
 from glaip_sdk.client.mcps import MCPClient
 from glaip_sdk.client.run_rendering import (
     AgentRunRenderingManager,
     compute_timeout_seconds,
 )
+from glaip_sdk.client.shared import build_shared_config
 from glaip_sdk.client.tools import ToolClient
 from glaip_sdk.config.constants import (
+    AGENT_CONFIG_FIELDS,
     DEFAULT_AGENT_FRAMEWORK,
     DEFAULT_AGENT_RUN_TIMEOUT,
     DEFAULT_AGENT_TYPE,
     DEFAULT_AGENT_VERSION,
     DEFAULT_MODEL,
 )
-from glaip_sdk.exceptions import NotFoundError
-from glaip_sdk.models import Agent
+from glaip_sdk.exceptions import NotFoundError, ValidationError
+from glaip_sdk.models import AgentResponse
 from glaip_sdk.payload_schemas.agent import list_server_only_fields
 from glaip_sdk.utils.agent_config import normalize_agent_config_for_import
 from glaip_sdk.utils.client_utils import (
@@ -67,6 +77,21 @@ _MERGED_SEQUENCE_FIELDS = ("tools", "agents", "mcps")
 _DEFAULT_METADATA_TYPE = "custom"
 
 
+@asynccontextmanager
+async def _async_timeout_guard(
+    timeout_seconds: float | None,
+) -> AsyncGenerator[None, None]:
+    """Apply an asyncio timeout when a custom timeout is provided."""
+    if timeout_seconds is None:
+        yield
+        return
+    try:
+        async with asyncio.timeout(timeout_seconds):
+            yield
+    except asyncio.TimeoutError as exc:
+        raise httpx.TimeoutException(f"Request timed out after {timeout_seconds}s") from exc
+
+
 def _normalise_sequence(value: Any) -> list[Any] | None:
     """Normalise optional sequence inputs to plain lists."""
     if value is None:
@@ -97,9 +122,7 @@ def _merge_override_maps(
         for key, value in source.items():
             if value is None:
                 continue
-            merged[key] = (
-                _normalise_sequence(value) if key in _MERGED_SEQUENCE_FIELDS else value
-            )
+            merged[key] = _normalise_sequence(value) if key in _MERGED_SEQUENCE_FIELDS else value
     return merged
 
 
@@ -134,9 +157,7 @@ def _prepare_agent_metadata(value: Any) -> dict[str, Any]:
     return prepared
 
 
-def _load_agent_file_payload(
-    file_path: Path, *, model_override: str | None
-) -> dict[str, Any]:
+def _load_agent_file_payload(file_path: Path, *, model_override: str | None) -> dict[str, Any]:
     """Load agent configuration from disk and normalise legacy fields."""
     if not file_path.exists():
         raise FileNotFoundError(f"Agent configuration file not found: {file_path}")
@@ -168,9 +189,7 @@ def _prepare_import_payload(
     raw_definition = load_resource_from_file(file_path)
     original_refs = _extract_original_refs(raw_definition)
 
-    base_payload = _load_agent_file_payload(
-        file_path, model_override=overrides_dict.get("model")
-    )
+    base_payload = _load_agent_file_payload(file_path, model_override=overrides_dict.get("model"))
 
     cli_args = _build_cli_args(overrides_dict)
 
@@ -199,19 +218,7 @@ def _extract_original_refs(raw_definition: dict) -> dict[str, list]:
 
 def _build_cli_args(overrides_dict: dict) -> dict[str, Any]:
     """Build CLI args from overrides, filtering out None values."""
-    cli_args = {
-        key: overrides_dict.get(key)
-        for key in (
-            "name",
-            "instruction",
-            "model",
-            "tools",
-            "agents",
-            "mcps",
-            "timeout",
-        )
-        if overrides_dict.get(key) is not None
-    }
+    cli_args = {key: overrides_dict.get(key) for key in AGENT_CONFIG_FIELDS if overrides_dict.get(key) is not None}
 
     # Normalize sequence fields
     for field in _MERGED_SEQUENCE_FIELDS:
@@ -223,11 +230,7 @@ def _build_cli_args(overrides_dict: dict) -> dict[str, Any]:
 
 def _build_additional_args(overrides_dict: dict, cli_args: dict) -> dict[str, Any]:
     """Build additional args not already in CLI args."""
-    return {
-        key: value
-        for key, value in overrides_dict.items()
-        if value is not None and key not in cli_args
-    }
+    return {key: value for key, value in overrides_dict.items() if value is not None and key not in cli_args}
 
 
 def _remove_model_fields_if_needed(merged: dict, overrides_dict: dict) -> None:
@@ -264,6 +267,8 @@ class AgentClient(BaseClient):
         self._renderer_manager = AgentRunRenderingManager(logger)
         self._tool_client: ToolClient | None = None
         self._mcp_client: MCPClient | None = None
+        self._runs_client: AgentRunsClient | None = None
+        self._schedule_client: ScheduleClient | None = None
 
     def list_agents(
         self,
@@ -278,9 +283,7 @@ class AgentClient(BaseClient):
         """
         if query is not None and kwargs:
             # Both query object and individual parameters provided
-            raise ValueError(
-                "Provide either `query` or individual filter arguments, not both."
-            )
+            raise ValueError("Provide either `query` or individual filter arguments, not both.")
 
         if query is None:
             # Create query from individual parameters for backward compatibility
@@ -339,7 +342,19 @@ class AgentClient(BaseClient):
 
     def get_agent_by_id(self, agent_id: str) -> Agent:
         """Get agent by ID."""
-        data = self._request("GET", f"/agents/{agent_id}")
+        try:
+            data = self._request("GET", f"/agents/{agent_id}")
+        except ValidationError as exc:
+            if exc.status_code == 422:
+                message = f"Agent '{agent_id}' not found"
+                raise NotFoundError(
+                    message,
+                    status_code=404,
+                    error_type=exc.error_type,
+                    payload=exc.payload,
+                    request_id=exc.request_id,
+                ) from exc
+            raise
 
         if isinstance(data, str):
             # Some backends may respond with plain text for missing agents.
@@ -352,7 +367,8 @@ class AgentClient(BaseClient):
                 status_code=404,
             )
 
-        return Agent(**data)._set_client(self)
+        response = AgentResponse(**data)
+        return Agent.from_response(response, client=self)
 
     def find_agents(self, name: str | None = None) -> list[Agent]:
         """Find agents by name."""
@@ -366,15 +382,27 @@ class AgentClient(BaseClient):
     # Renderer delegation helpers
     # ------------------------------------------------------------------ #
     def _get_renderer_manager(self) -> AgentRunRenderingManager:
+        """Get or create the renderer manager instance.
+
+        Returns:
+            AgentRunRenderingManager instance.
+        """
         manager = getattr(self, "_renderer_manager", None)
         if manager is None:
             manager = AgentRunRenderingManager(logger)
             self._renderer_manager = manager
         return manager
 
-    def _create_renderer(
-        self, renderer: RichStreamRenderer | str | None, **kwargs: Any
-    ) -> RichStreamRenderer:
+    def _create_renderer(self, renderer: RichStreamRenderer | str | None, **kwargs: Any) -> RichStreamRenderer:
+        """Create or return a renderer instance.
+
+        Args:
+            renderer: Renderer instance, string identifier, or None.
+            **kwargs: Additional keyword arguments (e.g., verbose).
+
+        Returns:
+            RichStreamRenderer instance.
+        """
         manager = self._get_renderer_manager()
         verbose = kwargs.get("verbose", False)
         if isinstance(renderer, RichStreamRenderer) or hasattr(renderer, "on_start"):
@@ -388,7 +416,21 @@ class AgentClient(BaseClient):
         timeout_seconds: float,
         agent_name: str | None,
         meta: dict[str, Any],
+        hitl_handler: "RemoteHITLHandler | None" = None,
     ) -> tuple[str, dict[str, Any], float | None, float | None]:
+        """Process stream events from an HTTP response.
+
+        Args:
+            stream_response: HTTP response stream.
+            renderer: Renderer to use for displaying events.
+            timeout_seconds: Timeout in seconds.
+            agent_name: Optional agent name.
+            meta: Metadata dictionary.
+            hitl_handler: Optional HITL handler for approval callbacks.
+
+        Returns:
+            Tuple of (final_text, stats_usage, started_monotonic, finished_monotonic).
+        """
         manager = self._get_renderer_manager()
         return manager.process_stream_events(
             stream_response,
@@ -396,6 +438,7 @@ class AgentClient(BaseClient):
             timeout_seconds,
             agent_name,
             meta,
+            hitl_handler=hitl_handler,
         )
 
     def _finalize_renderer(
@@ -406,30 +449,73 @@ class AgentClient(BaseClient):
         started_monotonic: float | None,
         finished_monotonic: float | None,
     ) -> str:
+        """Finalize the renderer and return the final response text.
+
+        Args:
+            renderer: Renderer to finalize.
+            final_text: Final text content.
+            stats_usage: Usage statistics dictionary.
+            started_monotonic: Start time (monotonic).
+            finished_monotonic: Finish time (monotonic).
+
+        Returns:
+            Final text string.
+        """
+        from glaip_sdk.client.run_rendering import finalize_render_manager  # noqa: PLC0415
+
         manager = self._get_renderer_manager()
-        return manager.finalize_renderer(
-            renderer,
-            final_text,
-            stats_usage,
-            started_monotonic,
-            finished_monotonic,
+        return finalize_render_manager(
+            manager, renderer, final_text, stats_usage, started_monotonic, finished_monotonic
         )
 
     def _get_tool_client(self) -> ToolClient:
+        """Get or create the tool client instance.
+
+        Returns:
+            ToolClient instance.
+        """
         if self._tool_client is None:
             self._tool_client = ToolClient(parent_client=self)
         return self._tool_client
 
     def _get_mcp_client(self) -> MCPClient:
+        """Get or create the MCP client instance.
+
+        Returns:
+            MCPClient instance.
+        """
         if self._mcp_client is None:
             self._mcp_client = MCPClient(parent_client=self)
         return self._mcp_client
 
+    @property
+    def schedules(self) -> "ScheduleClient":
+        """Get or create the schedule client instance.
+
+        Returns:
+            ScheduleClient instance.
+        """
+        if self._schedule_client is None:
+            # Import here to avoid circular import
+            from glaip_sdk.client.schedules import ScheduleClient  # noqa: PLC0415
+
+            self._schedule_client = ScheduleClient(parent_client=self)
+        return self._schedule_client
+
     def _normalise_reference_entry(
         self,
         entry: Any,
         fallback_iter: Iterator[Any] | None,
     ) -> tuple[str | None, str | None]:
+        """Normalize a reference entry to extract ID and name.
+
+        Args:
+            entry: Reference entry (string, dict, or other).
+            fallback_iter: Optional iterator for fallback values.
+
+        Returns:
+            Tuple of (entry_id, entry_name).
+        """
         entry_id: str | None = None
         entry_name: str | None = None
 
@@ -466,6 +552,19 @@ class AgentClient(BaseClient):
         label: str,
         plural_label: str | None = None,
     ) -> list[str] | None:
+        """Resolve a list of resource references to IDs.
+
+        Args:
+            items: List of resource references to resolve.
+            references: Optional list of reference objects for fallback.
+            fetch_by_id: Function to fetch resource by ID.
+            find_by_name: Function to find resources by name.
+            label: Singular label for error messages.
+            plural_label: Plural label for error messages.
+
+        Returns:
+            List of resolved resource IDs, or None if items is empty.
+        """
         if not items:
             return None
 
@@ -497,6 +596,22 @@ class AgentClient(BaseClient):
         singular: str,
         plural: str,
     ) -> str:
+        """Resolve a single resource reference to an ID.
+
+        Args:
+            entry: Resource reference to resolve.
+            fallback_iter: Optional iterator for fallback values.
+            fetch_by_id: Function to fetch resource by ID.
+            find_by_name: Function to find resources by name.
+            singular: Singular label for error messages.
+            plural: Plural label for error messages.
+
+        Returns:
+            Resolved resource ID string.
+
+        Raises:
+            ValueError: If the resource cannot be resolved.
+        """
         entry_id, entry_name = self._normalise_reference_entry(entry, fallback_iter)
 
         validated_id = self._validate_resource_id(fetch_by_id, entry_id)
@@ -506,15 +621,21 @@ class AgentClient(BaseClient):
             return entry_id
 
         if entry_name:
-            resolved, success = self._resolve_resource_by_name(
-                find_by_name, entry_name, singular, plural
-            )
+            resolved, success = self._resolve_resource_by_name(find_by_name, entry_name, singular, plural)
             return resolved if success else entry_name
 
         raise ValueError(f"{singular} references must include a valid ID or name.")
 
     @staticmethod
     def _coerce_reference_value(entry: Any) -> str:
+        """Coerce a reference entry to a string value.
+
+        Args:
+            entry: Reference entry (dict, string, or other).
+
+        Returns:
+            String representation of the reference.
+        """
         if isinstance(entry, dict):
             if entry.get("id"):
                 return str(entry["id"])
@@ -523,9 +644,16 @@ class AgentClient(BaseClient):
         return str(entry)
 
     @staticmethod
-    def _validate_resource_id(
-        fetch_by_id: Callable[[str], Any], candidate_id: str | None
-    ) -> str | None:
+    def _validate_resource_id(fetch_by_id: Callable[[str], Any], candidate_id: str | None) -> str | None:
+        """Validate a resource ID by attempting to fetch it.
+
+        Args:
+            fetch_by_id: Function to fetch resource by ID.
+            candidate_id: Candidate ID to validate.
+
+        Returns:
+            Validated ID if found, None otherwise.
+        """
         if not candidate_id:
             return None
         try:
@@ -541,27 +669,33 @@ class AgentClient(BaseClient):
         singular: str,
         plural: str,
     ) -> tuple[str, bool]:
+        """Resolve a resource by name to an ID.
+
+        Args:
+            find_by_name: Function to find resources by name.
+            entry_name: Name of the resource to find.
+            singular: Singular label for error messages.
+            plural: Plural label for error messages.
+
+        Returns:
+            Tuple of (resolved_id, success).
+
+        Raises:
+            ValueError: If resource not found or multiple matches exist.
+        """
         try:
             matches = find_by_name(entry_name)
         except Exception:
             return entry_name, False
 
         if not matches:
-            raise ValueError(
-                f"{singular} '{entry_name}' not found in current workspace."
-            )
+            raise ValueError(f"{singular} '{entry_name}' not found in current workspace.")
         if len(matches) > 1:
-            exact = [
-                m
-                for m in matches
-                if getattr(m, "name", "").lower() == entry_name.lower()
-            ]
+            exact = [m for m in matches if getattr(m, "name", "").lower() == entry_name.lower()]
             if len(exact) == 1:
                 matches = exact
             else:
-                raise ValueError(
-                    f"Multiple {plural} named '{entry_name}'. Please disambiguate."
-                )
+                raise ValueError(f"Multiple {plural} named '{entry_name}'. Please disambiguate.")
         return str(matches[0].id), True
 
     def _resolve_tool_ids(
@@ -569,6 +703,15 @@ class AgentClient(BaseClient):
         tools: list[Any] | None,
         references: list[Any] | None = None,
     ) -> list[str] | None:
+        """Resolve tool references to IDs.
+
+        Args:
+            tools: List of tool references to resolve.
+            references: Optional list of reference objects for fallback.
+
+        Returns:
+            List of resolved tool IDs, or None if tools is empty.
+        """
         tool_client = self._get_tool_client()
         return self._resolve_resource_ids(
             tools,
@@ -584,6 +727,15 @@ class AgentClient(BaseClient):
         agents: list[Any] | None,
         references: list[Any] | None = None,
     ) -> list[str] | None:
+        """Resolve agent references to IDs.
+
+        Args:
+            agents: List of agent references to resolve.
+            references: Optional list of reference objects for fallback.
+
+        Returns:
+            List of resolved agent IDs, or None if agents is empty.
+        """
         return self._resolve_resource_ids(
             agents,
             references,
@@ -598,6 +750,15 @@ class AgentClient(BaseClient):
         mcps: list[Any] | None,
         references: list[Any] | None = None,
     ) -> list[str] | None:
+        """Resolve MCP references to IDs.
+
+        Args:
+            mcps: List of MCP references to resolve.
+            references: Optional list of reference objects for fallback.
+
+        Returns:
+            List of resolved MCP IDs, or None if mcps is empty.
+        """
         mcp_client = self._get_mcp_client()
         return self._resolve_resource_ids(
             mcps,
@@ -610,9 +771,7 @@ class AgentClient(BaseClient):
 
     def _create_agent_from_payload(self, payload: Mapping[str, Any]) -> "Agent":
         """Create an agent using a fully prepared payload mapping."""
-        known, extras = _split_known_and_extra(
-            payload, AgentCreateRequest.__dataclass_fields__
-        )
+        known, extras = _split_known_and_extra(payload, AgentCreateRequest.__dataclass_fields__)
 
         name = known.pop("name", None)
         instruction = known.pop("instruction", None)
@@ -691,7 +850,8 @@ class AgentClient(BaseClient):
             get_endpoint_fmt=f"{AGENTS_ENDPOINT}{{id}}",
             json=payload_dict,
         )
-        return Agent(**full_agent_data)._set_client(self)
+        response = AgentResponse(**full_agent_data)
+        return Agent.from_response(response, client=self)
 
     def create_agent(
         self,
@@ -721,9 +881,7 @@ class AgentClient(BaseClient):
         overrides = _merge_override_maps(base_overrides, kwargs)
 
         if file is not None:
-            payload = _prepare_import_payload(
-                Path(file).expanduser(), overrides, drop_model_fields=True
-            )
+            payload = _prepare_import_payload(Path(file).expanduser(), overrides, drop_model_fields=True)
             if overrides.get("model") is None:
                 payload.pop("model", None)
         else:
@@ -746,9 +904,7 @@ class AgentClient(BaseClient):
         payload: Mapping[str, Any],
     ) -> "Agent":
         """Update an agent using a prepared payload mapping."""
-        known, extras = _split_known_and_extra(
-            payload, AgentUpdateRequest.__dataclass_fields__
-        )
+        known, extras = _split_known_and_extra(payload, AgentUpdateRequest.__dataclass_fields__)
         _normalise_sequence_fields(known)
 
         tool_refs = extras.pop("_tool_refs", None)
@@ -790,8 +946,9 @@ class AgentClient(BaseClient):
 
         payload_dict = request.to_payload(current_agent)
 
-        response = self._request("PUT", f"/agents/{agent_id}", json=payload_dict)
-        return Agent(**response)._set_client(self)
+        api_response = self._request("PUT", f"/agents/{agent_id}", json=payload_dict)
+        response = AgentResponse(**api_response)
+        return Agent.from_response(response, client=self)
 
     def update_agent(
         self,
@@ -818,9 +975,7 @@ class AgentClient(BaseClient):
         overrides = _merge_override_maps(base_overrides, kwargs)
 
         if file is not None:
-            payload = _prepare_import_payload(
-                Path(file).expanduser(), overrides, drop_model_fields=True
-            )
+            payload = _prepare_import_payload(Path(file).expanduser(), overrides, drop_model_fields=True)
         else:
             payload = overrides
 
@@ -840,6 +995,62 @@ class AgentClient(BaseClient):
         """Delete an agent."""
         self._request("DELETE", f"/agents/{agent_id}")
 
+    def upsert_agent(self, identifier: str | Agent, **kwargs) -> Agent:
+        """Create or update an agent by instance, ID, or name.
+
+        Args:
+            identifier: Agent instance, ID (UUID string), or name
+            **kwargs: Agent configuration (instruction, description, tools, etc.)
+
+        Returns:
+            The created or updated agent.
+
+        Example:
+            >>> # By name (creates if not exists)
+            >>> agent = client.agents.upsert_agent(
+            ...     "hello_agent",
+            ...     instruction="You are a helpful assistant.",
+            ...     description="A friendly agent",
+            ... )
+            >>> # By instance
+            >>> agent = client.agents.upsert_agent(existing_agent, description="Updated")
+            >>> # By ID
+            >>> agent = client.agents.upsert_agent("uuid-here", description="Updated")
+        """
+        # Handle Agent instance
+        if isinstance(identifier, Agent):
+            if identifier.id:
+                logger.info("Updating agent by instance: %s", identifier.name)
+                return self.update_agent(identifier.id, name=identifier.name, **kwargs)
+            identifier = identifier.name
+
+        # Handle string (ID or name)
+        if isinstance(identifier, str):
+            # Check if it's a UUID
+            if is_uuid(identifier):
+                logger.info("Updating agent by ID: %s", identifier)
+                return self.update_agent(identifier, **kwargs)
+
+            # It's a name - find or create
+            return self._upsert_agent_by_name(identifier, **kwargs)
+
+        raise ValueError(f"Invalid identifier type: {type(identifier)}")
+
+    def _upsert_agent_by_name(self, name: str, **kwargs) -> Agent:
+        """Find agent by name and update, or create if not found."""
+        existing = self.find_agents(name)
+
+        if len(existing) == 1:
+            logger.info("Updating existing agent: %s", name)
+            return self.update_agent(existing[0].id, name=name, **kwargs)
+
+        if len(existing) > 1:
+            raise ValueError(f"Multiple agents found with name '{name}'")
+
+        # Create new agent
+        logger.info("Creating new agent: %s", name)
+        return self.create_agent(name=name, **kwargs)
+
     def _prepare_sync_request_data(
         self,
         message: str,
@@ -882,9 +1093,7 @@ class AgentClient(BaseClient):
                 payload["tty"] = True
             return payload, None, None, headers, None
 
-    def _get_timeout_values(
-        self, timeout: float | None, **kwargs: Any
-    ) -> tuple[float, float]:
+    def _get_timeout_values(self, timeout: float | None, **kwargs: Any) -> tuple[float, float]:
         """Get request timeout and execution timeout values.
 
         Args:
@@ -906,9 +1115,35 @@ class AgentClient(BaseClient):
         tty: bool = False,
         *,
         renderer: RichStreamRenderer | str | None = "auto",
+        runtime_config: dict[str, Any] | None = None,
+        hitl_handler: "RemoteHITLHandler | None" = None,
         **kwargs,
     ) -> str:
-        """Run an agent with a message, streaming via a renderer."""
+        """Run an agent with a message, streaming via a renderer.
+
+        Args:
+            agent_id: The ID of the agent to run.
+            message: The message to send to the agent.
+            files: Optional list of files to include with the request.
+            tty: Whether to enable TTY mode.
+            renderer: Renderer for streaming output.
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys should be platform IDs. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "mcp_configs": {"mcp-id": {"setting": "on"}},
+                    "agent_config": {"planning": True},
+                }
+            hitl_handler: Optional RemoteHITLHandler for approval callbacks.
+                Set GLAIP_HITL_AUTO_APPROVE=true for auto-approval without handler.
+            **kwargs: Additional arguments to pass to the run API.
+
+        Returns:
+            The agent's response as a string.
+        """
+        # Include runtime_config in kwargs only when caller hasn't already provided it
+        if runtime_config is not None and "runtime_config" not in kwargs:
+            kwargs["runtime_config"] = runtime_config
         (
             payload,
             data_payload,
@@ -957,6 +1192,7 @@ class AgentClient(BaseClient):
                     timeout_seconds,
                     agent_name,
                     meta,
+                    hitl_handler=hitl_handler,
                 )
 
         except KeyboardInterrupt:
@@ -973,6 +1209,13 @@ class AgentClient(BaseClient):
             if multipart_data:
                 multipart_data.close()
 
+        # Wait for pending HITL decisions before returning
+        if hitl_handler and hasattr(hitl_handler, "wait_for_pending_decisions"):
+            try:
+                hitl_handler.wait_for_pending_decisions(timeout=30)
+            except Exception as e:
+                logger.warning(f"Error waiting for HITL decisions: {e}")
+
         return self._finalize_renderer(
             r,
             final_text,
@@ -1009,9 +1252,7 @@ class AgentClient(BaseClient):
             headers = {"Accept": SSE_CONTENT_TYPE}
             return payload, None, None, headers
 
-    def _create_async_client_config(
-        self, timeout: float | None, headers: dict | None
-    ) -> dict:
+    def _create_async_client_config(self, timeout: float | None, headers: dict | None) -> dict:
         """Create async client configuration with proper headers and timeout."""
         config = self._build_async_client(timeout or self.timeout)
         if headers:
@@ -1040,9 +1281,7 @@ class AgentClient(BaseClient):
         ) as stream_response:
             stream_response.raise_for_status()
 
-            async for event in aiter_sse_events(
-                stream_response, timeout_seconds, agent_name
-            ):
+            async for event in aiter_sse_events(stream_response, timeout_seconds, agent_name):
                 try:
                     chunk = json.loads(event["data"])
                     yield chunk
@@ -1056,7 +1295,9 @@ class AgentClient(BaseClient):
         message: str,
         files: list[str | BinaryIO] | None = None,
         *,
-        timeout: float | None = None,
+        request_timeout: float | None = None,
+        runtime_config: dict[str, Any] | None = None,
+        hitl_handler: "RemoteHITLHandler | None" = None,
         **kwargs,
     ) -> AsyncGenerator[dict, None]:
         """Async run an agent with a message, yielding streaming JSON chunks.
@@ -1065,31 +1306,53 @@ class AgentClient(BaseClient):
             agent_id: ID of the agent to run
             message: Message to send to the agent
             files: Optional list of files to include
-            timeout: Request timeout in seconds
+            request_timeout: Optional request timeout in seconds (defaults to client timeout)
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys should be platform IDs. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "mcp_configs": {"mcp-id": {"setting": "on"}},
+                    "agent_config": {"planning": True},
+                }
+            hitl_handler: Optional HITL handler for remote approval requests.
+                Note: Async HITL support is currently deferred. This parameter
+                is accepted for API consistency but will raise NotImplementedError
+                if provided.
             **kwargs: Additional arguments (chat_history, pii_mapping, etc.)
 
         Yields:
             Dictionary containing parsed JSON chunks from the streaming response
 
         Raises:
+            NotImplementedError: If hitl_handler is provided (async HITL not yet supported)
             AgentTimeoutError: When agent execution times out
             httpx.TimeoutException: When general timeout occurs
             Exception: For other unexpected errors
         """
+        if hitl_handler is not None:
+            raise NotImplementedError(
+                "Async HITL support is currently deferred. "
+                "Please use the synchronous run_agent() method with hitl_handler."
+            )
+        # Include runtime_config in kwargs only when caller hasn't already provided it
+        if runtime_config is not None and "runtime_config" not in kwargs:
+            kwargs["runtime_config"] = runtime_config
+        # Derive timeout values for request/control flow
+        legacy_timeout = kwargs.get("timeout")
+        http_timeout_override = request_timeout if request_timeout is not None else legacy_timeout
+        http_timeout = http_timeout_override or self.timeout
+
         # Prepare request data
-        payload, data_payload, files_payload, headers = self._prepare_request_data(
-            message, files, **kwargs
-        )
+        payload, data_payload, files_payload, headers = self._prepare_request_data(message, files, **kwargs)
 
         # Create async client configuration
-        async_client_config = self._create_async_client_config(timeout, headers)
+        async_client_config = self._create_async_client_config(http_timeout_override, headers)
 
         # Get execution timeout for streaming control
         timeout_seconds = kwargs.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
         agent_name = kwargs.get("agent_name")
 
-        try:
-            # Create async client and stream response
+        async def _chunk_stream() -> AsyncGenerator[dict, None]:
             async with httpx.AsyncClient(**async_client_config) as async_client:
                 async for chunk in self._stream_agent_response(
                     async_client,
@@ -1103,7 +1366,14 @@ class AgentClient(BaseClient):
                 ):
                     yield chunk
 
-        finally:
-            # Ensure cleanup - this is handled by the calling context
-            # but we keep this for safety in case of future changes
-            pass
+        async with _async_timeout_guard(http_timeout):
+            async for chunk in _chunk_stream():
+                yield chunk
+
+    @property
+    def runs(self) -> "AgentRunsClient":
+        """Get the agent runs client."""
+        if self._runs_client is None:
+            shared_config = build_shared_config(self)
+            self._runs_client = AgentRunsClient(**shared_config)
+        return self._runs_client