glaip-sdk 0.0.5b1__py3-none-any.whl → 0.0.7__py3-none-any.whl

glaip_sdk/cli/commands/agents.py

@@ -7,6 +7,7 @@ Authors:
 import json
 import os
 from pathlib import Path
+from typing import Any
 
 import click
 from rich.console import Console
@@ -46,7 +47,9 @@ from glaip_sdk.cli.utils import (
     _fuzzy_pick_for_resources,
     build_renderer,
     coerce_to_row,
+    detect_export_format,
     get_client,
+    get_ctx_value,
     output_flags,
     output_list,
     output_result,
@@ -73,7 +76,7 @@ console = Console()
 AGENT_NOT_FOUND_ERROR = "Agent not found"
 
 
-def _fetch_full_agent_details(client, agent):
+def _fetch_full_agent_details(client: Any, agent: Any) -> Any | None:
     """Fetch full agent details by ID to ensure all fields are populated."""
     try:
         agent_id = str(getattr(agent, "id", "")).strip()
@@ -85,7 +88,7 @@ def _fetch_full_agent_details(client, agent):
     return agent
 
 
-def _get_agent_model_name(agent):
+def _get_agent_model_name(agent: Any) -> str | None:
     """Extract model name from agent configuration."""
     # Try different possible locations for model name
     if hasattr(agent, "agent_config") and agent.agent_config:
@@ -100,7 +103,7 @@ def _get_agent_model_name(agent):
 
 
 def _resolve_resources_by_name(
-    _client, items: tuple[str, ...], resource_type: str, find_func, label: str
+    _client: Any, items: tuple[str, ...], resource_type: str, find_func: Any, label: str
 ) -> list[str]:
     """Resolve resource names/IDs to IDs, handling ambiguity.
 
@@ -131,90 +134,112 @@ def _resolve_resources_by_name(
     return out
 
 
-def _display_agent_details(ctx, client, agent):
-    """Display full agent details using raw API data to preserve ALL fields."""
-    if agent is None:
-        handle_rich_output(ctx, Text("[red]❌ No agent provided[/red]"))
-        return
-
-    # Try to fetch raw API data first to preserve ALL fields
-    raw_agent_data = fetch_raw_resource_details(client, agent, "agents")
+def _fetch_and_format_raw_agent_data(client: Any, agent: Any) -> dict | None:
+    """Fetch raw agent data and format it for display."""
+    try:
+        raw_agent_data = fetch_raw_resource_details(client, agent, "agents")
+        if not raw_agent_data:
+            return None
 
-    if raw_agent_data:
-        # Use raw API data - this preserves ALL fields including account_id
-        # Format dates for better display (minimal postprocessing)
+        # Format dates for better display
         formatted_data = raw_agent_data.copy()
         if "created_at" in formatted_data:
             formatted_data["created_at"] = format_datetime(formatted_data["created_at"])
         if "updated_at" in formatted_data:
             formatted_data["updated_at"] = format_datetime(formatted_data["updated_at"])
 
-        # Display using output_result with raw data
+        return formatted_data
+    except Exception:
+        return None
+
+
+def _format_fallback_agent_data(client: Any, agent: Any) -> dict:
+    """Format fallback agent data using Pydantic model."""
+    full_agent = _fetch_full_agent_details(client, agent)
+
+    # Define fields to extract
+    fields = [
+        "id",
+        "name",
+        "type",
+        "framework",
+        "version",
+        "description",
+        "instruction",
+        "created_at",
+        "updated_at",
+        "metadata",
+        "language_model_id",
+        "agent_config",
+        "tool_configs",
+        "tools",
+        "agents",
+        "mcps",
+        "a2a_profile",
+    ]
+
+    result_data = build_resource_result_data(full_agent, fields)
+
+    # Handle missing instruction
+    if result_data.get("instruction") in ["N/A", None, ""]:
+        result_data["instruction"] = "-"
+
+    # Format dates for better display
+    for date_field in ["created_at", "updated_at"]:
+        if result_data.get(date_field) and result_data[date_field] not in ["N/A", None]:
+            result_data[date_field] = format_datetime(result_data[date_field])
+
+    return result_data
+
+
+def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
+    """Display full agent details using raw API data to preserve ALL fields."""
+    if agent is None:
+        handle_rich_output(ctx, Text("[red]❌ No agent provided[/red]"))
+        return
+
+    # Try to fetch and format raw agent data first
+    formatted_data = _fetch_and_format_raw_agent_data(client, agent)
+
+    if formatted_data:
+        # Use raw API data - this preserves ALL fields including account_id
+        panel_title = f"🤖 {formatted_data.get('name', 'Unknown')}"
         output_result(
             ctx,
             formatted_data,
             title="Agent Details",
-            panel_title=f"🤖 {raw_agent_data.get('name', 'Unknown')}",
+            panel_title=panel_title,
         )
     else:
-        # Fall back to original method if raw fetch fails
+        # Fall back to Pydantic model data if raw fetch fails
         handle_rich_output(
             ctx, Text("[yellow]Falling back to Pydantic model data[/yellow]")
         )
-        full_agent = _fetch_full_agent_details(client, agent)
-
-        # Build result data using standardized helper
-        fields = [
-            "id",
-            "name",
-            "type",
-            "framework",
-            "version",
-            "description",
-            "instruction",
-            "created_at",
-            "updated_at",
-            "metadata",
-            "language_model_id",
-            "agent_config",
-            "tool_configs",
-            "tools",
-            "agents",
-            "mcps",
-            "a2a_profile",
-        ]
-        result_data = build_resource_result_data(full_agent, fields)
-        if not result_data.get("instruction"):
-            result_data["instruction"] = "-"  # pragma: no cover - cosmetic fallback
 
-        # Format dates for better display
-        if "created_at" in result_data and result_data["created_at"] not in [
-            "N/A",
-            None,
-        ]:
-            result_data["created_at"] = format_datetime(result_data["created_at"])
-        if "updated_at" in result_data and result_data["updated_at"] not in [
-            "N/A",
-            None,
-        ]:
-            result_data["updated_at"] = format_datetime(result_data["updated_at"])
+        result_data = _format_fallback_agent_data(client, agent)
 
         # Display using output_result
         output_result(
             ctx,
             result_data,
             title="Agent Details",
-            panel_title=f"🤖 {full_agent.name}",
+            panel_title=f"🤖 {result_data.get('name', 'Unknown')}",
         )
 
 
 @click.group(name="agents", no_args_is_help=True)
-def agents_group():
+def agents_group() -> None:
     """Agent management operations."""
     pass
 
 
-def _resolve_agent(ctx, client, ref, select=None, interface_preference="fuzzy"):
+def _resolve_agent(
+    ctx: Any,
+    client: Any,
+    ref: str,
+    select: int | None = None,
+    interface_preference: str = "fuzzy",
+) -> Any | None:
     """Resolve agent reference (ID or name) with ambiguity handling.
 
     Args:
@@ -252,7 +277,15 @@ def _resolve_agent(ctx, client, ref, select=None, interface_preference="fuzzy"):
 )
 @output_flags()
 @click.pass_context
-def list_agents(ctx, simple, agent_type, framework, name, version, sync_langflow):
+def list_agents(
+    ctx: Any,
+    simple: bool,
+    agent_type: str | None,
+    framework: str | None,
+    name: str | None,
+    version: str | None,
+    sync_langflow: bool,
+) -> None:
     """List agents with optional filtering."""
     try:
         client = get_client(ctx)
@@ -274,7 +307,7 @@ def list_agents(ctx, simple, agent_type, framework, name, version, sync_langflow
         ]
 
         # Transform function for safe attribute access
-        def transform_agent(agent):
+        def transform_agent(agent: Any) -> dict[str, Any]:
             row = coerce_to_row(agent, ["id", "name", "type", "framework", "version"])
             # Ensure id is always a string
             row["id"] = str(row["id"])
@@ -307,7 +340,7 @@ def list_agents(ctx, simple, agent_type, framework, name, version, sync_langflow
 )
 @output_flags()
 @click.pass_context
-def get(ctx, agent_ref, select, export):
+def get(ctx: Any, agent_ref: str, select: int | None, export: str | None) -> None:
     """Get agent details.
 
     Examples:
@@ -324,18 +357,15 @@ def get(ctx, agent_ref, select, export):
         )
 
         # Handle export option
-        if export:  # pragma: no cover - requires filesystem verification
+        if export:
             export_path = Path(export)
             # Auto-detect format from file extension
-            if export_path.suffix.lower() in [".yaml", ".yml"]:
-                detected_format = "yaml"
-            else:
-                detected_format = "json"
+            detected_format = detect_export_format(export_path)
 
             # Always export comprehensive data - re-fetch agent with full details
             try:
                 agent = client.agents.get_agent_by_id(agent.id)
-            except Exception as e:  # pragma: no cover - best-effort fallback messaging
+            except Exception as e:
                 handle_rich_output(
                     ctx,
                     Text(
@@ -364,7 +394,7 @@ def get(ctx, agent_ref, select, export):
         raise click.ClickException(str(e))
 
 
-def _validate_run_input(input_option, input_text):
+def _validate_run_input(input_option: str | None, input_text: str | None) -> str:
     """Validate and determine the final input text for agent run."""
     final_input_text = input_option if input_option else input_text
 
@@ -376,7 +406,7 @@ def _validate_run_input(input_option, input_text):
     return final_input_text
 
 
-def _parse_chat_history(chat_history):
+def _parse_chat_history(chat_history: str | None) -> list[dict[str, Any]] | None:
     """Parse chat history JSON if provided."""
     if not chat_history:
         return None
@@ -387,9 +417,9 @@ def _parse_chat_history(chat_history):
         raise click.ClickException("Invalid JSON in chat history")
 
 
-def _setup_run_renderer(ctx, save, verbose):
+def _setup_run_renderer(ctx: Any, save: str | None, verbose: bool) -> Any:
     """Set up renderer and working console for agent run."""
-    tty_enabled = bool((ctx.obj or {}).get("tty", True))
+    tty_enabled = bool(get_ctx_value(ctx, "tty", True))
     return build_renderer(
         ctx,
         save_path=save,
@@ -399,8 +429,13 @@ def _setup_run_renderer(ctx, save, verbose):
 
 
 def _prepare_run_kwargs(
-    agent, final_input_text, files, parsed_chat_history, renderer, tty_enabled
-):
+    agent: Any,
+    final_input_text: str,
+    files: list[str] | None,
+    parsed_chat_history: list[dict[str, Any]] | None,
+    renderer: Any,
+    tty_enabled: bool,
+) -> dict[str, Any]:
     """Prepare kwargs for agent run."""
     run_kwargs = {
         "agent_id": agent.id,
@@ -419,10 +454,10 @@ def _prepare_run_kwargs(
     return run_kwargs
 
 
-def _handle_run_output(ctx, result, renderer):
+def _handle_run_output(ctx: Any, result: Any, renderer: Any) -> None:
     """Handle output formatting for agent run results."""
     printed_by_renderer = bool(renderer)
-    selected_view = (ctx.obj or {}).get("view", "rich")
+    selected_view = get_ctx_value(ctx, "view", "rich")
 
     if not printed_by_renderer:
         if selected_view == "json":
@@ -433,7 +468,7 @@ def _handle_run_output(ctx, result, renderer):
             click.echo(result)
 
 
-def _save_run_transcript(save, result, working_console):
+def _save_run_transcript(save: str | None, result: Any, working_console: Any) -> None:
     """Save transcript to file if requested."""
     if not save:
         return
@@ -492,17 +527,17 @@ def _save_run_transcript(save, result, working_console):
 @output_flags()
 @click.pass_context
 def run(
-    ctx,
-    agent_ref,
-    select,
-    input_text,
-    input_option,
-    chat_history,
-    timeout,
-    save,
-    files,
-    verbose,
-):
+    ctx: Any,
+    agent_ref: str,
+    select: int | None,
+    input_text: str | None,
+    input_option: str | None,
+    chat_history: str | None,
+    timeout: float | None,
+    save: str | None,
+    files: tuple[str, ...] | None,
+    verbose: bool,
+) -> None:
     """Run an agent with input text.
 
     Usage: aip agents run <agent_ref> <input_text> [OPTIONS]
@@ -534,7 +569,7 @@ def run(
             files,
             parsed_chat_history,
             renderer,
-            bool((ctx.obj or {}).get("tty", True)),
+            bool(get_ctx_value(ctx, "tty", True)),
         )
 
         result = client.agents.run_agent(**run_kwargs, timeout=timeout)
@@ -547,8 +582,235 @@ def run(
         handle_json_output(ctx, error=Exception(error_msg))
         raise click.ClickException(error_msg)
     except Exception as e:
-        handle_json_output(ctx, error=e)
-        raise click.ClickException(str(e))
+        _handle_command_exception(ctx, e)
+
+
+def _handle_import_file_logic(
+    import_file: str,
+    model: str | None,
+    name: str,
+    instruction: str,
+    tools: tuple[str, ...],
+    agents: tuple[str, ...],
+    mcps: tuple[str, ...],
+    timeout: float | None,
+) -> dict[str, Any]:
+    """Handle import file logic and merge with CLI args."""
+    import_data = load_resource_from_file(Path(import_file), "agent")
+    import_data = convert_export_to_import_format(import_data)
+    import_data = normalize_agent_config_for_import(import_data, model)
+
+    cli_args = {
+        "name": name,
+        "instruction": instruction,
+        "model": model,
+        "tools": tools or (),
+        "agents": agents or (),
+        "mcps": mcps or (),
+        "timeout": timeout if timeout != DEFAULT_AGENT_RUN_TIMEOUT else None,
+    }
+
+    return merge_import_with_cli_args(import_data, cli_args)
+
+
+def _build_cli_args_data(
+    name: str,
+    instruction: str,
+    model: str | None,
+    tools: tuple[str, ...],
+    agents: tuple[str, ...],
+    mcps: tuple[str, ...],
+    timeout: float | None,
+) -> dict[str, Any]:
+    """Build merged data from CLI arguments."""
+    return {
+        "name": name,
+        "instruction": instruction,
+        "model": model,
+        "tools": tools or (),
+        "agents": agents or (),
+        "mcps": mcps or (),
+        "timeout": timeout if timeout != DEFAULT_AGENT_RUN_TIMEOUT else None,
+    }
+
+
+def _extract_and_validate_fields(
+    merged_data: dict[str, Any],
+) -> tuple[str, str, str | None, tuple, tuple, tuple, Any]:
+    """Extract and validate required fields from merged data."""
+    name = merged_data.get("name")
+    instruction = merged_data.get("instruction")
+    model = merged_data.get("model")
+    tools = tuple(merged_data.get("tools", ()))
+    agents = tuple(merged_data.get("agents", ()))
+    mcps = tuple(merged_data.get("mcps", ()))
+    timeout = merged_data.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
+
+    # Validate required fields
+    if not name:
+        raise click.ClickException("Agent name is required (--name or --import)")
+    if not instruction:
+        raise click.ClickException(
+            "Agent instruction is required (--instruction or --import)"
+        )
+
+    return name, instruction, model, tools, agents, mcps, timeout
+
+
+def _validate_and_coerce_fields(
+    name: str, instruction: str, timeout: Any
+) -> tuple[str, str, Any]:
+    """Validate and coerce field values."""
+    name = validate_agent_name(name)
+    instruction = validate_agent_instruction(instruction)
+    timeout = coerce_timeout(timeout)
+    if timeout is not None:
+        timeout = validate_timeout(timeout)
+
+    return name, instruction, timeout
+
+
+def _resolve_resources(
+    client: Any, tools: tuple, agents: tuple, mcps: tuple
+) -> tuple[list, list, list]:
+    """Resolve tool, agent, and MCP references."""
+    resolved_tools = _resolve_resources_by_name(
+        client, tools, "tool", client.find_tools, "Tool"
+    )
+    resolved_agents = _resolve_resources_by_name(
+        client, agents, "agent", client.find_agents, "Agent"
+    )
+    resolved_mcps = _resolve_resources_by_name(
+        client, mcps, "mcp", client.find_mcps, "MCP"
+    )
+
+    return resolved_tools, resolved_agents, resolved_mcps
+
+
+def _build_create_kwargs(
+    name: str,
+    instruction: str,
+    resolved_tools: list,
+    resolved_agents: list,
+    resolved_mcps: list,
+    timeout: Any,
+    merged_data: dict[str, Any],
+    model: str | None,
+    import_file: str | None,
+) -> dict[str, Any]:
+    """Build create_agent kwargs with all necessary parameters."""
+    create_kwargs = {
+        "name": name,
+        "instruction": instruction,
+        "tools": resolved_tools or None,
+        "agents": resolved_agents or None,
+        "mcps": resolved_mcps or None,
+        "timeout": timeout,
+    }
+
+    # Handle language model selection
+    lm_selection_dict, should_strip_lm_identity = resolve_language_model_selection(
+        merged_data, model
+    )
+    create_kwargs.update(lm_selection_dict)
+
+    # Handle import file specific logic
+    if import_file:
+        _add_import_file_attributes(
+            create_kwargs, merged_data, should_strip_lm_identity
+        )
+
+    return create_kwargs
+
+
+def _add_import_file_attributes(
+    create_kwargs: dict[str, Any],
+    merged_data: dict[str, Any],
+    should_strip_lm_identity: bool,
+) -> None:
+    """Add import file specific attributes to create_kwargs."""
+    agent_config_raw = merged_data.get("agent_config")
+    if isinstance(agent_config_raw, dict):
+        create_kwargs["agent_config"] = sanitize_agent_config(
+            agent_config_raw, strip_lm_identity=should_strip_lm_identity
+        )
+
+    # Add other attributes from import data
+    excluded_fields = {
+        "name",
+        "instruction",
+        "model",
+        "language_model_id",
+        "tools",
+        "agents",
+        "timeout",
+        "agent_config",
+        "id",
+        "created_at",
+        "updated_at",
+        "type",
+        "framework",
+        "version",
+        "tool_configs",
+        "mcps",
+        "a2a_profile",
+    }
+    for key, value in merged_data.items():
+        if key not in excluded_fields and value is not None:
+            create_kwargs[key] = value
+
+
+def _get_language_model_display_name(agent: Any, model: str | None) -> str:
+    """Get display name for the language model."""
+    lm_display = getattr(agent, "model", None)
+    if not lm_display:
+        cfg = getattr(agent, "agent_config", {}) or {}
+        lm_display = (
+            cfg.get("lm_name")
+            or cfg.get("model")
+            or model
+            or f"{DEFAULT_MODEL} (backend default)"
+        )
+    return lm_display
+
+
+def _handle_successful_creation(ctx: Any, agent: Any, model: str | None) -> None:
+    """Handle successful agent creation output."""
+    handle_json_output(ctx, agent.model_dump())
+
+    lm_display = _get_language_model_display_name(agent, model)
+
+    handle_rich_output(
+        ctx,
+        display_creation_success(
+            "Agent",
+            agent.name,
+            agent.id,
+            Model=lm_display,
+            Type=getattr(agent, "type", "config"),
+            Framework=getattr(agent, "framework", "langchain"),
+            Version=getattr(agent, "version", "1.0"),
+        ),
+    )
+    handle_rich_output(ctx, display_agent_run_suggestions(agent))
+
+
+def _handle_command_exception(ctx: Any, e: Exception) -> None:
+    """Handle exceptions during command execution with consistent error handling."""
+    if isinstance(e, click.ClickException):
+        if get_ctx_value(ctx, "view") == "json":
+            handle_json_output(ctx, error=Exception(AGENT_NOT_FOUND_ERROR))
+        raise
+
+    handle_json_output(ctx, error=e)
+    if get_ctx_value(ctx, "view") != "json":
+        print_api_error(e)
+    raise click.ClickException(str(e))
+
+
+def _handle_creation_exception(ctx: Any, e: Exception) -> None:
+    """Handle exceptions during agent creation."""
+    _handle_command_exception(ctx, e)
 
 
 @agents_group.command()
@@ -576,16 +838,16 @@ def run(
 @output_flags()
 @click.pass_context
 def create(
-    ctx,
-    name,
-    instruction,
-    model,
-    tools,
-    agents,
-    mcps,
-    timeout,
-    import_file,
-):
+    ctx: Any,
+    name: str,
+    instruction: str,
+    model: str | None,
+    tools: tuple[str, ...] | None,
+    agents: tuple[str, ...] | None,
+    mcps: tuple[str, ...] | None,
+    timeout: float | None,
+    import_file: str | None,
+) -> None:
     """Create a new agent.
 
     Examples:
@@ -595,181 +857,59 @@ def create(
     try:
         client = get_client(ctx)
 
-        # Initialize merged_data for cases without import_file
-        merged_data = {}
-
-        # Handle import from file
-        if (
-            import_file
-        ):  # pragma: no cover - exercised in higher-level integration tests
-            import_data = load_resource_from_file(Path(import_file), "agent")
-
-            # Convert export format to import-compatible format
-            import_data = convert_export_to_import_format(import_data)
-
-            # Auto-normalize agent config (extract LM settings from agent_config)
-            import_data = normalize_agent_config_for_import(import_data, model)
-
-            # Merge CLI args with imported data
-            cli_args = {
-                "name": name,
-                "instruction": instruction,
-                "model": model,
-                "tools": tools or (),
-                "agents": agents or (),
-                "mcps": mcps or (),
-                "timeout": timeout if timeout != DEFAULT_AGENT_RUN_TIMEOUT else None,
-            }
-
-            merged_data = merge_import_with_cli_args(import_data, cli_args)
+        # Handle import file or CLI args
+        if import_file:
+            merged_data = _handle_import_file_logic(
+                import_file, model, name, instruction, tools, agents, mcps, timeout
+            )
         else:
-            # No import file - use CLI args directly
-            merged_data = {
-                "name": name,
-                "instruction": instruction,
-                "model": model,
-                "tools": tools or (),
-                "agents": agents or (),
-                "mcps": mcps or (),
-                "timeout": timeout if timeout != DEFAULT_AGENT_RUN_TIMEOUT else None,
-            }
-
-        # Extract merged values
-        name = merged_data.get("name")
-        instruction = merged_data.get("instruction")
-        model = merged_data.get("model")
-        tools = tuple(merged_data.get("tools", ()))
-        agents = tuple(merged_data.get("agents", ()))
-        mcps = tuple(merged_data.get("mcps", ()))
-        timeout = merged_data.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
-        # Coerce timeout to proper integer type
-        timeout = coerce_timeout(timeout)
-
-        # Validate required fields using centralized validators
-        if not name:
-            raise click.ClickException("Agent name is required (--name or --import)")
-        if not instruction:
-            raise click.ClickException(
-                "Agent instruction is required (--instruction or --import)"
+            merged_data = _build_cli_args_data(
+                name, instruction, model, tools, agents, mcps, timeout
             )
 
-        # Apply validation
-        name = validate_agent_name(name)
-        instruction = validate_agent_instruction(instruction)
-        if timeout is not None:
-            timeout = validate_timeout(timeout)
-
-        # Resolve tool and agent references: accept names or IDs
-        resolved_tools = _resolve_resources_by_name(
-            client, tools, "tool", client.find_tools, "Tool"
-        )
-        resolved_agents = _resolve_resources_by_name(
-            client, agents, "agent", client.find_agents, "Agent"
-        )
-        resolved_mcps = _resolve_resources_by_name(
-            client, mcps, "mcp", client.find_mcps, "MCP"
+        # Extract and validate fields
+        (
+            name,
+            instruction,
+            model,
+            tools,
+            agents,
+            mcps,
+            timeout,
+        ) = _extract_and_validate_fields(merged_data)
+        name, instruction, timeout = _validate_and_coerce_fields(
+            name, instruction, timeout
         )
 
-        # Create agent with comprehensive attribute support
-        create_kwargs = {
-            "name": name,
-            "instruction": instruction,
-            "tools": resolved_tools or None,
-            "agents": resolved_agents or None,
-            "mcps": resolved_mcps or None,
-            "timeout": timeout,
-        }
-
-        # Handle language model selection using helper function
-        lm_selection_dict, should_strip_lm_identity = resolve_language_model_selection(
-            merged_data, model
+        # Resolve resources
+        resolved_tools, resolved_agents, resolved_mcps = _resolve_resources(
+            client, tools, agents, mcps
         )
-        create_kwargs.update(lm_selection_dict)
-
-        # If importing from file, include agent_config (pass-through minus credentials)
-        if import_file:
-            agent_config_raw = (
-                merged_data.get("agent_config")
-                if isinstance(merged_data, dict)
-                else None
-            )
-            if isinstance(agent_config_raw, dict):
-                # If language_model_id is used, strip LM identity keys from agent_config to avoid conflicts
-                create_kwargs["agent_config"] = sanitize_agent_config(
-                    agent_config_raw, strip_lm_identity=should_strip_lm_identity
-                )
 
-        # If importing from file, include all other detected attributes
-        if import_file:
-            # Add all other attributes from import data (excluding already handled ones and system-only fields)
-            excluded_fields = {
-                "name",
-                "instruction",
-                "model",
-                "language_model_id",
-                "tools",
-                "agents",
-                "timeout",
-                "agent_config",  # handled explicitly above
-                # System-only fields that shouldn't be passed to create_agent
-                "id",
-                "created_at",
-                "updated_at",
-                "type",
-                "framework",
-                "version",
-                "tool_configs",
-                "mcps",
-                "a2a_profile",
-            }
-            for key, value in merged_data.items():
-                if key not in excluded_fields and value is not None:
-                    create_kwargs[key] = value
+        # Build create kwargs
+        create_kwargs = _build_create_kwargs(
+            name,
+            instruction,
+            resolved_tools,
+            resolved_agents,
+            resolved_mcps,
+            timeout,
+            merged_data,
+            model,
+            import_file,
+        )
 
+        # Create agent
         agent = client.agents.create_agent(**create_kwargs)
 
-        handle_json_output(ctx, agent.model_dump())
-
-        lm_display = getattr(agent, "model", None)
-        if not lm_display:
-            cfg = getattr(agent, "agent_config", {}) or {}
-            lm_display = (
-                cfg.get("lm_name")
-                or cfg.get("model")
-                or model
-                or f"{DEFAULT_MODEL} (backend default)"
-            )
-
-        handle_rich_output(
-            ctx,
-            display_creation_success(
-                "Agent",
-                agent.name,
-                agent.id,
-                Model=lm_display,
-                Type=getattr(agent, "type", "config"),
-                Framework=getattr(agent, "framework", "langchain"),
-                Version=getattr(agent, "version", "1.0"),
-            ),
-        )
-        handle_rich_output(ctx, display_agent_run_suggestions(agent))
+        # Handle successful creation
+        _handle_successful_creation(ctx, agent, model)
 
-    except (
-        click.ClickException
-    ):  # pragma: no cover - error formatting verified elsewhere
-        # Handle JSON output for ClickExceptions if view is JSON
-        if ctx.obj.get("view") == "json":
-            handle_json_output(ctx, error=Exception(AGENT_NOT_FOUND_ERROR))
-        # Re-raise ClickExceptions without additional processing
-        raise
-    except Exception as e:  # pragma: no cover - defensive logging path
-        handle_json_output(ctx, error=e)
-        if ctx.obj.get("view") != "json":
-            print_api_error(e)
-        raise click.ClickException(str(e))
+    except Exception as e:
+        _handle_creation_exception(ctx, e)
 
 
-def _get_agent_for_update(client, agent_id):
+def _get_agent_for_update(client: Any, agent_id: str) -> Any:
     """Retrieve agent by ID for update operation."""
     try:
         return client.agents.get_agent_by_id(agent_id)
@@ -777,7 +917,21 @@ def _get_agent_for_update(client, agent_id):
         raise click.ClickException(f"Agent with ID '{agent_id}' not found: {e}")
 
 
-def _handle_update_import_file(import_file, name, instruction, tools, agents, timeout):
+def _handle_update_import_file(
+    import_file: str | None,
+    name: str | None,
+    instruction: str | None,
+    tools: tuple[str, ...] | None,
+    agents: tuple[str, ...] | None,
+    timeout: float | None,
+) -> tuple[
+    Any | None,
+    str | None,
+    str | None,
+    tuple[str, ...] | None,
+    tuple[str, ...] | None,
+    float | None,
+]:
     """Handle import file processing for agent update."""
     if not import_file:
         return None, name, instruction, tools, agents, timeout
@@ -806,7 +960,13 @@ def _handle_update_import_file(import_file, name, instruction, tools, agents, ti
     )
 
 
-def _build_update_data(name, instruction, tools, agents, timeout):
+def _build_update_data(
+    name: str | None,
+    instruction: str | None,
+    tools: tuple[str, ...] | None,
+    agents: tuple[str, ...] | None,
+    timeout: float | None,
+) -> dict[str, Any]:
     """Build the update data dictionary from provided parameters."""
     update_data = {}
     if name is not None:
@@ -822,7 +982,9 @@ def _build_update_data(name, instruction, tools, agents, timeout):
     return update_data
 
 
-def _handle_update_import_config(import_file, merged_data, update_data):
+def _handle_update_import_config(
+    import_file: str | None, merged_data: dict[str, Any], update_data: dict[str, Any]
+) -> None:
     """Handle agent config and additional attributes for import-based updates."""
     if not import_file:
         return
@@ -876,7 +1038,16 @@ def _handle_update_import_config(import_file, merged_data, update_data):
 )
 @output_flags()
 @click.pass_context
-def update(ctx, agent_id, name, instruction, tools, agents, timeout, import_file):
+def update(
+    ctx: Any,
+    agent_id: str,
+    name: str | None,
+    instruction: str | None,
+    tools: tuple[str, ...] | None,
+    agents: tuple[str, ...] | None,
+    timeout: float | None,
+    import_file: str | None,
+) -> None:
     """Update an existing agent.
 
     Examples:
@@ -888,10 +1059,15 @@ def update(ctx, agent_id, name, instruction, tools, agents, timeout, import_file
         agent = _get_agent_for_update(client, agent_id)
 
         # Handle import file processing
-        merged_data, name, instruction, tools, agents, timeout = (
-            _handle_update_import_file(
-                import_file, name, instruction, tools, agents, timeout
-            )
+        (
+            merged_data,
+            name,
+            instruction,
+            tools,
+            agents,
+            timeout,
+        ) = _handle_update_import_file(
+            import_file, name, instruction, tools, agents, timeout
         )
 
         update_data = _build_update_data(name, instruction, tools, agents, timeout)
@@ -910,15 +1086,12 @@ def update(ctx, agent_id, name, instruction, tools, agents, timeout, import_file
 
     except click.ClickException:
         # Handle JSON output for ClickExceptions if view is JSON
-        if ctx.obj.get("view") == "json":
+        if get_ctx_value(ctx, "view") == "json":
             handle_json_output(ctx, error=Exception(AGENT_NOT_FOUND_ERROR))
         # Re-raise ClickExceptions without additional processing
         raise
     except Exception as e:
-        handle_json_output(ctx, error=e)
-        if ctx.obj.get("view") != "json":
-            print_api_error(e)
-        raise click.ClickException(str(e))
+        _handle_command_exception(ctx, e)
 
 
 @agents_group.command()
@@ -926,7 +1099,7 @@ def update(ctx, agent_id, name, instruction, tools, agents, timeout, import_file
 @click.option("-y", "--yes", is_flag=True, help="Skip confirmation")
 @output_flags()
 @click.pass_context
-def delete(ctx, agent_id, yes):
+def delete(ctx: Any, agent_id: str, yes: bool) -> None:
     """Delete an agent."""
     try:
         client = get_client(ctx)
@@ -954,15 +1127,12 @@ def delete(ctx, agent_id, yes):
 
     except click.ClickException:
         # Handle JSON output for ClickExceptions if view is JSON
-        if ctx.obj.get("view") == "json":
+        if get_ctx_value(ctx, "view") == "json":
             handle_json_output(ctx, error=Exception(AGENT_NOT_FOUND_ERROR))
         # Re-raise ClickExceptions without additional processing
         raise
     except Exception as e:
-        handle_json_output(ctx, error=e)
-        if ctx.obj.get("view") != "json":
-            print_api_error(e)
-        raise click.ClickException(str(e))
+        _handle_command_exception(ctx, e)
 
 
 @agents_group.command()
@@ -975,7 +1145,7 @@ def delete(ctx, agent_id, yes):
 )
 @output_flags()
 @click.pass_context
-def sync_langflow(ctx, base_url, api_key):  # pragma: no cover - integration-only path
+def sync_langflow(ctx: Any, base_url: str | None, api_key: str | None) -> None:
     """Sync agents with LangFlow server flows.
 
     This command fetches all flows from the configured LangFlow server and
@@ -999,7 +1169,7 @@ def sync_langflow(ctx, base_url, api_key):  # pragma: no cover - integration-onl
         handle_json_output(ctx, result)
 
         # Show success message for non-JSON output
-        if ctx.obj.get("view") != "json":
+        if get_ctx_value(ctx, "view") != "json":
             from rich.text import Text
 
             # Extract some useful info from the result
@@ -1016,7 +1186,4 @@ def sync_langflow(ctx, base_url, api_key):  # pragma: no cover - integration-onl
             )
 
     except Exception as e:
-        handle_json_output(ctx, error=e)
-        if ctx.obj.get("view") != "json":
-            print_api_error(e)
-        raise click.ClickException(str(e))
+        _handle_command_exception(ctx, e)