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

glaip_sdk/cli/commands/agents.py

@@ -1,1412 +0,0 @@
-"""Agent CLI commands for AIP SDK.
-
-Authors:
-    Raymond Christopher (raymond.christopher@gdplabs.id)
-"""
-
-from __future__ import annotations
-
-import json
-import os
-from collections.abc import Mapping
-from pathlib import Path
-from typing import Any
-
-import click
-from rich.console import Console
-
-from glaip_sdk.branding import (
-    ACCENT_STYLE,
-    ERROR_STYLE,
-    INFO,
-    SUCCESS,
-    SUCCESS_STYLE,
-    WARNING_STYLE,
-)
-from glaip_sdk.cli.agent_config import (
-    merge_agent_config_with_cli_args as merge_import_with_cli_args,
-)
-from glaip_sdk.cli.agent_config import (
-    resolve_agent_language_model_selection as resolve_language_model_selection,
-)
-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.display import (
-    build_resource_result_data,
-    display_agent_run_suggestions,
-    display_confirmation_prompt,
-    display_creation_success,
-    display_deletion_success,
-    display_update_success,
-    handle_json_output,
-    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.io import (
-    fetch_raw_resource_details,
-)
-from glaip_sdk.cli.io import (
-    load_resource_from_file_with_validation as load_resource_from_file,
-)
-from glaip_sdk.cli.resolution import resolve_resource_reference
-from glaip_sdk.cli.rich_helpers import markup_text, print_markup
-from glaip_sdk.cli.transcript import (
-    maybe_launch_post_run_viewer,
-    store_transcript_for_session,
-)
-from glaip_sdk.cli.utils import (
-    _fuzzy_pick_for_resources,
-    build_renderer,
-    coerce_to_row,
-    get_client,
-    output_list,
-    output_result,
-    spinner_context,
-)
-from glaip_sdk.cli.validators import (
-    validate_agent_instruction_cli as validate_agent_instruction,
-)
-from glaip_sdk.cli.validators import (
-    validate_agent_name_cli as validate_agent_name,
-)
-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.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.validation import coerce_timeout
-
-console = Console()
-
-# Error message constants
-AGENT_NOT_FOUND_ERROR = "Agent not found"
-
-
-def _safe_agent_attribute(agent: Any, name: str) -> Any:
-    """Return attribute value for ``name`` while filtering Mock sentinels."""
-    try:
-        value = getattr(agent, name)
-    except Exception:
-        return None
-
-    if hasattr(value, "_mock_name"):
-        return None
-    return value
-
-
-def _coerce_mapping_candidate(candidate: Any) -> dict[str, Any] | None:
-    """Convert a mapping-like candidate to a plain dict when possible."""
-    if candidate is None:
-        return None
-    if isinstance(candidate, Mapping):
-        return dict(candidate)
-    return None
-
-
-def _call_agent_method(agent: Any, method_name: str) -> dict[str, Any] | None:
-    """Attempt to call the named method and coerce its output to a dict."""
-    method = getattr(agent, method_name, None)
-    if not callable(method):
-        return None
-    try:
-        candidate = method()
-    except Exception:
-        return None
-    return _coerce_mapping_candidate(candidate)
-
-
-def _coerce_agent_via_methods(agent: Any) -> dict[str, Any] | None:
-    """Try standard serialisation helpers to produce a mapping."""
-    for attr in ("model_dump", "dict", "to_dict"):
-        mapping = _call_agent_method(agent, attr)
-        if mapping is not None:
-            return mapping
-    return None
-
-
-def _build_fallback_agent_mapping(agent: Any) -> dict[str, Any]:
-    """Construct a minimal mapping from well-known agent attributes."""
-    fallback_fields = (
-        "id",
-        "name",
-        "instruction",
-        "description",
-        "model",
-        "agent_config",
-        "tools",
-        "agents",
-        "mcps",
-        "timeout",
-        "tool_configs",
-    )
-
-    fallback: dict[str, Any] = {}
-    for field in fallback_fields:
-        value = _safe_agent_attribute(agent, field)
-        if value is not None:
-            fallback[field] = value
-
-    return fallback or {"name": str(agent)}
-
-
-def _prepare_agent_output(agent: Any) -> dict[str, Any]:
-    """Build a JSON-serialisable mapping for CLI output."""
-    method_mapping = _coerce_agent_via_methods(agent)
-    if method_mapping is not None:
-        return method_mapping
-
-    intrinsic = _coerce_mapping_candidate(agent)
-    if intrinsic is not None:
-        return intrinsic
-
-    return _build_fallback_agent_mapping(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()
-        if agent_id:
-            return client.agents.get_agent_by_id(agent_id)
-    except Exception:
-        # If fetching full details fails, continue with the resolved object
-        pass
-    return agent
-
-
-def _normalise_model_name(value: Any) -> str | None:
-    """Return a cleaned model name or None when not usable."""
-    if value is None:
-        return None
-    if isinstance(value, str):
-        cleaned = value.strip()
-        return cleaned or None
-    if isinstance(value, bool):
-        return None
-    return str(value)
-
-
-def _model_from_config(agent: Any) -> str | None:
-    """Extract a usable model name from an agent's configuration mapping."""
-    config = getattr(agent, "agent_config", None)
-    if not config or not isinstance(config, dict):
-        return None
-
-    for key in ("lm_name", "model"):
-        normalised = _normalise_model_name(config.get(key))
-        if normalised:
-            return normalised
-    return None
-
-
-def _get_agent_model_name(agent: Any) -> str | None:
-    """Extract model name from agent configuration."""
-    config_model = _model_from_config(agent)
-    if config_model:
-        return config_model
-
-    normalised_attr = _normalise_model_name(getattr(agent, "model", None))
-    if normalised_attr:
-        return normalised_attr
-
-    return DEFAULT_MODEL
-
-
-def _resolve_resources_by_name(
-    _client: Any, items: tuple[str, ...], resource_type: str, find_func: Any, label: str
-) -> list[str]:
-    """Resolve resource names/IDs to IDs, handling ambiguity.
-
-    Args:
-        client: API client
-        items: Tuple of resource names/IDs
-        resource_type: Type of resource ("tool" or "agent")
-        find_func: Function to find resources by name
-        label: Label for error messages
-
-    Returns:
-        List of resolved resource IDs
-    """
-    out = []
-    for ref in items or ():
-        if is_uuid(ref):
-            out.append(ref)
-            continue
-
-        matches = find_func(name=ref)
-        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."
-            )
-        out.append(str(matches[0].id))
-    return out
-
-
-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
-
-        # 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"])
-
-        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",
-        "tools",
-        "agents",
-        "mcps",
-        "a2a_profile",
-        "tool_configs",
-    ]
-
-    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, markup_text(f"[{ERROR_STYLE}]❌ No agent provided[/]"))
-        return
-
-    # Try to fetch and format raw agent data first
-    with spinner_context(
-        ctx,
-        "[bold blue]Loading agent details…[/bold blue]",
-        console_override=console,
-    ):
-        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"{ICON_AGENT} {formatted_data.get('name', 'Unknown')}"
-        output_result(
-            ctx,
-            formatted_data,
-            title=panel_title,
-        )
-    else:
-        # Fall back to Pydantic model data if raw fetch fails
-        handle_rich_output(
-            ctx,
-            markup_text(f"[{WARNING_STYLE}]Falling back to Pydantic model data[/]"),
-        )
-
-        with spinner_context(
-            ctx,
-            "[bold blue]Preparing fallback agent details…[/bold blue]",
-            console_override=console,
-        ):
-            result_data = _format_fallback_agent_data(client, agent)
-
-        # Display using output_result
-        output_result(
-            ctx,
-            result_data,
-            title="Agent Details",
-        )
-
-
-@click.group(name="agents", no_args_is_help=True)
-def agents_group() -> None:
-    """Agent management operations."""
-    pass
-
-
-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:
-        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.
-
-    Returns:
-        Resolved agent object or None if not found.
-    """
-    return resolve_resource_reference(
-        ctx,
-        client,
-        ref,
-        "agent",
-        client.agents.get_agent_by_id,
-        client.agents.find_agents,
-        "Agent",
-        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("--name", help="Filter by partial name match (case-insensitive)")
-@click.option("--version", help="Filter by exact version match")
-@click.option(
-    "--sync-langflow",
-    is_flag=True,
-    help="Sync with LangFlow server before listing (only applies when filtering by langflow type)",
-)
-@output_flags()
-@click.pass_context
-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)
-        with spinner_context(
-            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,
-            )
-
-        # Define table columns: (data_key, header, style, width)
-        columns = [
-            ("id", "ID", "dim", 36),
-            ("name", "Name", ACCENT_STYLE, None),
-            ("type", "Type", WARNING_STYLE, None),
-            ("framework", "Framework", INFO, None),
-            ("version", "Version", SUCCESS, None),
-        ]
-
-        # Transform function for safe attribute access
-        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"])
-            return row
-
-        # Use fuzzy picker for interactive agent selection and details (default behavior)
-        # Skip if --simple flag is used, a name filter is applied, or non-rich output is requested
-        ctx_obj = ctx.obj if isinstance(getattr(ctx, "obj", None), dict) else {}
-        current_view = ctx_obj.get("view")
-        interactive_enabled = (
-            not simple
-            and name is None
-            and current_view not in {"json", "plain", "md"}
-            and console.is_terminal
-            and os.isatty(1)
-            and len(agents) > 0
-        )
-
-        if interactive_enabled:
-            picked_agent = _fuzzy_pick_for_resources(agents, "agent", "")
-            if picked_agent:
-                _display_agent_details(ctx, client, picked_agent)
-                # Show run suggestions via centralized display helper
-                handle_rich_output(ctx, display_agent_run_suggestions(picked_agent))
-                return
-
-        # Show simple table (either --simple flag or non-interactive)
-        output_list(
-            ctx,
-            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)
-            ),
-            use_pager=False,
-        )
-
-    except Exception as e:
-        raise click.ClickException(str(e))
-
-
-@agents_group.command()
-@click.argument("agent_ref")
-@click.option("--select", type=int, help="Choose among ambiguous matches (1-based)")
-@click.option(
-    "--export",
-    type=click.Path(dir_okay=False, writable=True),
-    help="Export complete agent configuration to file (format auto-detected from .json/.yaml extension)",
-)
-@output_flags()
-@click.pass_context
-def get(ctx: Any, agent_ref: str, select: int | None, export: str | None) -> None:
-    """Get agent details.
-
-    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)
-
-        # Resolve agent with ambiguity handling - use questionary interface for traditional UX
-        agent = _resolve_agent(
-            ctx, client, agent_ref, select, interface_preference="questionary"
-        )
-
-        # Handle export option
-        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(
-                ctx,
-                markup_text(
-                    f"[{SUCCESS_STYLE}]✅ Complete agent configuration exported to: {export_path} (format: {detected_format})[/]"
-                ),
-            )
-
-        # Display full agent details using the standardized helper
-        _display_agent_details(ctx, client, agent)
-
-        # Show run suggestions via centralized display helper
-        handle_rich_output(ctx, display_agent_run_suggestions(agent))
-
-    except Exception as e:
-        raise click.ClickException(str(e))
-
-
-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
-
-    if not final_input_text:
-        raise click.ClickException(
-            "Input text is required. Use either positional argument or --input option."
-        )
-
-    return final_input_text
-
-
-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
-
-    try:
-        return json.loads(chat_history)
-    except json.JSONDecodeError:
-        raise click.ClickException("Invalid JSON in chat history")
-
-
-def _setup_run_renderer(ctx: Any, save: str | None, verbose: bool) -> Any:
-    """Set up renderer and working console for agent run."""
-    tty_enabled = bool(get_ctx_value(ctx, "tty", True))
-    return build_renderer(
-        ctx,
-        save_path=save,
-        verbose=verbose,
-        _tty_enabled=tty_enabled,
-    )
-
-
-def _prepare_run_kwargs(
-    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,
-        "message": final_input_text,
-        "files": list(files),
-        "agent_name": agent.name,
-        "tty": tty_enabled,
-    }
-
-    if parsed_chat_history:
-        run_kwargs["chat_history"] = parsed_chat_history
-
-    if renderer is not None:
-        run_kwargs["renderer"] = renderer
-
-    return run_kwargs
-
-
-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 = get_ctx_value(ctx, "view", "rich")
-
-    if not printed_by_renderer:
-        if selected_view == "json":
-            handle_json_output(ctx, {"output": result})
-        elif selected_view == "md":
-            click.echo(f"# Assistant\n\n{result}")
-        elif selected_view == "plain":
-            click.echo(result)
-
-
-def _save_run_transcript(save: str | None, result: Any, working_console: Any) -> None:
-    """Save transcript to file if requested."""
-    if not save:
-        return
-
-    ext = (save.rsplit(".", 1)[-1] or "").lower()
-    if ext == "json":
-        save_data = {
-            "output": result or "",
-            "full_debug_output": getattr(
-                working_console, "get_captured_output", lambda: ""
-            )(),
-            "timestamp": "captured during agent execution",
-        }
-        content = json.dumps(save_data, indent=2)
-    else:
-        full_output = getattr(working_console, "get_captured_output", lambda: "")()
-        if full_output:
-            content = f"# Agent Debug Log\n\n{full_output}\n\n---\n\n## Final Result\n\n{result or ''}\n"
-        else:
-            content = f"# Assistant\n\n{result or ''}\n"
-
-    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
-    )
-
-
-@agents_group.command()
-@click.argument("agent_ref")
-@click.argument("input_text", required=False)
-@click.option("--select", type=int, help="Choose among ambiguous matches (1-based)")
-@click.option("--input", "input_option", help="Input text for the agent")
-@click.option("--chat-history", help="JSON string of chat history")
-@click.option(
-    "--timeout",
-    default=DEFAULT_AGENT_RUN_TIMEOUT,
-    type=int,
-    help="Agent execution timeout in seconds (default: 300s)",
-)
-@click.option(
-    "--save",
-    type=click.Path(dir_okay=False, writable=True),
-    help="Save transcript to file (md or json)",
-)
-@click.option(
-    "--file",
-    "files",
-    multiple=True,
-    type=click.Path(exists=True),
-    help="Attach file(s)",
-)
-@click.option(
-    "--verbose/--no-verbose",
-    default=False,
-    help="Show detailed SSE events during streaming",
-)
-@output_flags()
-@click.pass_context
-def run(
-    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]
-
-    Examples:
-        aip agents run my-agent "Hello world"
-        aip agents run agent-123 "Process this data" --timeout 600
-        aip agents run my-agent --input "Hello world"  # Legacy style
-    """
-    final_input_text = _validate_run_input(input_option, input_text)
-
-    if verbose:
-        _emit_verbose_guidance(ctx)
-        return
-
-    try:
-        client = get_client(ctx)
-        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)
-
-        try:
-            client.timeout = float(timeout)
-        except Exception:
-            pass
-
-        run_kwargs = _prepare_run_kwargs(
-            agent,
-            final_input_text,
-            files,
-            parsed_chat_history,
-            renderer,
-            bool(get_ctx_value(ctx, "tty", True)),
-        )
-
-        result = client.agents.run_agent(**run_kwargs, timeout=timeout)
-
-        slash_mode = _running_in_slash_mode(ctx)
-        agent_id = str(_safe_agent_attribute(agent, "id") or "") or None
-        agent_name = _safe_agent_attribute(agent, "name")
-        model_hint = _get_agent_model_name(agent)
-
-        transcript_context = store_transcript_for_session(
-            ctx,
-            renderer,
-            final_result=result,
-            agent_id=agent_id,
-            agent_name=agent_name,
-            model=model_hint,
-            source="slash" if slash_mode else "cli",
-        )
-
-        _handle_run_output(ctx, result, renderer)
-        _save_run_transcript(save, result, working_console)
-        maybe_launch_post_run_viewer(
-            ctx,
-            transcript_context,
-            console=console,
-            slash_mode=slash_mode,
-        )
-
-    except AgentTimeoutError as e:
-        error_msg = str(e)
-        handle_json_output(ctx, error=Exception(error_msg))
-        raise click.ClickException(error_msg)
-    except Exception as e:
-        _handle_command_exception(ctx, e)
-
-
-def _running_in_slash_mode(ctx: Any) -> bool:
-    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:
-    if _running_in_slash_mode(ctx):
-        message = (
-            "[dim]Tip:[/] Verbose streaming has been retired in the command palette. Run the agent normally and open "
-            "the post-run viewer (Ctrl+T) to inspect the transcript."
-        )
-    else:
-        message = (
-            "[dim]Tip:[/] `--verbose` is no longer supported. Re-run without the flag and toggle the post-run viewer "
-            "(Ctrl+T) for detailed output."
-        )
-    handle_rich_output(ctx, markup_text(message))
-
-
-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",
-        "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, _prepare_agent_output(agent))
-
-    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()
-@click.option("--name", help="Agent name")
-@click.option("--instruction", help="Agent instruction (prompt)")
-@click.option(
-    "--model",
-    help=f"Language model to use (e.g., {DEFAULT_MODEL}, default: {DEFAULT_MODEL})",
-)
-@click.option("--tools", multiple=True, help="Tool names or IDs to attach")
-@click.option("--agents", multiple=True, help="Sub-agent names or IDs to attach")
-@click.option("--mcps", multiple=True, help="MCP names or IDs to attach")
-@click.option(
-    "--timeout",
-    default=DEFAULT_AGENT_RUN_TIMEOUT,
-    type=int,
-    help="Agent execution timeout in seconds (default: 300s)",
-)
-@click.option(
-    "--import",
-    "import_file",
-    type=click.Path(exists=True, dir_okay=False),
-    help="Import agent configuration from JSON file",
-)
-@output_flags()
-@click.pass_context
-def create(
-    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:
-        aip agents create --name "My Agent" --instruction "You are a helpful assistant"
-        aip agents create --import agent.json
-    """
-    try:
-        client = get_client(ctx)
-
-        # 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:
-            merged_data = _build_cli_args_data(
-                name, instruction, model, tools, agents, mcps, timeout
-            )
-
-        # 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
-        )
-
-        # Resolve resources
-        resolved_tools, resolved_agents, resolved_mcps = _resolve_resources(
-            client, tools, agents, mcps
-        )
-
-        # 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 successful creation
-        _handle_successful_creation(ctx, agent, model)
-
-    except Exception as e:
-        _handle_creation_exception(ctx, e)
-
-
-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)
-    except Exception as e:
-        raise click.ClickException(f"Agent with ID '{agent_id}' not found: {e}")
-
-
-def _handle_update_import_file(
-    import_file: str | None,
-    name: str | None,
-    instruction: str | None,
-    tools: tuple[str, ...] | None,
-    agents: tuple[str, ...] | None,
-    mcps: tuple[str, ...] | None,
-    timeout: float | None,
-) -> tuple[
-    Any | None,
-    str | None,
-    str | None,
-    tuple[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, mcps, timeout
-
-    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, None)
-
-    cli_args = {
-        "name": name,
-        "instruction": instruction,
-        "tools": tools or (),
-        "agents": agents or (),
-        "mcps": mcps or (),
-        "timeout": timeout,
-    }
-
-    merged_data = merge_import_with_cli_args(import_data, cli_args)
-
-    return (
-        merged_data,
-        merged_data.get("name"),
-        merged_data.get("instruction"),
-        tuple(merged_data.get("tools", ())),
-        tuple(merged_data.get("agents", ())),
-        tuple(merged_data.get("mcps", ())),
-        coerce_timeout(merged_data.get("timeout")),
-    )
-
-
-def _build_update_data(
-    name: str | None,
-    instruction: str | None,
-    tools: tuple[str, ...] | None,
-    agents: tuple[str, ...] | None,
-    mcps: tuple[str, ...] | None,
-    timeout: float | None,
-) -> dict[str, Any]:
-    """Build the update data dictionary from provided parameters."""
-    update_data = {}
-    if name is not None:
-        update_data["name"] = name
-    if instruction is not None:
-        update_data["instruction"] = instruction
-    if tools:
-        update_data["tools"] = list(tools)
-    if agents:
-        update_data["agents"] = list(agents)
-    if mcps:
-        update_data["mcps"] = list(mcps)
-    if timeout is not None:
-        update_data["timeout"] = timeout
-    return 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
-
-    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
-        )
-
-    excluded_fields = {
-        "name",
-        "instruction",
-        "tools",
-        "agents",
-        "timeout",
-        "agent_config",
-        "language_model_id",
-        "id",
-        "created_at",
-        "updated_at",
-        "type",
-        "framework",
-        "version",
-        "a2a_profile",
-    }
-    for key, value in merged_data.items():
-        if key not in excluded_fields and value is not None:
-            update_data[key] = value
-
-
-@agents_group.command()
-@click.argument("agent_id")
-@click.option("--name", help="New agent name")
-@click.option("--instruction", help="New instruction")
-@click.option("--tools", multiple=True, help="New tool names or IDs")
-@click.option("--agents", multiple=True, help="New sub-agent names")
-@click.option("--mcps", multiple=True, help="New MCP names or IDs")
-@click.option("--timeout", type=int, help="New timeout value")
-@click.option(
-    "--import",
-    "import_file",
-    type=click.Path(exists=True, dir_okay=False),
-    help="Import agent configuration from JSON file",
-)
-@output_flags()
-@click.pass_context
-def update(
-    ctx: Any,
-    agent_id: str,
-    name: str | None,
-    instruction: str | None,
-    tools: tuple[str, ...] | None,
-    agents: tuple[str, ...] | None,
-    mcps: tuple[str, ...] | None,
-    timeout: float | None,
-    import_file: str | None,
-) -> None:
-    """Update an existing agent.
-
-    Examples:
-        aip agents update my-agent --instruction "New instruction"
-        aip agents update my-agent --import agent.json
-    """
-    try:
-        client = get_client(ctx)
-        agent = _get_agent_for_update(client, agent_id)
-
-        # Handle import file processing
-        (
-            merged_data,
-            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
-        )
-
-        if merged_data:
-            _handle_update_import_config(import_file, merged_data, update_data)
-
-        if not update_data:
-            raise click.ClickException("No update fields specified")
-
-        updated_agent = client.agents.update_agent(agent.id, **update_data)
-
-        handle_json_output(ctx, _prepare_agent_output(updated_agent))
-        handle_rich_output(ctx, display_update_success("Agent", updated_agent.name))
-        handle_rich_output(ctx, display_agent_run_suggestions(updated_agent))
-
-    except click.ClickException:
-        # Handle JSON output for ClickExceptions if view is 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_command_exception(ctx, e)
-
-
-@agents_group.command()
-@click.argument("agent_id")
-@click.option("-y", "--yes", is_flag=True, help="Skip confirmation")
-@output_flags()
-@click.pass_context
-def delete(ctx: Any, agent_id: str, yes: bool) -> None:
-    """Delete an agent."""
-    try:
-        client = get_client(ctx)
-
-        # Get agent by ID (no ambiguity handling needed)
-        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}")
-
-        # Confirm deletion when not forced
-        if not yes and not display_confirmation_prompt("Agent", agent.name):
-            return
-
-        client.agents.delete_agent(agent.id)
-
-        handle_json_output(
-            ctx,
-            {
-                "success": True,
-                "message": f"Agent '{agent.name}' deleted",
-            },
-        )
-        handle_rich_output(ctx, display_deletion_success("Agent", agent.name))
-
-    except click.ClickException:
-        # Handle JSON output for ClickExceptions if view is 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_command_exception(ctx, e)
-
-
-@agents_group.command()
-@click.option(
-    "--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)"
-)
-@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.
-
-    This command fetches all flows from the configured LangFlow server and
-    creates/updates corresponding agents in the platform.
-
-    The LangFlow server configuration can be provided via:
-    - Command options (--base-url, --api-key)
-    - Environment variables (LANGFLOW_BASE_URL, LANGFLOW_API_KEY)
-
-    Examples:
-        aip agents sync-langflow
-        aip agents sync-langflow --base-url https://my-langflow.com --api-key my-key
-    """
-    try:
-        client = get_client(ctx)
-
-        # Perform the sync
-        result = client.sync_langflow_agents(base_url=base_url, api_key=api_key)
-
-        # Handle output format
-        handle_json_output(ctx, result)
-
-        # 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)
-            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)[/]"
-                ),
-            )
-
-    except Exception as e:
-        _handle_command_exception(ctx, e)