glaip-sdk 0.0.20__py3-none-any.whl → 0.6.5b6__py3-none-any.whl

glaip_sdk/cli/commands/agents.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import json
 import os
 from collections.abc import Mapping
+from copy import deepcopy
 from pathlib import Path
 from typing import Any
 
@@ -18,6 +19,7 @@ from rich.console import Console
 from glaip_sdk.branding import (
     ACCENT_STYLE,
     ERROR_STYLE,
+    HINT_PREFIX_STYLE,
     INFO,
     SUCCESS,
     SUCCESS_STYLE,
@@ -32,7 +34,8 @@ from glaip_sdk.cli.agent_config import (
 from glaip_sdk.cli.agent_config import (
     sanitize_agent_config_for_cli as sanitize_agent_config,
 )
-from glaip_sdk.cli.context import detect_export_format, get_ctx_value, output_flags
+from glaip_sdk.cli.constants import DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
+from glaip_sdk.cli.context import get_ctx_value, output_flags
 from glaip_sdk.cli.display import (
     build_resource_result_data,
     display_agent_run_suggestions,
@@ -44,9 +47,7 @@ from glaip_sdk.cli.display import (
     handle_rich_output,
     print_api_error,
 )
-from glaip_sdk.cli.io import (
-    export_resource_to_file_with_validation as export_resource_to_file,
-)
+from glaip_sdk.cli.hints import in_slash_mode
 from glaip_sdk.cli.io import (
     fetch_raw_resource_details,
 )
@@ -64,9 +65,11 @@ from glaip_sdk.cli.utils import (
     build_renderer,
     coerce_to_row,
     get_client,
+    handle_resource_export,
     output_list,
     output_result,
     spinner_context,
+    with_client_and_spinner,
 )
 from glaip_sdk.cli.validators import (
     validate_agent_instruction_cli as validate_agent_instruction,
@@ -77,12 +80,13 @@ from glaip_sdk.cli.validators import (
 from glaip_sdk.cli.validators import (
     validate_timeout_cli as validate_timeout,
 )
-from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT, DEFAULT_MODEL
+from glaip_sdk.config.constants import AGENT_CONFIG_FIELDS, DEFAULT_AGENT_RUN_TIMEOUT, DEFAULT_MODEL
 from glaip_sdk.exceptions import AgentTimeoutError
 from glaip_sdk.icons import ICON_AGENT
 from glaip_sdk.utils import format_datetime, is_uuid
 from glaip_sdk.utils.agent_config import normalize_agent_config_for_import
 from glaip_sdk.utils.import_export import convert_export_to_import_format
+from glaip_sdk.utils.rendering.renderer.toggle import TranscriptToggleController
 from glaip_sdk.utils.validation import coerce_timeout
 
 console = Console()
@@ -90,6 +94,8 @@ console = Console()
 # Error message constants
 AGENT_NOT_FOUND_ERROR = "Agent not found"
 
+# Instruction preview controls
+
 
 def _safe_agent_attribute(agent: Any, name: str) -> Any:
     """Return attribute value for ``name`` while filtering Mock sentinels."""
@@ -142,10 +148,7 @@ def _build_fallback_agent_mapping(agent: Any) -> dict[str, Any]:
         "description",
         "model",
         "agent_config",
-        "tools",
-        "agents",
-        "mcps",
-        "timeout",
+        *[field for field in AGENT_CONFIG_FIELDS if field not in ("name", "instruction", "model")],
         "tool_configs",
     )
 
@@ -246,9 +249,7 @@ def _resolve_resources_by_name(
         if not matches:
             raise click.ClickException(f"{label} not found: {ref}")
         if len(matches) > 1:
-            raise click.ClickException(
-                f"Multiple {resource_type}s named '{ref}'. Use ID instead."
-            )
+            raise click.ClickException(f"Multiple {resource_type}s named '{ref}'. Use ID instead.")
         out.append(str(matches[0].id))
     return out
 
@@ -311,12 +312,92 @@ def _format_fallback_agent_data(client: Any, agent: Any) -> dict:
     return result_data
 
 
-def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
+def _clamp_instruction_preview_limit(limit: int | None) -> int:
+    """Normalise preview limit; 0 disables trimming."""
+    default = DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
+    if limit is None:  # pragma: no cover
+        return default
+    try:
+        limit_value = int(limit)
+    except (TypeError, ValueError):  # pragma: no cover - defensive parsing
+        return default
+
+    if limit_value <= 0:
+        return 0
+
+    return limit_value
+
+
+def _build_instruction_preview(value: Any, limit: int) -> tuple[Any, bool]:
+    """Return a trimmed preview for long instruction strings."""
+    if not isinstance(value, str) or limit <= 0:  # pragma: no cover
+        return value, False
+
+    if len(value) <= limit:
+        return value, False
+
+    trimmed_value = value[:limit].rstrip()
+    preview = f"{trimmed_value}\n\n... (preview trimmed)"
+    return preview, True
+
+
+def _prepare_agent_details_payload(
+    data: dict[str, Any],
+    *,
+    instruction_preview_limit: int,
+) -> tuple[dict[str, Any], bool]:
+    """Return payload ready for rendering plus trim indicator."""
+    payload = deepcopy(data)
+    trimmed = False
+    if instruction_preview_limit > 0:
+        preview, trimmed = _build_instruction_preview(payload.get("instruction"), instruction_preview_limit)
+        if trimmed:
+            payload["instruction"] = preview
+    return payload, trimmed
+
+
+def _show_instruction_trim_hint(
+    ctx: Any,
+    *,
+    trimmed: bool,
+    preview_limit: int,
+) -> None:
+    """Render hint describing how to expand or collapse the instruction preview."""
+    if not trimmed or preview_limit <= 0:
+        return
+
+    view = get_ctx_value(ctx, "view", "rich") if ctx is not None else "rich"
+    if view != "rich":  # pragma: no cover - non-rich view handling
+        return
+
+    suffix = f"[dim](preview: {preview_limit:,} chars)[/]"
+    if in_slash_mode(ctx):
+        console.print(
+            f"[{HINT_PREFIX_STYLE}]Tip:[/] Use '/details' again to toggle between trimmed and full prompts {suffix}"
+        )
+        return
+
+    console.print(  # pragma: no cover - fallback hint rendering
+        f"[{HINT_PREFIX_STYLE}]Tip:[/] Run 'aip agents get <agent> --instruction-preview <n>' "
+        f"to control prompt preview length {suffix}"
+    )
+
+
+def _display_agent_details(
+    ctx: Any,
+    client: Any,
+    agent: Any,
+    *,
+    instruction_preview_limit: int | None = None,
+) -> None:
     """Display full agent details using raw API data to preserve ALL fields."""
     if agent is None:
         handle_rich_output(ctx, markup_text(f"[{ERROR_STYLE}]❌ No agent provided[/]"))
         return
 
+    preview_limit = _clamp_instruction_preview_limit(instruction_preview_limit)
+    trimmed_instruction = False
+
     # Try to fetch and format raw agent data first
     with spinner_context(
         ctx,
@@ -328,9 +409,13 @@ def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
     if formatted_data:
         # Use raw API data - this preserves ALL fields including account_id
         panel_title = f"{ICON_AGENT} {formatted_data.get('name', 'Unknown')}"
+        payload, trimmed_instruction = _prepare_agent_details_payload(
+            formatted_data,
+            instruction_preview_limit=preview_limit,
+        )
         output_result(
             ctx,
-            formatted_data,
+            payload,
             title=panel_title,
         )
     else:
@@ -348,12 +433,22 @@ def _display_agent_details(ctx: Any, client: Any, agent: Any) -> None:
             result_data = _format_fallback_agent_data(client, agent)
 
         # Display using output_result
+        payload, trimmed_instruction = _prepare_agent_details_payload(
+            result_data,
+            instruction_preview_limit=preview_limit,
+        )
         output_result(
             ctx,
-            result_data,
+            payload,
             title="Agent Details",
         )
 
+    _show_instruction_trim_hint(
+        ctx,
+        trimmed=trimmed_instruction,
+        preview_limit=preview_limit,
+    )
+
 
 @click.group(name="agents", no_args_is_help=True)
 def agents_group() -> None:
@@ -368,41 +463,47 @@ def _resolve_agent(
     select: int | None = None,
     interface_preference: str = "fuzzy",
 ) -> Any | None:
-    """Resolve agent reference (ID or name) with ambiguity handling.
+    """Resolve an agent by ID or name, supporting fuzzy and questionary interfaces.
+
+    This function provides agent-specific resolution with flexible UI options.
+    It wraps resolve_resource_reference with agent-specific configuration, allowing
+    users to choose between fuzzy search and traditional questionary selection.
 
     Args:
-        ctx: Click context object for CLI operations.
-        client: AIP client instance for API operations.
-        ref: Agent reference (ID or name) to resolve.
-        select: Pre-selected agent index for non-interactive mode.
-        interface_preference: "fuzzy" for fuzzy picker, "questionary" for up/down list.
+        ctx: Click context for CLI command execution.
+        client: AIP SDK client instance.
+        ref: Agent identifier (UUID or name string).
+        select: Pre-selected index for non-interactive resolution (1-based).
+        interface_preference: UI preference - "fuzzy" for search or "questionary" for list.
 
     Returns:
-        Resolved agent object or None if not found.
+        Agent object when found, None when resolution fails.
     """
+    # Configure agent-specific resolution parameters
+    resolution_config = {
+        "resource_type": "agent",
+        "get_by_id": client.agents.get_agent_by_id,
+        "find_by_name": client.agents.find_agents,
+        "label": "Agent",
+    }
+    # Use agent-specific resolution with flexible interface preference
     return resolve_resource_reference(
         ctx,
         client,
         ref,
-        "agent",
-        client.agents.get_agent_by_id,
-        client.agents.find_agents,
-        "Agent",
+        resolution_config["resource_type"],
+        resolution_config["get_by_id"],
+        resolution_config["find_by_name"],
+        resolution_config["label"],
         select=select,
         interface_preference=interface_preference,
     )
 
 
 @agents_group.command(name="list")
-@click.option(
-    "--simple", is_flag=True, help="Show simple table without interactive picker"
-)
-@click.option(
-    "--type", "agent_type", help="Filter by agent type (config, code, a2a, langflow)"
-)
-@click.option(
-    "--framework", help="Filter by framework (langchain, langgraph, google_adk)"
-)
+@click.option("--simple", is_flag=True, help="Show simple table without interactive picker")
+@click.option("--type", "agent_type", help="Filter by agent type (config, code, a2a, langflow)")
+@click.option("--framework", help="Filter by framework (langchain, langgraph, google_adk)")
 @click.option("--name", help="Filter by partial name match (case-insensitive)")
 @click.option("--version", help="Filter by exact version match")
 @click.option(
@@ -423,19 +524,20 @@ def list_agents(
 ) -> None:
     """List agents with optional filtering."""
     try:
-        client = get_client(ctx)
-        with spinner_context(
+        with with_client_and_spinner(
             ctx,
             "[bold blue]Fetching agents…[/bold blue]",
             console_override=console,
-        ):
-            agents = client.agents.list_agents(
-                agent_type=agent_type,
-                framework=framework,
-                name=name,
-                version=version,
-                sync_langflow_agents=sync_langflow,
-            )
+        ) as client:
+            # Query agents with specified filters
+            filter_params = {
+                "agent_type": agent_type,
+                "framework": framework,
+                "name": name,
+                "version": version,
+                "sync_langflow_agents": sync_langflow,
+            }
+            agents = client.agents.list_agents(**filter_params)
 
         # Define table columns: (data_key, header, style, width)
         columns = [
@@ -448,6 +550,14 @@ def list_agents(
 
         # Transform function for safe attribute access
         def transform_agent(agent: Any) -> dict[str, Any]:
+            """Transform an agent object to a display row dictionary.
+
+            Args:
+                agent: Agent object to transform.
+
+            Returns:
+                Dictionary with id, name, type, framework, and version fields.
+            """
             row = coerce_to_row(agent, ["id", "name", "type", "framework", "version"])
             # Ensure id is always a string
             row["id"] = str(row["id"])
@@ -466,7 +576,10 @@ def list_agents(
             and len(agents) > 0
         )
 
+        # Track picker attempt so the fallback table doesn't re-open the palette
+        picker_attempted = False
         if interactive_enabled:
+            picker_attempted = True
             picked_agent = _fuzzy_pick_for_resources(agents, "agent", "")
             if picked_agent:
                 _display_agent_details(ctx, client, picked_agent)
@@ -481,15 +594,17 @@ def list_agents(
             f"{ICON_AGENT} Available Agents",
             columns,
             transform_agent,
-            skip_picker=simple
-            or any(
-                param is not None for param in (agent_type, framework, name, version)
+            skip_picker=(
+                not interactive_enabled
+                or picker_attempted
+                or simple
+                or any(param is not None for param in (agent_type, framework, name, version))
             ),
             use_pager=False,
         )
 
     except Exception as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 @agents_group.command()
@@ -500,68 +615,66 @@ def list_agents(
     type=click.Path(dir_okay=False, writable=True),
     help="Export complete agent configuration to file (format auto-detected from .json/.yaml extension)",
 )
+@click.option(
+    "--instruction-preview",
+    type=int,
+    default=0,
+    show_default=True,
+    help="Instruction preview length when printing instructions (0 shows full prompt).",
+)
 @output_flags()
 @click.pass_context
-def get(ctx: Any, agent_ref: str, select: int | None, export: str | None) -> None:
-    """Get agent details.
+def get(
+    ctx: Any,
+    agent_ref: str,
+    select: int | None,
+    export: str | None,
+    instruction_preview: int,
+) -> None:
+    r"""Get agent details.
 
+    \b
     Examples:
         aip agents get my-agent
         aip agents get my-agent --export agent.json    # Exports complete configuration as JSON
         aip agents get my-agent --export agent.yaml    # Exports complete configuration as YAML
     """
     try:
-        client = get_client(ctx)
+        # Initialize API client for agent retrieval
+        api_client = get_client(ctx)
 
-        # Resolve agent with ambiguity handling - use questionary interface for traditional UX
-        agent = _resolve_agent(
-            ctx, client, agent_ref, select, interface_preference="questionary"
-        )
+        # Resolve agent reference using questionary interface for better UX
+        agent = _resolve_agent(ctx, api_client, agent_ref, select, interface_preference="questionary")
 
-        # Handle export option
+        if not agent:
+            raise click.ClickException(f"Agent '{agent_ref}' not found")
+
+        # Handle export option if requested
         if export:
-            export_path = Path(export)
-            # Auto-detect format from file extension
-            detected_format = detect_export_format(export_path)
-
-            # Always export comprehensive data - re-fetch agent with full details
-            try:
-                with spinner_context(
-                    ctx,
-                    "[bold blue]Fetching complete agent data…[/bold blue]",
-                    console_override=console,
-                ):
-                    agent = client.agents.get_agent_by_id(agent.id)
-            except Exception as e:
-                handle_rich_output(
-                    ctx,
-                    markup_text(
-                        f"[{WARNING_STYLE}]⚠️  Could not fetch full agent details: {e}[/]"
-                    ),
-                )
-                handle_rich_output(
-                    ctx,
-                    markup_text(
-                        f"[{WARNING_STYLE}]⚠️  Proceeding with available data[/]"
-                    ),
-                )
-
-            export_resource_to_file(agent, export_path, detected_format)
-            handle_rich_output(
+            handle_resource_export(
                 ctx,
-                markup_text(
-                    f"[{SUCCESS_STYLE}]✅ Complete agent configuration exported to: {export_path} (format: {detected_format})[/]"
-                ),
+                agent,
+                Path(export),
+                resource_type="agent",
+                get_by_id_func=api_client.agents.get_agent_by_id,
+                console_override=console,
             )
 
         # Display full agent details using the standardized helper
-        _display_agent_details(ctx, client, agent)
+        _display_agent_details(
+            ctx,
+            api_client,
+            agent,
+            instruction_preview_limit=instruction_preview,
+        )
 
         # Show run suggestions via centralized display helper
         handle_rich_output(ctx, display_agent_run_suggestions(agent))
 
+    except click.ClickException:
+        raise
     except Exception as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def _validate_run_input(input_option: str | None, input_text: str | None) -> str:
@@ -569,9 +682,7 @@ def _validate_run_input(input_option: str | None, input_text: str | None) -> str
     final_input_text = input_option if input_option else input_text
 
     if not final_input_text:
-        raise click.ClickException(
-            "Input text is required. Use either positional argument or --input option."
-        )
+        raise click.ClickException("Input text is required. Use either positional argument or --input option.")
 
     return final_input_text
 
@@ -583,8 +694,8 @@ def _parse_chat_history(chat_history: str | None) -> list[dict[str, Any]] | None
 
     try:
         return json.loads(chat_history)
-    except json.JSONDecodeError:
-        raise click.ClickException("Invalid JSON in chat history")
+    except json.JSONDecodeError as err:
+        raise click.ClickException("Invalid JSON in chat history") from err
 
 
 def _setup_run_renderer(ctx: Any, save: str | None, verbose: bool) -> Any:
@@ -598,6 +709,23 @@ def _setup_run_renderer(ctx: Any, save: str | None, verbose: bool) -> Any:
     )
 
 
+def _maybe_attach_transcript_toggle(ctx: Any, renderer: Any) -> None:
+    """Attach transcript toggle controller when interactive TTY is available."""
+    if renderer is None:
+        return
+
+    console_obj = getattr(renderer, "console", None)
+    if console_obj is None or not getattr(console_obj, "is_terminal", False):
+        return
+
+    tty_enabled = bool(get_ctx_value(ctx, "tty", True))
+    if not tty_enabled:
+        return
+
+    controller = TranscriptToggleController(enabled=True)
+    renderer.transcript_controller = controller
+
+
 def _prepare_run_kwargs(
     agent: Any,
     final_input_text: str,
@@ -647,9 +775,7 @@ def _save_run_transcript(save: str | None, result: Any, working_console: Any) ->
     if ext == "json":
         save_data = {
             "output": result or "",
-            "full_debug_output": getattr(
-                working_console, "get_captured_output", lambda: ""
-            )(),
+            "full_debug_output": getattr(working_console, "get_captured_output", lambda: "")(),
             "timestamp": "captured during agent execution",
         }
         content = json.dumps(save_data, indent=2)
@@ -662,9 +788,7 @@ def _save_run_transcript(save: str | None, result: Any, working_console: Any) ->
 
     with open(save, "w", encoding="utf-8") as f:
         f.write(content)
-    print_markup(
-        f"[{SUCCESS_STYLE}]Full debug output saved to: {save}[/]", console=console
-    )
+    print_markup(f"[{SUCCESS_STYLE}]Full debug output saved to: {save}[/]", console=console)
 
 
 @agents_group.command()
@@ -710,10 +834,11 @@ def run(
     files: tuple[str, ...] | None,
     verbose: bool,
 ) -> None:
-    """Run an agent with input text.
+    r"""Run an agent with input text.
 
     Usage: aip agents run <agent_ref> <input_text> [OPTIONS]
 
+    \b
     Examples:
         aip agents run my-agent "Hello world"
         aip agents run agent-123 "Process this data" --timeout 600
@@ -727,12 +852,11 @@ def run(
 
     try:
         client = get_client(ctx)
-        agent = _resolve_agent(
-            ctx, client, agent_ref, select, interface_preference="fuzzy"
-        )
+        agent = _resolve_agent(ctx, client, agent_ref, select, interface_preference="fuzzy")
 
         parsed_chat_history = _parse_chat_history(chat_history)
         renderer, working_console = _setup_run_renderer(ctx, save, verbose)
+        _maybe_attach_transcript_toggle(ctx, renderer)
 
         try:
             client.timeout = float(timeout)
@@ -777,17 +901,19 @@ def run(
     except AgentTimeoutError as e:
         error_msg = str(e)
         handle_json_output(ctx, error=Exception(error_msg))
-        raise click.ClickException(error_msg)
+        raise click.ClickException(error_msg) from e
     except Exception as e:
         _handle_command_exception(ctx, e)
 
 
 def _running_in_slash_mode(ctx: Any) -> bool:
+    """Return True if the command is executing inside the slash session."""
     ctx_obj = getattr(ctx, "obj", None)
     return isinstance(ctx_obj, dict) and bool(ctx_obj.get("_slash_session"))
 
 
 def _emit_verbose_guidance(ctx: Any) -> None:
+    """Explain the modern alternative to the deprecated --verbose flag."""
     if _running_in_slash_mode(ctx):
         message = (
             "[dim]Tip:[/] Verbose streaming has been retired in the command palette. Run the agent normally and open "
@@ -866,16 +992,12 @@ def _extract_and_validate_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)"
-        )
+        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]:
+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)
@@ -886,19 +1008,11 @@ def _validate_and_coerce_fields(
     return name, instruction, timeout
 
 
-def _resolve_resources(
-    client: Any, tools: tuple, agents: tuple, mcps: tuple
-) -> tuple[list, list, list]:
+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"
-    )
+    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
 
@@ -925,16 +1039,12 @@ def _build_create_kwargs(
     }
 
     # Handle language model selection
-    lm_selection_dict, should_strip_lm_identity = resolve_language_model_selection(
-        merged_data, model
-    )
+    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
-        )
+        _add_import_file_attributes(create_kwargs, merged_data, should_strip_lm_identity)
 
     return create_kwargs
 
@@ -980,12 +1090,7 @@ def _get_language_model_display_name(agent: Any, model: str | None) -> str:
     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)"
-        )
+        lm_display = cfg.get("lm_name") or cfg.get("model") or model or f"{DEFAULT_MODEL} (backend default)"
     return lm_display
 
 
@@ -1020,7 +1125,7 @@ def _handle_command_exception(ctx: Any, e: Exception) -> None:
     handle_json_output(ctx, error=e)
     if get_ctx_value(ctx, "view") != "json":
         print_api_error(e)
-    raise click.ClickException(str(e))
+    raise click.exceptions.Exit(1) from e
 
 
 def _handle_creation_exception(ctx: Any, e: Exception) -> None:
@@ -1063,8 +1168,9 @@ def create(
     timeout: float | None,
     import_file: str | None,
 ) -> None:
-    """Create a new agent.
+    r"""Create a new agent.
 
+    \b
     Examples:
         aip agents create --name "My Agent" --instruction "You are a helpful assistant"
         aip agents create --import agent.json
@@ -1074,13 +1180,9 @@ def create(
 
         # Handle import file or CLI args
         if import_file:
-            merged_data = _handle_import_file_logic(
-                import_file, model, name, instruction, tools, agents, mcps, timeout
-            )
+            merged_data = _handle_import_file_logic(import_file, model, name, instruction, tools, agents, mcps, timeout)
         else:
-            merged_data = _build_cli_args_data(
-                name, instruction, model, tools, agents, mcps, timeout
-            )
+            merged_data = _build_cli_args_data(name, instruction, model, tools, agents, mcps, timeout)
 
         # Extract and validate fields
         (
@@ -1092,14 +1194,10 @@ def create(
             mcps,
             timeout,
         ) = _extract_and_validate_fields(merged_data)
-        name, instruction, timeout = _validate_and_coerce_fields(
-            name, instruction, timeout
-        )
+        name, instruction, timeout = _validate_and_coerce_fields(name, instruction, timeout)
 
         # Resolve resources
-        resolved_tools, resolved_agents, resolved_mcps = _resolve_resources(
-            client, tools, agents, mcps
-        )
+        resolved_tools, resolved_agents, resolved_mcps = _resolve_resources(client, tools, agents, mcps)
 
         # Build create kwargs
         create_kwargs = _build_create_kwargs(
@@ -1129,7 +1227,7 @@ def _get_agent_for_update(client: Any, agent_id: str) -> Any:
     try:
         return client.agents.get_agent_by_id(agent_id)
     except Exception as e:
-        raise click.ClickException(f"Agent with ID '{agent_id}' not found: {e}")
+        raise click.ClickException(f"Agent with ID '{agent_id}' not found: {e}") from e
 
 
 def _handle_update_import_file(
@@ -1211,16 +1309,12 @@ def _handle_update_import_config(
     if not import_file:
         return
 
-    lm_selection, should_strip_lm_identity = resolve_language_model_selection(
-        merged_data, None
-    )
+    lm_selection, should_strip_lm_identity = resolve_language_model_selection(merged_data, None)
     update_data.update(lm_selection)
 
     raw_cfg = merged_data.get("agent_config") if isinstance(merged_data, dict) else None
     if isinstance(raw_cfg, dict):
-        update_data["agent_config"] = sanitize_agent_config(
-            raw_cfg, strip_lm_identity=should_strip_lm_identity
-        )
+        update_data["agent_config"] = sanitize_agent_config(raw_cfg, strip_lm_identity=should_strip_lm_identity)
 
     excluded_fields = {
         "name",
@@ -1270,8 +1364,9 @@ def update(
     timeout: float | None,
     import_file: str | None,
 ) -> None:
-    """Update an existing agent.
+    r"""Update an existing agent.
 
+    \b
     Examples:
         aip agents update my-agent --instruction "New instruction"
         aip agents update my-agent --import agent.json
@@ -1289,16 +1384,18 @@ def update(
             agents,
             mcps,
             timeout,
-        ) = _handle_update_import_file(
-            import_file, name, instruction, tools, agents, mcps, timeout
-        )
+        ) = _handle_update_import_file(import_file, name, instruction, tools, agents, mcps, timeout)
 
-        update_data = _build_update_data(
-            name, instruction, tools, agents, mcps, timeout
-        )
+        update_data = _build_update_data(name, instruction, tools, agents, mcps, timeout)
 
         if merged_data:
             _handle_update_import_config(import_file, merged_data, update_data)
+            # Ensure instruction from import file is included if not already set via CLI
+            # This handles the case where instruction is None in CLI args but exists in import file
+            if import_file and (instruction is None or "instruction" not in update_data):
+                import_instruction = merged_data.get("instruction")
+                if import_instruction is not None:
+                    update_data["instruction"] = import_instruction
 
         if not update_data:
             raise click.ClickException("No update fields specified")
@@ -1333,7 +1430,7 @@ def delete(ctx: Any, agent_id: str, yes: bool) -> None:
         try:
             agent = client.agents.get_agent_by_id(agent_id)
         except Exception as e:
-            raise click.ClickException(f"Agent with ID '{agent_id}' not found: {e}")
+            raise click.ClickException(f"Agent with ID '{agent_id}' not found: {e}") from e
 
         # Confirm deletion when not forced
         if not yes and not display_confirmation_prompt("Agent", agent.name):
@@ -1365,13 +1462,11 @@ def delete(ctx: Any, agent_id: str, yes: bool) -> None:
     "--base-url",
     help="Custom LangFlow server base URL (overrides LANGFLOW_BASE_URL env var)",
 )
-@click.option(
-    "--api-key", help="Custom LangFlow API key (overrides LANGFLOW_API_KEY env var)"
-)
+@click.option("--api-key", help="Custom LangFlow API key (overrides LANGFLOW_API_KEY env var)")
 @output_flags()
 @click.pass_context
 def sync_langflow(ctx: Any, base_url: str | None, api_key: str | None) -> None:
-    """Sync agents with LangFlow server flows.
+    r"""Sync agents with LangFlow server flows.
 
     This command fetches all flows from the configured LangFlow server and
     creates/updates corresponding agents in the platform.
@@ -1380,6 +1475,7 @@ def sync_langflow(ctx: Any, base_url: str | None, api_key: str | None) -> None:
     - Command options (--base-url, --api-key)
     - Environment variables (LANGFLOW_BASE_URL, LANGFLOW_API_KEY)
 
+    \b
     Examples:
         aip agents sync-langflow
         aip agents sync-langflow --base-url https://my-langflow.com --api-key my-key
@@ -1396,15 +1492,16 @@ def sync_langflow(ctx: Any, base_url: str | None, api_key: str | None) -> None:
         # Show success message for non-JSON output
         if get_ctx_value(ctx, "view") != "json":
             # Extract some useful info from the result
-            success_count = result.get("data", {}).get("created_count", 0) + result.get(
-                "data", {}
-            ).get("updated_count", 0)
+            success_count = result.get("data", {}).get("created_count", 0) + result.get("data", {}).get(
+                "updated_count", 0
+            )
             total_count = result.get("data", {}).get("total_processed", 0)
 
             handle_rich_output(
                 ctx,
                 markup_text(
-                    f"[{SUCCESS_STYLE}]✅ Successfully synced {success_count} LangFlow agents ({total_count} total processed)[/]"
+                    f"[{SUCCESS_STYLE}]✅ Successfully synced {success_count} LangFlow agents "
+                    f"({total_count} total processed)[/]"
                 ),
             )