glaip-sdk 0.0.15__py3-none-any.whl → 0.0.17__py3-none-any.whl

glaip_sdk/client/agents.py

@@ -5,20 +5,30 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-import io
 import json
 import logging
-from collections.abc import AsyncGenerator
-from time import monotonic
+from collections.abc import AsyncGenerator, Callable, Iterator, Mapping
+from os import PathLike
+from pathlib import Path
 from typing import Any, BinaryIO
 
 import httpx
-from rich.console import Console as _Console
 
+from glaip_sdk.client._agent_payloads import (
+    AgentCreateRequest,
+    AgentListParams,
+    AgentListResult,
+    AgentUpdateRequest,
+)
 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.tools import ToolClient
 from glaip_sdk.config.constants import (
     DEFAULT_AGENT_FRAMEWORK,
-    DEFAULT_AGENT_PROVIDER,
     DEFAULT_AGENT_RUN_TIMEOUT,
     DEFAULT_AGENT_TYPE,
     DEFAULT_AGENT_VERSION,
@@ -26,17 +36,21 @@ from glaip_sdk.config.constants import (
 )
 from glaip_sdk.exceptions import NotFoundError
 from glaip_sdk.models import Agent
+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 (
     aiter_sse_events,
     create_model_instances,
-    extract_ids,
     find_by_name,
-    iter_sse_events,
     prepare_multipart_data,
 )
-from glaip_sdk.utils.rendering.models import RunStats
+from glaip_sdk.utils.import_export import (
+    convert_export_to_import_format,
+    merge_import_with_cli_args,
+)
 from glaip_sdk.utils.rendering.renderer import RichStreamRenderer
-from glaip_sdk.utils.rendering.renderer.config import RendererConfig
+from glaip_sdk.utils.resource_refs import is_uuid
+from glaip_sdk.utils.serialization import load_resource_from_file
 from glaip_sdk.utils.validation import validate_agent_instruction
 
 # API endpoints
@@ -48,6 +62,145 @@ SSE_CONTENT_TYPE = "text/event-stream"
 # Set up module-level logger
 logger = logging.getLogger("glaip_sdk.agents")
 
+_SERVER_ONLY_IMPORT_FIELDS = set(list_server_only_fields()) | {"success", "message"}
+_MERGED_SEQUENCE_FIELDS = ("tools", "agents", "mcps")
+
+
+def _normalise_sequence(value: Any) -> list[Any] | None:
+    """Normalise optional sequence inputs to plain lists."""
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return value
+    if isinstance(value, (tuple, set)):
+        return list(value)
+    return [value]
+
+
+def _normalise_sequence_fields(mapping: dict[str, Any]) -> None:
+    """Normalise merged sequence fields in-place."""
+    for field in _MERGED_SEQUENCE_FIELDS:
+        if field in mapping:
+            normalised = _normalise_sequence(mapping[field])
+            if normalised is not None:
+                mapping[field] = normalised
+
+
+def _merge_override_maps(
+    base_values: Mapping[str, Any],
+    extra_values: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Merge override mappings while normalising sequence fields."""
+    merged: dict[str, Any] = {}
+    for source in (base_values, extra_values):
+        for key, value in source.items():
+            if value is None:
+                continue
+            merged[key] = (
+                _normalise_sequence(value) if key in _MERGED_SEQUENCE_FIELDS else value
+            )
+    return merged
+
+
+def _split_known_and_extra(
+    payload: Mapping[str, Any],
+    known_fields: Mapping[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Split payload mapping into known request fields and extras."""
+    known: dict[str, Any] = {}
+    extras: dict[str, Any] = {}
+    for key, value in payload.items():
+        if value is None:
+            continue
+        if key in known_fields:
+            known[key] = value
+        else:
+            extras[key] = value
+    return known, extras
+
+
+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}")
+    if not file_path.is_file():
+        raise ValueError(f"Agent configuration path must point to a file: {file_path}")
+
+    raw_data = load_resource_from_file(file_path)
+    if not isinstance(raw_data, Mapping):
+        raise ValueError("Agent configuration file must contain a mapping/object.")
+
+    payload = convert_export_to_import_format(dict(raw_data))
+    payload = normalize_agent_config_for_import(payload, model_override)
+
+    for field in _SERVER_ONLY_IMPORT_FIELDS:
+        payload.pop(field, None)
+
+    return payload
+
+
+def _prepare_import_payload(
+    file_path: Path,
+    overrides: Mapping[str, Any],
+    *,
+    drop_model_fields: bool = False,
+) -> dict[str, Any]:
+    """Prepare merged payload from file contents and explicit overrides."""
+    overrides_dict = dict(overrides)
+
+    raw_definition = load_resource_from_file(file_path)
+    original_refs = {
+        "tools": list(raw_definition.get("tools") or []),
+        "agents": list(raw_definition.get("agents") or []),
+        "mcps": list(raw_definition.get("mcps") or []),
+    }
+
+    base_payload = _load_agent_file_payload(
+        file_path, model_override=overrides_dict.get("model")
+    )
+
+    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
+    }
+
+    for field in _MERGED_SEQUENCE_FIELDS:
+        if field in cli_args:
+            cli_args[field] = tuple(_normalise_sequence(cli_args[field]) or [])
+
+    merged = merge_import_with_cli_args(base_payload, cli_args)
+
+    additional = {
+        key: value
+        for key, value in overrides_dict.items()
+        if value is not None and key not in cli_args
+    }
+    merged.update(additional)
+
+    if drop_model_fields:
+        if overrides_dict.get("language_model_id") is None:
+            merged.pop("language_model_id", None)
+        if overrides_dict.get("provider") is None:
+            merged.pop("provider", None)
+
+    merged.setdefault("_tool_refs", original_refs["tools"])
+    merged.setdefault("_agent_refs", original_refs["agents"])
+    merged.setdefault("_mcp_refs", original_refs["mcps"])
+
+    _normalise_sequence_fields(merged)
+    return merged
+
 
 class AgentClient(BaseClient):
     """Client for agent operations."""
@@ -65,44 +218,53 @@ class AgentClient(BaseClient):
             **kwargs: Additional arguments for standalone initialization
         """
         super().__init__(parent_client=parent_client, **kwargs)
+        self._renderer_manager = AgentRunRenderingManager(logger)
+        self._tool_client: ToolClient | None = None
+        self._mcp_client: MCPClient | None = None
 
     def list_agents(
         self,
-        agent_type: str | None = None,
-        framework: str | None = None,
-        name: str | None = None,
-        version: str | None = None,
-        sync_langflow_agents: bool = False,
-    ) -> list[Agent]:
-        """List agents with optional filtering.
+        query: AgentListParams | None = None,
+        **kwargs: Any,
+    ) -> AgentListResult:
+        """List agents with optional filtering and pagination support.
 
         Args:
-            agent_type: Filter by agent type (config, code, a2a)
-            framework: Filter by framework (langchain, langgraph, google_adk)
-            name: Filter by partial name match (case-insensitive)
-            version: Filter by exact version match
-            sync_langflow_agents: Sync with LangFlow server before listing (only applies when agent_type=langflow)
-
-        Returns:
-            List of agents matching the filters
+            query: Query parameters for filtering agents. If None, uses kwargs to create query.
+            **kwargs: Individual filter parameters for backward compatibility.
         """
-        params = {}
-        if agent_type is not None:
-            params["agent_type"] = agent_type
-        if framework is not None:
-            params["framework"] = framework
-        if name is not None:
-            params["name"] = name
-        if version is not None:
-            params["version"] = version
-        if sync_langflow_agents:
-            params["sync_langflow_agents"] = "true"
-
-        if params:
-            data = self._request("GET", AGENTS_ENDPOINT, params=params)
-        else:
-            data = self._request("GET", AGENTS_ENDPOINT)
-        return create_model_instances(data, Agent, self)
+        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."
+            )
+
+        if query is None:
+            # Create query from individual parameters for backward compatibility
+            query = AgentListParams(**kwargs)
+
+        params = query.to_query_params()
+        envelope = self._request_with_envelope(
+            "GET",
+            AGENTS_ENDPOINT,
+            params=params if params else None,
+        )
+
+        if not isinstance(envelope, dict):
+            envelope = {"data": envelope}
+
+        data_payload = envelope.get("data") or []
+        items = create_model_instances(data_payload, Agent, self)
+
+        return AgentListResult(
+            items=items,
+            total=envelope.get("total"),
+            page=envelope.get("page"),
+            limit=envelope.get("limit"),
+            has_next=envelope.get("has_next"),
+            has_prev=envelope.get("has_prev"),
+            message=envelope.get("message"),
+        )
 
     def sync_langflow_agents(
         self,
@@ -151,329 +313,423 @@ class AgentClient(BaseClient):
 
     def find_agents(self, name: str | None = None) -> list[Agent]:
         """Find agents by name."""
-        params = {}
-        if name:
-            params["name"] = name
-
-        data = self._request("GET", AGENTS_ENDPOINT, params=params)
-        agents = create_model_instances(data, Agent, self)
+        result = self.list_agents(name=name)
+        agents = list(result)
         if name is None:
             return agents
         return find_by_name(agents, name, case_sensitive=False)
 
-    def _build_create_payload(
-        self,
-        name: str,
-        instruction: str,
-        model: str = DEFAULT_MODEL,
-        tools: list[str | Any] | None = None,
-        agents: list[str | Any] | None = None,
-        timeout: int = DEFAULT_AGENT_RUN_TIMEOUT,
-        **kwargs: Any,
-    ) -> dict[str, Any]:
-        """Build payload for agent creation with proper LM selection and metadata handling.
-
-        CENTRALIZED PAYLOAD BUILDING LOGIC:
-        - LM exclusivity: Uses language_model_id if provided, otherwise provider/model_name
-        - Always includes required backend metadata
-        - Preserves mem0 keys in agent_config
-        - Handles tool/agent ID extraction from objects
-
-        Args:
-            name: Agent name
-            instruction: Agent instruction
-            model: Language model name (used when language_model_id not provided)
-            tools: List of tools to attach
-            agents: List of sub-agents to attach
-            timeout: Agent execution timeout
-            **kwargs: Additional parameters (language_model_id, agent_config, etc.)
-
-        Returns:
-            Complete payload dictionary for agent creation
-        """
-        # Prepare the creation payload with required fields
-        payload: dict[str, Any] = {
-            "name": name.strip(),
-            "instruction": instruction.strip(),
-            "type": DEFAULT_AGENT_TYPE,
-            "framework": DEFAULT_AGENT_FRAMEWORK,
-            "version": DEFAULT_AGENT_VERSION,
-        }
-
-        # Language model selection with exclusivity:
-        # Priority: language_model_id (if provided) > provider/model_name (fallback)
-        if kwargs.get("language_model_id"):
-            # Use language_model_id - defer to kwargs update below
-            pass
-        else:
-            # Use provider/model_name fallback
-            payload["provider"] = DEFAULT_AGENT_PROVIDER
-            payload["model_name"] = model or DEFAULT_MODEL
-
-        # Include execution timeout if provided
-        if timeout is not None:
-            payload["timeout"] = str(timeout)
-
-        # Ensure minimum required metadata for visibility
-        if "metadata" not in kwargs:
-            kwargs["metadata"] = {}
-        if "type" not in kwargs["metadata"]:
-            kwargs["metadata"]["type"] = "custom"
+    # ------------------------------------------------------------------ #
+    # Renderer delegation helpers
+    # ------------------------------------------------------------------ #
+    def _get_renderer_manager(self) -> AgentRunRenderingManager:
+        manager = getattr(self, "_renderer_manager", None)
+        if manager is None:
+            manager = AgentRunRenderingManager(logger)
+            self._renderer_manager = manager
+        return manager
 
-        # Extract IDs from tool and agent objects
-        tool_ids = extract_ids(tools)
-        agent_ids = extract_ids(agents)
+    def _create_renderer(
+        self, renderer: RichStreamRenderer | str | None, **kwargs: Any
+    ) -> RichStreamRenderer:
+        manager = self._get_renderer_manager()
+        verbose = kwargs.get("verbose", False)
+        if isinstance(renderer, RichStreamRenderer) or hasattr(renderer, "on_start"):
+            return renderer  # type: ignore[return-value]
+        return manager.create_renderer(renderer, verbose=verbose)
 
-        # Add tools and agents if provided
-        if tool_ids:
-            payload["tools"] = tool_ids
-        if agent_ids:
-            payload["agents"] = agent_ids
+    def _process_stream_events(
+        self,
+        stream_response: httpx.Response,
+        renderer: RichStreamRenderer,
+        timeout_seconds: float,
+        agent_name: str | None,
+        meta: dict[str, Any],
+    ) -> tuple[str, dict[str, Any], float | None, float | None]:
+        manager = self._get_renderer_manager()
+        return manager.process_stream_events(
+            stream_response,
+            renderer,
+            timeout_seconds,
+            agent_name,
+            meta,
+        )
 
-        # Add any additional kwargs (including language_model_id, agent_config, etc.)
-        payload.update(kwargs)
+    def _finalize_renderer(
+        self,
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        started_monotonic: float | None,
+        finished_monotonic: float | None,
+    ) -> str:
+        manager = self._get_renderer_manager()
+        return manager.finalize_renderer(
+            renderer,
+            final_text,
+            stats_usage,
+            started_monotonic,
+            finished_monotonic,
+        )
 
-        return payload
+    def _get_tool_client(self) -> ToolClient:
+        if self._tool_client is None:
+            self._tool_client = ToolClient(parent_client=self)
+        return self._tool_client
 
-    def _build_basic_update_payload(
-        self, current_agent: "Agent", name: str | None, instruction: str | None
-    ) -> dict[str, Any]:
-        """Build the basic update payload with required fields."""
-        return {
-            "name": name if name is not None else current_agent.name,
-            "instruction": instruction
-            if instruction is not None
-            else current_agent.instruction,
-            "type": DEFAULT_AGENT_TYPE,  # Required by backend
-            "framework": DEFAULT_AGENT_FRAMEWORK,  # Required by backend
-            "version": DEFAULT_AGENT_VERSION,  # Required by backend
-        }
+    def _get_mcp_client(self) -> MCPClient:
+        if self._mcp_client is None:
+            self._mcp_client = MCPClient(parent_client=self)
+        return self._mcp_client
 
-    def _handle_language_model_selection(
+    def _normalise_reference_entry(
         self,
-        update_data: dict[str, Any],
-        current_agent: "Agent",
-        model: str | None,
-        language_model_id: str | None,
-    ) -> None:
-        """Handle language model selection with proper priority and fallbacks."""
-        if language_model_id:
-            # Use language_model_id if provided
-            update_data["language_model_id"] = language_model_id
-        elif model is not None:
-            # Use explicit model parameter
-            update_data["provider"] = DEFAULT_AGENT_PROVIDER
-            update_data["model_name"] = model
+        entry: Any,
+        fallback_iter: Iterator[Any] | None,
+    ) -> tuple[str | None, str | None]:
+        entry_id: str | None = None
+        entry_name: str | None = None
+
+        if isinstance(entry, str):
+            if is_uuid(entry):
+                entry_id = entry
+            else:
+                entry_name = entry
+        elif isinstance(entry, dict):
+            entry_id = entry.get("id")
+            entry_name = entry.get("name")
         else:
-            # Use current agent config or fallbacks
-            self._set_language_model_from_current_agent(update_data, current_agent)
+            entry_name = str(entry)
 
-    def _set_language_model_from_current_agent(
-        self, update_data: dict[str, Any], current_agent: "Agent"
-    ) -> None:
-        """Set language model from current agent config or use defaults."""
-        if hasattr(current_agent, "agent_config") and current_agent.agent_config:
-            agent_config = current_agent.agent_config
-            if "lm_provider" in agent_config:
-                update_data["provider"] = agent_config["lm_provider"]
-            if "lm_name" in agent_config:
-                update_data["model_name"] = agent_config["lm_name"]
-        else:
-            # Default fallback values
-            update_data["provider"] = DEFAULT_AGENT_PROVIDER
-            update_data["model_name"] = DEFAULT_MODEL
+        if entry_name or fallback_iter is None:
+            return entry_id, entry_name
 
-    def _handle_tools_and_agents(
-        self,
-        update_data: dict[str, Any],
-        current_agent: "Agent",
-        tools: list | None,
-        agents: list | None,
-    ) -> None:
-        """Handle tools and agents with proper ID extraction."""
-        # Handle tools
-        if tools is not None:
-            tool_ids = extract_ids(tools)
-            update_data["tools"] = tool_ids if tool_ids else []
-        else:
-            update_data["tools"] = self._extract_current_tool_ids(current_agent)
+        try:
+            ref = next(fallback_iter)
+        except StopIteration:
+            ref = None
+        if isinstance(ref, dict):
+            entry_name = ref.get("name") or entry_name
 
-        # Handle agents
-        if agents is not None:
-            agent_ids = extract_ids(agents)
-            update_data["agents"] = agent_ids if agent_ids else []
-        else:
-            update_data["agents"] = self._extract_current_agent_ids(current_agent)
-
-    def _extract_current_tool_ids(self, current_agent: "Agent") -> list[str]:
-        """Extract tool IDs from current agent."""
-        if current_agent.tools:
-            return [
-                tool["id"] if isinstance(tool, dict) else tool
-                for tool in current_agent.tools
-            ]
-        return []
-
-    def _extract_current_agent_ids(self, current_agent: "Agent") -> list[str]:
-        """Extract agent IDs from current agent."""
-        if current_agent.agents:
-            return [
-                agent["id"] if isinstance(agent, dict) else agent
-                for agent in current_agent.agents
-            ]
-        return []
+        return entry_id, entry_name
 
-    def _handle_agent_config(
+    def _resolve_resource_ids(
         self,
-        update_data: dict[str, Any],
-        current_agent: "Agent",
-        agent_config: dict | None,
-    ) -> None:
-        """Handle agent_config with proper merging and cleanup."""
-        if agent_config is not None:
-            # Use provided agent_config, merging with current if needed
-            update_data["agent_config"] = self._merge_agent_configs(
-                current_agent, agent_config
+        items: list[Any] | None,
+        references: list[Any] | None,
+        *,
+        fetch_by_id: Callable[[str], Any],
+        find_by_name: Callable[[str], list[Any]],
+        label: str,
+        plural_label: str | None = None,
+    ) -> list[str] | None:
+        if not items:
+            return None
+
+        if references is None:
+            return [self._coerce_reference_value(entry) for entry in items]
+
+        singular = label
+        plural = plural_label or f"{label}s"
+        fallback_iter = iter(references or [])
+
+        return [
+            self._resolve_single_resource(
+                entry,
+                fallback_iter,
+                fetch_by_id,
+                find_by_name,
+                singular,
+                plural,
             )
-        elif hasattr(current_agent, "agent_config") and current_agent.agent_config:
-            # Preserve existing agent_config
-            update_data["agent_config"] = current_agent.agent_config.copy()
-        else:
-            # Default agent_config
-            update_data["agent_config"] = {
-                "lm_provider": DEFAULT_AGENT_PROVIDER,
-                "lm_name": DEFAULT_MODEL,
-                "lm_hyperparameters": {"temperature": 0.0},
-            }
-
-        # Clean LM keys from agent_config to prevent conflicts
-        self._clean_agent_config_lm_keys(update_data)
-
-    def _merge_agent_configs(self, current_agent: "Agent", new_config: dict) -> dict:
-        """Merge current agent config with new config."""
-        if hasattr(current_agent, "agent_config") and current_agent.agent_config:
-            merged_config = current_agent.agent_config.copy()
-            merged_config.update(new_config)
-            return merged_config
-        return new_config
-
-    def _clean_agent_config_lm_keys(self, update_data: dict[str, Any]) -> None:
-        """Remove LM keys from agent_config to prevent conflicts."""
-        if "agent_config" in update_data and isinstance(
-            update_data["agent_config"], dict
-        ):
-            agent_config = update_data["agent_config"]
-            lm_keys_to_remove = {
-                "lm_provider",
-                "lm_name",
-                "lm_base_url",
-                "lm_hyperparameters",
-            }
-            for key in lm_keys_to_remove:
-                agent_config.pop(key, None)
-
-    def _finalize_update_payload(
+            for entry in items
+        ]
+
+    def _resolve_single_resource(
         self,
-        update_data: dict[str, Any],
-        current_agent: "Agent",
-        **kwargs: Any,
-    ) -> dict[str, Any]:
-        """Finalize the update payload with metadata and additional kwargs."""
-        # Handle metadata preservation
-        if hasattr(current_agent, "metadata") and current_agent.metadata:
-            update_data["metadata"] = current_agent.metadata.copy()
+        entry: Any,
+        fallback_iter: Iterator[Any] | None,
+        fetch_by_id: Callable[[str], Any],
+        find_by_name: Callable[[str], list[Any]],
+        singular: str,
+        plural: str,
+    ) -> str:
+        entry_id, entry_name = self._normalise_reference_entry(entry, fallback_iter)
 
-        # Add any other kwargs (excluding already handled ones)
-        excluded_keys = {"tools", "agents", "agent_config", "language_model_id"}
-        for key, value in kwargs.items():
-            if key not in excluded_keys:
-                update_data[key] = value
+        validated_id = self._validate_resource_id(fetch_by_id, entry_id)
+        if validated_id:
+            return validated_id
+        if entry_id and entry_name is None:
+            return entry_id
 
-        return update_data
+        if entry_name:
+            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:
+        if isinstance(entry, dict):
+            if entry.get("id"):
+                return str(entry["id"])
+            if entry.get("name"):
+                return str(entry["name"])
+        return str(entry)
+
+    @staticmethod
+    def _validate_resource_id(
+        fetch_by_id: Callable[[str], Any], candidate_id: str | None
+    ) -> str | None:
+        if not candidate_id:
+            return None
+        try:
+            fetch_by_id(candidate_id)
+        except Exception:
+            return None
+        return candidate_id
+
+    @staticmethod
+    def _resolve_resource_by_name(
+        find_by_name: Callable[[str], list[Any]],
+        entry_name: str,
+        singular: str,
+        plural: str,
+    ) -> tuple[str, bool]:
+        try:
+            matches = find_by_name(entry_name)
+        except Exception:
+            return entry_name, False
 
-    def _build_update_payload(
-        self,
-        current_agent: "Agent",
-        name: str | None = None,
-        instruction: str | None = None,
-        model: str | None = None,
-        **kwargs: Any,
-    ) -> dict[str, Any]:
-        """Build payload for agent update with proper LM selection and current state preservation.
+        if not matches:
+            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()
+            ]
+            if len(exact) == 1:
+                matches = exact
+            else:
+                raise ValueError(
+                    f"Multiple {plural} named '{entry_name}'. Please disambiguate."
+                )
+        return str(matches[0].id), True
 
-        Args:
-            current_agent: Current agent object to update
-            name: New agent name (None to keep current)
-            instruction: New instruction (None to keep current)
-            model: New language model name (None to use current or fallback)
-            **kwargs: Additional parameters including language_model_id, agent_config, etc.
+    def _resolve_tool_ids(
+        self,
+        tools: list[Any] | None,
+        references: list[Any] | None = None,
+    ) -> list[str] | None:
+        tool_client = self._get_tool_client()
+        return self._resolve_resource_ids(
+            tools,
+            references,
+            fetch_by_id=tool_client.get_tool_by_id,
+            find_by_name=tool_client.find_tools,
+            label="Tool",
+            plural_label="tools",
+        )
 
-        Returns:
-            Complete payload dictionary for agent update
+    def _resolve_agent_ids(
+        self,
+        agents: list[Any] | None,
+        references: list[Any] | None = None,
+    ) -> list[str] | None:
+        return self._resolve_resource_ids(
+            agents,
+            references,
+            fetch_by_id=self.get_agent_by_id,
+            find_by_name=self.find_agents,
+            label="Agent",
+            plural_label="agents",
+        )
 
-        Notes:
-            - LM exclusivity: Uses language_model_id if provided, otherwise provider/model_name
-            - Preserves current values as defaults when new values not provided
-            - Handles tools/agents updates with proper ID extraction
-        """
-        # Build basic payload
-        update_data = self._build_basic_update_payload(current_agent, name, instruction)
+    def _resolve_mcp_ids(
+        self,
+        mcps: list[Any] | None,
+        references: list[Any] | None = None,
+    ) -> list[str] | None:
+        mcp_client = self._get_mcp_client()
+        return self._resolve_resource_ids(
+            mcps,
+            references,
+            fetch_by_id=mcp_client.get_mcp_by_id,
+            find_by_name=mcp_client.find_mcps,
+            label="MCP",
+            plural_label="MCPs",
+        )
 
-        # Handle language model selection
-        language_model_id = kwargs.get("language_model_id")
-        self._handle_language_model_selection(
-            update_data, current_agent, model, language_model_id
+    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__
         )
 
-        # Handle tools and agents
-        tools = kwargs.get("tools")
-        agents = kwargs.get("agents")
-        self._handle_tools_and_agents(update_data, current_agent, tools, agents)
+        name = known.pop("name", None)
+        instruction = known.pop("instruction", None)
+        if not name or not str(name).strip():
+            raise ValueError("Agent name cannot be empty or whitespace")
+        if not instruction or not str(instruction).strip():
+            raise ValueError("Agent instruction cannot be empty or whitespace")
+
+        validated_instruction = validate_agent_instruction(str(instruction))
+        _normalise_sequence_fields(known)
+
+        resolved_model = known.pop("model", None) or DEFAULT_MODEL
+        tool_refs = extras.pop("_tool_refs", None)
+        agent_refs = extras.pop("_agent_refs", None)
+        mcp_refs = extras.pop("_mcp_refs", None)
+
+        tools_raw = known.pop("tools", None)
+        agents_raw = known.pop("agents", None)
+        mcps_raw = known.pop("mcps", None)
+
+        resolved_tools = self._resolve_tool_ids(tools_raw, tool_refs)
+        resolved_agents = self._resolve_agent_ids(agents_raw, agent_refs)
+        resolved_mcps = self._resolve_mcp_ids(mcps_raw, mcp_refs)
+
+        final_extras = {**known, **extras}
+        final_extras.setdefault("model", resolved_model)
+
+        request = AgentCreateRequest(
+            name=str(name).strip(),
+            instruction=validated_instruction,
+            model=resolved_model,
+            language_model_id=known.pop("language_model_id", None),
+            provider=known.pop("provider", None),
+            model_name=known.pop("model_name", None),
+            agent_type=known.pop("agent_type", known.pop("type", DEFAULT_AGENT_TYPE)),
+            framework=known.pop("framework", None) or DEFAULT_AGENT_FRAMEWORK,
+            version=known.pop("version", None) or DEFAULT_AGENT_VERSION,
+            account_id=known.pop("account_id", None),
+            description=known.pop("description", None),
+            metadata=known.pop("metadata", None),
+            tools=resolved_tools,
+            agents=resolved_agents,
+            mcps=resolved_mcps,
+            tool_configs=known.pop("tool_configs", None),
+            agent_config=known.pop("agent_config", None),
+            timeout=known.pop("timeout", None) or DEFAULT_AGENT_RUN_TIMEOUT,
+            a2a_profile=known.pop("a2a_profile", None),
+            extras=final_extras,
+        )
 
-        # Handle agent config
-        agent_config = kwargs.get("agent_config")
-        self._handle_agent_config(update_data, current_agent, agent_config)
+        payload_dict = request.to_payload()
+        payload_dict.setdefault("model", resolved_model)
 
-        # Finalize payload
-        return self._finalize_update_payload(update_data, current_agent, **kwargs)
+        full_agent_data = self._post_then_fetch(
+            id_key="id",
+            post_endpoint=AGENTS_ENDPOINT,
+            get_endpoint_fmt=f"{AGENTS_ENDPOINT}{{id}}",
+            json=payload_dict,
+        )
+        return Agent(**full_agent_data)._set_client(self)
 
     def create_agent(
         self,
-        name: str,
-        instruction: str,
-        model: str = DEFAULT_MODEL,
+        name: str | None = None,
+        instruction: str | None = None,
+        model: str | None = None,
         tools: list[str | Any] | None = None,
         agents: list[str | Any] | None = None,
-        timeout: int = DEFAULT_AGENT_RUN_TIMEOUT,
+        timeout: int | None = None,
+        *,
+        file: str | PathLike[str] | None = None,
+        mcps: list[str | Any] | None = None,
+        tool_configs: Mapping[str, Any] | None = None,
         **kwargs: Any,
     ) -> "Agent":
-        """Create a new agent."""
-        # Client-side validation
-        if not name or not name.strip():
-            raise ValueError("Agent name cannot be empty or whitespace")
+        """Create a new agent, optionally loading configuration from a file."""
+        base_overrides = {
+            "name": name,
+            "instruction": instruction,
+            "model": model,
+            "tools": tools,
+            "agents": agents,
+            "timeout": timeout,
+            "mcps": mcps,
+            "tool_configs": tool_configs,
+        }
+        overrides = _merge_override_maps(base_overrides, kwargs)
 
-        # Validate instruction using centralized validation
-        instruction = validate_agent_instruction(instruction)
-
-        # Build payload using centralized builder
-        payload = self._build_create_payload(
-            name=name,
-            instruction=instruction,
-            model=model,
-            tools=tools,
-            agents=agents,
-            timeout=timeout,
-            **kwargs,
-        )
+        if file is not None:
+            payload = _prepare_import_payload(
+                Path(file).expanduser(), overrides, drop_model_fields=True
+            )
+            if overrides.get("model") is None:
+                payload.pop("model", None)
+        else:
+            payload = overrides
 
-        # Create the agent and fetch full details
-        full_agent_data = self._post_then_fetch(
-            id_key="id",
-            post_endpoint=AGENTS_ENDPOINT,
-            get_endpoint_fmt=f"{AGENTS_ENDPOINT}{{id}}",
-            json=payload,
+        return self._create_agent_from_payload(payload)
+
+    def create_agent_from_file(  # pragma: no cover - thin compatibility wrapper
+        self,
+        file_path: str | PathLike[str],
+        **overrides: Any,
+    ) -> "Agent":
+        """Backward-compatible helper to create an agent from a configuration file."""
+        return self.create_agent(file=file_path, **overrides)
+
+    def _update_agent_from_payload(
+        self,
+        agent_id: str,
+        current_agent: Agent,
+        payload: Mapping[str, Any],
+    ) -> "Agent":
+        """Update an agent using a prepared payload mapping."""
+        known, extras = _split_known_and_extra(
+            payload, AgentUpdateRequest.__dataclass_fields__
+        )
+        _normalise_sequence_fields(known)
+
+        tool_refs = extras.pop("_tool_refs", None)
+        agent_refs = extras.pop("_agent_refs", None)
+        mcp_refs = extras.pop("_mcp_refs", None)
+
+        tools_value = known.pop("tools", None)
+        agents_value = known.pop("agents", None)
+        mcps_value = known.pop("mcps", None)
+
+        if tools_value is not None:
+            tools_value = self._resolve_tool_ids(tools_value, tool_refs)
+        if agents_value is not None:
+            agents_value = self._resolve_agent_ids(agents_value, agent_refs)
+        if mcps_value is not None:
+            mcps_value = self._resolve_mcp_ids(mcps_value, mcp_refs)  # pragma: no cover
+
+        request = AgentUpdateRequest(
+            name=known.pop("name", None),
+            instruction=known.pop("instruction", None),
+            description=known.pop("description", None),
+            model=known.pop("model", None),
+            language_model_id=known.pop("language_model_id", None),
+            provider=known.pop("provider", None),
+            model_name=known.pop("model_name", None),
+            agent_type=known.pop("agent_type", known.pop("type", None)),
+            framework=known.pop("framework", None),
+            version=known.pop("version", None),
+            account_id=known.pop("account_id", None),
+            metadata=known.pop("metadata", None),
+            tools=tools_value,
+            tool_configs=known.pop("tool_configs", None),
+            agents=agents_value,
+            mcps=mcps_value,
+            agent_config=known.pop("agent_config", None),
+            a2a_profile=known.pop("a2a_profile", None),
+            extras={**known, **extras},
         )
-        return Agent(**full_agent_data)._set_client(self)
+
+        payload_dict = request.to_payload(current_agent)
+
+        response = self._request("PUT", f"/agents/{agent_id}", json=payload_dict)
+        return Agent(**response)._set_client(self)
 
     def update_agent(
         self,
@@ -481,24 +737,42 @@ class AgentClient(BaseClient):
         name: str | None = None,
         instruction: str | None = None,
         model: str | None = None,
+        *,
+        file: str | PathLike[str] | None = None,
+        tools: list[str | Any] | None = None,
+        agents: list[str | Any] | None = None,
+        mcps: list[str | Any] | None = None,
         **kwargs: Any,
     ) -> "Agent":
         """Update an existing agent."""
-        # First, get the current agent data
-        current_agent = self.get_agent_by_id(agent_id)
+        base_overrides = {
+            "name": name,
+            "instruction": instruction,
+            "model": model,
+            "tools": tools,
+            "agents": agents,
+            "mcps": mcps,
+        }
+        overrides = _merge_override_maps(base_overrides, kwargs)
 
-        # Build payload using centralized builder
-        update_data = self._build_update_payload(
-            current_agent=current_agent,
-            name=name,
-            instruction=instruction,
-            model=model,
-            **kwargs,
-        )
+        if file is not None:
+            payload = _prepare_import_payload(
+                Path(file).expanduser(), overrides, drop_model_fields=True
+            )
+        else:
+            payload = overrides
 
-        # Send the complete payload
-        data = self._request("PUT", f"/agents/{agent_id}", json=update_data)
-        return Agent(**data)._set_client(self)
+        current_agent = self.get_agent_by_id(agent_id)
+        return self._update_agent_from_payload(agent_id, current_agent, payload)
+
+    def update_agent_from_file(  # pragma: no cover - thin compatibility wrapper
+        self,
+        agent_id: str,
+        file_path: str | PathLike[str],
+        **overrides: Any,
+    ) -> "Agent":
+        """Backward-compatible helper to update an agent from a configuration file."""
+        return self.update_agent(agent_id, file=file_path, **overrides)
 
     def delete_agent(self, agent_id: str) -> None:
         """Delete an agent."""
@@ -562,197 +836,6 @@ class AgentClient(BaseClient):
         execution_timeout = kwargs.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
         return request_timeout, execution_timeout
 
-    def _create_renderer(
-        self, renderer: RichStreamRenderer | None, **kwargs: Any
-    ) -> RichStreamRenderer:
-        """Create appropriate renderer based on configuration."""
-        if isinstance(renderer, RichStreamRenderer):
-            return renderer
-
-        verbose = kwargs.get("verbose", False)
-
-        if isinstance(renderer, str):
-            if renderer == "silent":
-                return self._create_silent_renderer()
-            elif renderer == "minimal":
-                return self._create_minimal_renderer()
-            else:
-                return self._create_default_renderer(verbose)
-        elif verbose:
-            return self._create_verbose_renderer()
-        else:
-            return self._create_default_renderer(verbose)
-
-    def _create_silent_renderer(self) -> RichStreamRenderer:
-        """Create a silent renderer that suppresses all output."""
-        silent_config = RendererConfig(
-            live=False,
-            persist_live=False,
-            show_delegate_tool_panels=False,
-            render_thinking=False,
-        )
-        return RichStreamRenderer(
-            console=_Console(file=io.StringIO(), force_terminal=False),
-            cfg=silent_config,
-            verbose=False,
-        )
-
-    def _create_minimal_renderer(self) -> RichStreamRenderer:
-        """Create a minimal renderer with basic output."""
-        minimal_config = RendererConfig(
-            live=False,
-            persist_live=False,
-            show_delegate_tool_panels=False,
-            render_thinking=False,
-        )
-        return RichStreamRenderer(
-            console=_Console(),
-            cfg=minimal_config,
-            verbose=False,
-        )
-
-    def _create_verbose_renderer(self) -> RichStreamRenderer:
-        """Create a verbose renderer for detailed output."""
-        verbose_config = RendererConfig(
-            theme="dark",
-            style="debug",
-            live=False,
-            show_delegate_tool_panels=True,
-            append_finished_snapshots=False,
-        )
-        return RichStreamRenderer(
-            console=_Console(),
-            cfg=verbose_config,
-            verbose=True,
-        )
-
-    def _create_default_renderer(self, verbose: bool) -> RichStreamRenderer:
-        """Create the default renderer."""
-        if verbose:
-            return self._create_verbose_renderer()
-        else:
-            default_config = RendererConfig(show_delegate_tool_panels=True)
-            return RichStreamRenderer(console=_Console(), cfg=default_config)
-
-    def _initialize_stream_metadata(self, kwargs: dict[str, Any]) -> dict[str, Any]:
-        """Initialize stream metadata."""
-        return {
-            "agent_name": kwargs.get("agent_name", ""),
-            "model": kwargs.get("model"),
-            "run_id": None,
-            "input_message": "",  # Will be set from kwargs if available
-        }
-
-    def _capture_request_id(
-        self,
-        stream_response: httpx.Response,
-        meta: dict[str, Any],
-        renderer: RichStreamRenderer,
-    ) -> None:
-        """Capture request ID from response headers."""
-        req_id = stream_response.headers.get(
-            "x-request-id"
-        ) or stream_response.headers.get("x-run-id")
-        if req_id:
-            meta["run_id"] = req_id
-            renderer.on_start(meta)
-
-    def _should_start_timer(self, ev: dict[str, Any]) -> bool:
-        """Check if timer should be started for this event."""
-        return "content" in ev or "status" in ev or ev.get("metadata")
-
-    def _handle_content_event(self, ev: dict[str, Any], final_text: str) -> str:
-        """Handle content events."""
-        content = ev.get("content", "")
-        if not content.startswith("Artifact received:"):
-            return content
-        return final_text
-
-    def _handle_usage_event(
-        self, ev: dict[str, Any], stats_usage: dict[str, Any]
-    ) -> None:
-        """Handle usage events."""
-        stats_usage.update(ev.get("usage") or {})
-
-    def _handle_run_info_event(
-        self, ev: dict[str, Any], meta: dict[str, Any], renderer: RichStreamRenderer
-    ) -> None:
-        """Handle run info events."""
-        if ev.get("model"):
-            meta["model"] = ev["model"]
-            renderer.on_start(meta)
-        if ev.get("run_id"):
-            meta["run_id"] = ev["run_id"]
-            renderer.on_start(meta)
-
-    def _process_single_event(
-        self,
-        event: dict[str, Any],
-        renderer: RichStreamRenderer,
-        final_text: str,
-        stats_usage: dict[str, Any],
-        meta: dict[str, Any],
-    ) -> tuple[str, dict[str, Any]]:
-        """Process a single streaming event."""
-        try:
-            ev = json.loads(event["data"])
-        except json.JSONDecodeError:
-            logger.debug("Non-JSON SSE fragment skipped")
-            return final_text, stats_usage
-
-        kind = (ev.get("metadata") or {}).get("kind")
-        renderer.on_event(ev)
-
-        # Skip artifacts from content accumulation
-        if kind == "artifact":
-            return final_text, stats_usage
-
-        # Handle different event types
-        if kind == "final_response" and ev.get("content"):
-            final_text = ev.get("content", "")
-        elif ev.get("content"):
-            final_text = self._handle_content_event(ev, final_text)
-        elif kind == "usage":
-            self._handle_usage_event(ev, stats_usage)
-        elif kind == "run_info":
-            self._handle_run_info_event(ev, meta, renderer)
-
-        return final_text, stats_usage
-
-    def _process_stream_events(
-        self,
-        stream_response: httpx.Response,
-        renderer: RichStreamRenderer,
-        timeout_seconds: float,
-        agent_name: str | None,
-        kwargs: dict[str, Any],
-    ) -> tuple[str, dict[str, Any], float | None, float | None]:
-        """Process streaming events and accumulate response."""
-        final_text = ""
-        stats_usage = {}
-        started_monotonic = None
-        finished_monotonic = None
-
-        meta = self._initialize_stream_metadata(kwargs)
-        self._capture_request_id(stream_response, meta, renderer)
-
-        for event in iter_sse_events(stream_response, timeout_seconds, agent_name):
-            # Start timer at first meaningful event
-            if started_monotonic is None:
-                try:
-                    ev = json.loads(event["data"])
-                    if self._should_start_timer(ev):
-                        started_monotonic = monotonic()
-                except json.JSONDecodeError:
-                    pass
-
-            final_text, stats_usage = self._process_single_event(
-                event, renderer, final_text, stats_usage, meta
-            )
-
-        finished_monotonic = monotonic()
-        return final_text, stats_usage, started_monotonic, finished_monotonic
-
     def run_agent(
         self,
         agent_id: str,
@@ -764,7 +847,6 @@ class AgentClient(BaseClient):
         **kwargs,
     ) -> str:
         """Run an agent with a message, streaming via a renderer."""
-        # Prepare request payload and headers
         (
             payload,
             data_payload,
@@ -773,20 +855,18 @@ class AgentClient(BaseClient):
             multipart_data,
         ) = self._prepare_sync_request_data(message, files, tty, **kwargs)
 
-        # Create renderer
-        r = self._create_renderer(renderer, **kwargs)
+        render_manager = self._get_renderer_manager()
+        verbose = kwargs.get("verbose", False)
+        r = self._create_renderer(renderer, verbose=verbose)
+        meta = render_manager.build_initial_metadata(agent_id, message, kwargs)
+        render_manager.start_renderer(r, meta)
 
-        # Initialize renderer
-        meta = {
-            "agent_name": kwargs.get("agent_name", agent_id),
-            "model": kwargs.get("model"),
-            "run_id": None,
-            "input_message": message,
-        }
-        r.on_start(meta)
+        final_text = ""
+        stats_usage: dict[str, Any] = {}
+        started_monotonic: float | None = None
+        finished_monotonic: float | None = None
 
         try:
-            # Make streaming request
             response = self.http_client.stream(
                 "POST",
                 f"/agents/{agent_id}/run",
@@ -799,8 +879,7 @@ class AgentClient(BaseClient):
             with response as stream_response:
                 stream_response.raise_for_status()
 
-                # Process streaming events
-                timeout_seconds = kwargs.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
+                timeout_seconds = compute_timeout_seconds(kwargs)
                 agent_name = kwargs.get("agent_name")
 
                 (
@@ -809,7 +888,11 @@ class AgentClient(BaseClient):
                     started_monotonic,
                     finished_monotonic,
                 ) = self._process_stream_events(
-                    stream_response, r, timeout_seconds, agent_name, kwargs
+                    stream_response,
+                    r,
+                    timeout_seconds,
+                    agent_name,
+                    meta,
                 )
 
         except KeyboardInterrupt:
@@ -823,25 +906,16 @@ class AgentClient(BaseClient):
             finally:
                 raise
         finally:
-            # Ensure cleanup
             if multipart_data:
                 multipart_data.close()
 
-        # Finalize and return result
-        st = RunStats()
-        st.started_at = started_monotonic or st.started_at
-        st.finished_at = finished_monotonic or st.started_at
-        st.usage = stats_usage
-
-        # Get final content
-        if hasattr(r, "state") and hasattr(r.state, "buffer"):
-            rendered_text = "".join(r.state.buffer)
-        else:
-            rendered_text = ""
-
-        final_payload = final_text or rendered_text or "No response content received."
-        r.on_complete(st)
-        return final_payload
+        return self._finalize_renderer(
+            r,
+            final_text,
+            stats_usage,
+            started_monotonic,
+            finished_monotonic,
+        )
 
     def _prepare_request_data(
         self,