applied-cli 0.1.0__py3-none-any.whl

applied_cli/commands/agent.py

@@ -0,0 +1,1231 @@
+import json
+from typing import Any, Optional
+
+import typer
+
+from applied_cli.commands._normalize import (
+    normalize_agent_type,
+    normalize_modality,
+    normalize_question,
+    normalize_response_type,
+)
+from applied_cli.commands._parsers import (
+    parse_json_dict as _parse_json_dict,
+    parse_optional_bool as _parse_optional_bool,
+    validate_uuid as _validate_uuid,
+)
+from applied_cli.commands._ui import (
+    confirm_or_exit,
+    emit_dry_run,
+    emit_success,
+    show_target,
+)
+from applied_cli.error_reporting import render_api_error
+from applied_cli.http import (
+    APIError,
+    create_agent,
+    create_response,
+    get_agent,
+    list_agents,
+    list_responses,
+    patch_response,
+    update_agent,
+)
+from applied_cli.runtime import resolve_runtime
+
+app = typer.Typer(help="Create and configure agents.")
+settings_app = typer.Typer(help="Update specific agent settings safely.")
+
+
+def _deep_merge_dict(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in patch.items():
+        existing = out.get(key)
+        if isinstance(existing, dict) and isinstance(value, dict):
+            out[key] = _deep_merge_dict(existing, value)
+        else:
+            out[key] = value
+    return out
+
+
+def _is_agent_attached(row: dict[str, Any], *, agent_id: str) -> bool:
+    agents = row.get("agents")
+    if not isinstance(agents, list):
+        return False
+    return any(isinstance(item, dict) and str(item.get("id")) == agent_id for item in agents)
+
+
+def _upsert_inline_responses(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    agent_id: str,
+    response_rows: list[dict[str, Any]],
+    dry_run: bool,
+) -> dict[str, Any]:
+    created = 0
+    updated = 0
+    unchanged = 0
+    for row in response_rows:
+        raw_type = row.get("type")
+        raw_q = row.get("question")
+        raw_a = row.get("answer")
+        if not isinstance(raw_type, str) or not isinstance(raw_q, str) or not isinstance(
+            raw_a, str
+        ):
+            raise typer.BadParameter(
+                "Each response must include string fields: type, question, answer."
+            )
+        normalized_type = normalize_response_type(raw_type, field_label="response type")
+        normalized_question = normalize_question(raw_q)
+        payload: dict[str, Any] = {
+            "agent_ids": [agent_id],
+            "type": normalized_type,
+            "question": raw_q.strip(),
+            "answer": raw_a.strip(),
+            "active": bool(row.get("active", True)),
+        }
+        guardrail = row.get("guardrail")
+        if isinstance(guardrail, str):
+            payload["guardrail"] = guardrail
+        fields_to_extract = row.get("fields_to_extract")
+        if isinstance(fields_to_extract, list):
+            payload["fields_to_extract"] = fields_to_extract
+
+        candidates = list_responses(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+            agent_id=agent_id,
+            response_type=normalized_type,
+            limit=500,
+        )
+        matched: Optional[dict[str, Any]] = None
+        for candidate in candidates:
+            if not _is_agent_attached(candidate, agent_id=agent_id):
+                continue
+            if normalize_question(str(candidate.get("question") or "")) == normalized_question:
+                matched = candidate
+                break
+        if matched is None:
+            created += 1
+            if not dry_run:
+                create_response(
+                    base_url=base_url,
+                    shop_id=shop_id,
+                    api_token=api_token,
+                    payload=payload,
+                )
+            continue
+        raw_current_fields = matched.get("fields_to_extract")
+        raw_target_fields = payload.get("fields_to_extract")
+        current_reduced = {
+            "type": str(matched.get("type") or "").strip().lower(),
+            "question": str(matched.get("question") or "").strip(),
+            "answer": str(matched.get("answer") or "").strip(),
+            "guardrail": str(matched.get("guardrail") or "").strip(),
+            "active": bool(matched.get("active")),
+            "fields_to_extract": raw_current_fields
+            if isinstance(raw_current_fields, list)
+            else [],
+        }
+        target_reduced = {
+            "type": str(payload.get("type") or "").strip().lower(),
+            "question": str(payload.get("question") or "").strip(),
+            "answer": str(payload.get("answer") or "").strip(),
+            "guardrail": str(payload.get("guardrail") or "").strip(),
+            "active": bool(payload.get("active")),
+            "fields_to_extract": raw_target_fields
+            if isinstance(raw_target_fields, list)
+            else [],
+        }
+        if current_reduced == target_reduced:
+            unchanged += 1
+        else:
+            updated += 1
+            if not dry_run:
+                patch_response(
+                    base_url=base_url,
+                    shop_id=shop_id,
+                    api_token=api_token,
+                    response_id=str(matched.get("id")),
+                    payload=payload,
+                )
+    return {"created": created, "updated": updated, "unchanged": unchanged}
+
+
+def _resolve_metadata_options(
+    *,
+    merge_raw: Optional[str],
+    replace_raw: Optional[str],
+    current_metadata: Optional[dict[str, Any]] = None,
+) -> Optional[dict[str, Any]]:
+    metadata_merge = _parse_json_dict(merge_raw, field_name="metadata-merge-json")
+    metadata_replace = _parse_json_dict(replace_raw, field_name="metadata-replace-json")
+    if metadata_merge is not None and metadata_replace is not None:
+        raise typer.BadParameter(
+            "Use either --metadata-merge-json or --metadata-replace-json, not both."
+        )
+    if metadata_replace is not None:
+        return metadata_replace
+    if metadata_merge is not None:
+        base = current_metadata or {}
+        return _deep_merge_dict(base, metadata_merge)
+    return None
+
+
+@app.command(
+    "list",
+    help="List agents in a shop. Example: applied-cli agent list --limit 20",
+)
+def list_cmd(
+    limit: int = typer.Option(100, "--limit", help="Maximum number of agents."),
+    ordering: str = typer.Option(
+        "-created_at", "--ordering", help="Ordering field, e.g. -created_at."
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        rows = list_agents(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            limit=limit,
+            ordering=ordering,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list agents"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    if output_json:
+        typer.echo(json.dumps(rows, indent=2, default=str))
+        return
+    if not rows:
+        typer.echo("No results.")
+        return
+    for row in rows:
+        typer.echo(
+            f"id={row.get('id')} | name={row.get('name')} | modality={row.get('modality')} | type={row.get('type')} | auto_reply={row.get('auto_reply')} | created_at={row.get('created_at')}"
+        )
+
+
+@app.command(
+    "show",
+    help="Show one agent by UUID. Example: applied-cli agent show --agent-id <uuid>",
+)
+def show(
+    agent_id: str = typer.Option(
+        ..., "--agent-id", "--agent", "--id", help="Target agent UUID."
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        row = get_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="show agent"), err=True)
+        if exc.status_code == 404:
+            typer.echo(
+                "Hint: verify `agent-id` and shop scope with `applied-cli agent list --json`.",
+                err=True,
+            )
+        raise typer.Exit(code=1) from exc
+
+    if output_json:
+        typer.echo(json.dumps(row, indent=2, default=str))
+        return
+    typer.echo(f"id={row.get('id')}")
+    typer.echo(f"name={row.get('name')}")
+    typer.echo(f"modality={row.get('modality')}")
+    typer.echo(f"type={row.get('type')}")
+    typer.echo(f"auto_reply={row.get('auto_reply')}")
+    typer.echo(f"created_at={row.get('created_at')}")
+    typer.echo(f"updated_at={row.get('updated_at')}")
+    typer.echo(f"escalation_mode={row.get('escalation_mode')}")
+    typer.echo(f"escalation_wait_time_mode={row.get('escalation_wait_time_mode')}")
+
+
+app.command(
+    "describe",
+    help="Describe one agent by UUID. Example: applied-cli agent describe --agent-id <uuid>",
+)(show)
+
+
+@app.command(
+    "create",
+    help=(
+        "Create an agent. Example: applied-cli agent create --name Smalls "
+        "--modality chat --type customer_support"
+    ),
+)
+def create(
+    name: str = typer.Option(..., "--name", help="Agent name."),
+    modality: str = typer.Option(..., "--modality", help="all/call/sms/email/chat/internal."),
+    agent_type: str = typer.Option("customer_support", "--type", help="Agent type."),
+    description: Optional[str] = typer.Option(None, "--description", help="Agent description."),
+    model: Optional[str] = typer.Option(None, "--model", help="Model identifier."),
+    metadata_merge_json: Optional[str] = typer.Option(
+        None, "--metadata-merge-json", help="Merge JSON object into metadata."
+    ),
+    metadata_replace_json: Optional[str] = typer.Option(
+        None,
+        "--metadata-replace-json",
+        help="Replace metadata with JSON object (destructive).",
+    ),
+    suggestions: list[str] = typer.Option(
+        [], "--suggestion", help="Suggestion text. Repeat option to add many."
+    ),
+    auto_reply: bool = typer.Option(
+        True,
+        "--auto-reply/--no-auto-reply",
+        help="Whether agent automatically replies to incoming messages.",
+    ),
+    guardrail: Optional[str] = typer.Option(None, "--guardrail", help="General guardrail text."),
+    escalation_mode: Optional[str] = typer.Option(None, "--escalation-mode"),
+    escalation_wait_time_mode: Optional[str] = typer.Option(
+        None, "--escalation-wait-time-mode"
+    ),
+    response_delay_in_seconds: Optional[int] = typer.Option(
+        None, "--response-delay-seconds"
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False, help="Preview payload without writes."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    normalized_modality = normalize_modality(modality)
+    normalized_type = normalize_agent_type(agent_type)
+    metadata = _resolve_metadata_options(
+        merge_raw=metadata_merge_json,
+        replace_raw=metadata_replace_json,
+        current_metadata=None,
+    )
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="resolve runtime for agent create"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    payload: dict[str, Any] = {
+        "name": name.strip(),
+        "modality": normalized_modality,
+        "type": normalized_type,
+    }
+    if description is not None:
+        payload["description"] = description
+    if model is not None:
+        payload["model"] = model
+    if metadata is not None:
+        payload["metadata"] = metadata
+    if suggestions:
+        payload["suggestions"] = [item.strip() for item in suggestions if item.strip()]
+    payload["auto_reply"] = auto_reply
+    if guardrail is not None:
+        payload["guardrail"] = guardrail
+    if escalation_mode is not None:
+        payload["escalation_mode"] = escalation_mode
+    if escalation_wait_time_mode is not None:
+        payload["escalation_wait_time_mode"] = escalation_wait_time_mode
+    if response_delay_in_seconds is not None:
+        payload["response_delay_in_seconds"] = response_delay_in_seconds
+
+    show_target(
+        {
+            "base_url": resolved_base_url,
+            "shop_id": resolved_shop_id,
+            "name": name,
+            "modality": normalized_modality,
+            "dry_run": dry_run,
+        }
+    )
+    if metadata_replace_json is not None and not yes:
+        typer.echo(
+            "Warning: --metadata-replace-json overwrites existing metadata keys."
+        )
+    confirm_or_exit(yes=yes)
+
+    if dry_run:
+        emit_dry_run(payload={"payload": payload, "dry_run": True}, output_json=output_json)
+
+    try:
+        created = create_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="create agent"), err=True)
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=created,
+        fields={"agent_id": created.get("id")},
+    )
+
+
+@app.command(
+    "update",
+    help=(
+        "Update an existing agent. Example: applied-cli agent update --agent-id <uuid> "
+        "--no-auto-reply --guardrail 'Never disclose personal data.'"
+    ),
+)
+def update(
+    agent_id: str = typer.Option(
+        ..., "--agent-id", "--agent", "--id", help="Target agent UUID."
+    ),
+    name: Optional[str] = typer.Option(None, "--name", help="Agent name."),
+    modality: Optional[str] = typer.Option(
+        None, "--modality", help="all/call/sms/email/chat/internal."
+    ),
+    agent_type: Optional[str] = typer.Option(None, "--type", help="Agent type."),
+    description: Optional[str] = typer.Option(None, "--description", help="Agent description."),
+    model: Optional[str] = typer.Option(None, "--model", help="Model identifier."),
+    metadata_merge_json: Optional[str] = typer.Option(
+        None, "--metadata-merge-json", help="Merge JSON object into metadata."
+    ),
+    metadata_replace_json: Optional[str] = typer.Option(
+        None,
+        "--metadata-replace-json",
+        help="Replace metadata with JSON object (destructive).",
+    ),
+    suggestions: list[str] = typer.Option(
+        [], "--suggestion", help="Suggestion text. Repeat option to add many."
+    ),
+    auto_reply: Optional[bool] = typer.Option(
+        None,
+        "--auto-reply/--no-auto-reply",
+        help="Set whether agent automatically replies to messages.",
+    ),
+    guardrail: Optional[str] = typer.Option(None, "--guardrail", help="General guardrail text."),
+    escalation_mode: Optional[str] = typer.Option(None, "--escalation-mode"),
+    escalation_wait_time_mode: Optional[str] = typer.Option(
+        None, "--escalation-wait-time-mode"
+    ),
+    response_delay_in_seconds: Optional[int] = typer.Option(
+        None, "--response-delay-seconds"
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False, help="Preview payload without writes."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    normalized_modality = normalize_modality(modality) if modality is not None else None
+    normalized_type = normalize_agent_type(agent_type) if agent_type is not None else None
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="resolve runtime for agent update"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    current_metadata: Optional[dict[str, Any]] = None
+    if metadata_merge_json is not None:
+        try:
+            current_agent = get_agent(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                agent_id=agent_id,
+            )
+        except APIError as exc:
+            typer.echo(render_api_error(exc, action="read current agent before update"), err=True)
+            raise typer.Exit(code=1) from exc
+        raw_metadata = current_agent.get("metadata")
+        current_metadata = raw_metadata if isinstance(raw_metadata, dict) else {}
+    metadata = _resolve_metadata_options(
+        merge_raw=metadata_merge_json,
+        replace_raw=metadata_replace_json,
+        current_metadata=current_metadata,
+    )
+
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name.strip()
+    if normalized_modality is not None:
+        payload["modality"] = normalized_modality
+    if normalized_type is not None:
+        payload["type"] = normalized_type
+    if description is not None:
+        payload["description"] = description
+    if model is not None:
+        payload["model"] = model
+    if metadata is not None:
+        payload["metadata"] = metadata
+    if suggestions:
+        payload["suggestions"] = [item.strip() for item in suggestions if item.strip()]
+    if auto_reply is not None:
+        payload["auto_reply"] = auto_reply
+    if guardrail is not None:
+        payload["guardrail"] = guardrail
+    if escalation_mode is not None:
+        payload["escalation_mode"] = escalation_mode
+    if escalation_wait_time_mode is not None:
+        payload["escalation_wait_time_mode"] = escalation_wait_time_mode
+    if response_delay_in_seconds is not None:
+        payload["response_delay_in_seconds"] = response_delay_in_seconds
+    if not payload:
+        raise typer.BadParameter("No fields provided. Pass at least one update option.")
+
+    show_target(
+        {
+            "base_url": resolved_base_url,
+            "shop_id": resolved_shop_id,
+            "agent_id": agent_id,
+            "fields": ", ".join(sorted(payload.keys())),
+            "dry_run": dry_run,
+        }
+    )
+    if metadata_replace_json is not None and not yes:
+        typer.echo(
+            "Warning: --metadata-replace-json overwrites existing metadata keys."
+        )
+    confirm_or_exit(yes=yes)
+
+    if dry_run:
+        emit_dry_run(
+            payload={"agent_id": agent_id, "payload": payload, "dry_run": True},
+            output_json=output_json,
+        )
+
+    try:
+        updated = update_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update agent"), err=True)
+        if exc.status_code == 404:
+            typer.echo(
+                "Hint: this often means the `agent-id` is wrong for the selected shop. Run `applied-cli agent list` first.",
+                err=True,
+            )
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=updated,
+        fields={"agent_id": updated.get("id")},
+    )
+
+
+@app.command(
+    "setup",
+    help=(
+        "Create or update an agent and optional responses. Example: applied-cli agent setup "
+        "--name Smalls --modality chat --responses-json '[{\"type\":\"qa\",\"question\":\"Shipping?\",\"answer\":\"We ship in US and Canada.\"}]'"
+    ),
+)
+def setup(
+    agent_id: Optional[str] = typer.Option(
+        None,
+        "--agent-id",
+        "--agent",
+        "--id",
+        help="Existing agent UUID. Omit to create a new agent.",
+    ),
+    name: Optional[str] = typer.Option(
+        None, "--name", help="Agent name (required when creating)."
+    ),
+    modality: str = typer.Option("chat", "--modality", help="all/call/sms/email/chat/internal."),
+    agent_type: str = typer.Option("customer_support", "--type", help="Agent type."),
+    description: Optional[str] = typer.Option(None, "--description"),
+    guardrail: Optional[str] = typer.Option(None, "--guardrail"),
+    auto_reply: Optional[bool] = typer.Option(
+        None, "--auto-reply/--no-auto-reply", help="Enable/disable automatic replies."
+    ),
+    escalation_mode: Optional[str] = typer.Option(None, "--escalation-mode"),
+    escalation_wait_time_mode: Optional[str] = typer.Option(
+        None, "--escalation-wait-time-mode"
+    ),
+    response_delay_in_seconds: Optional[int] = typer.Option(
+        None, "--response-delay-seconds"
+    ),
+    add_suggestion: list[str] = typer.Option(
+        [], "--add-suggestion", help="Append suggestion text."
+    ),
+    metadata_merge_json: Optional[str] = typer.Option(
+        None, "--metadata-merge-json", help="Merge JSON object into metadata."
+    ),
+    responses_json: Optional[str] = typer.Option(
+        None,
+        "--responses-json",
+        help="JSON array of response rule objects to upsert.",
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False, help="Preview without writes."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    if agent_id:
+        _validate_uuid(agent_id, field_name="agent-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="resolve runtime for agent setup"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    resolved_agent_id = agent_id
+    normalized_modality = normalize_modality(modality)
+    normalized_type = normalize_agent_type(agent_type)
+    if not resolved_agent_id and not (name and name.strip()):
+        raise typer.BadParameter("`--name` is required when creating a new agent.")
+
+    responses_rows: list[dict[str, Any]] = []
+    if responses_json:
+        try:
+            parsed = json.loads(responses_json)
+        except json.JSONDecodeError as exc:
+            raise typer.BadParameter("responses-json must be valid JSON.") from exc
+        if not isinstance(parsed, list):
+            raise typer.BadParameter("responses-json must decode to a JSON array.")
+        responses_rows = [item for item in parsed if isinstance(item, dict)]
+        if len(responses_rows) != len(parsed):
+            raise typer.BadParameter("Each entry in responses-json must be a JSON object.")
+
+    show_target(
+        {
+            "base_url": resolved_base_url,
+            "shop_id": resolved_shop_id,
+            "agent_id": resolved_agent_id or "(create new)",
+            "responses_upsert_count": len(responses_rows),
+            "dry_run": dry_run,
+        }
+    )
+    confirm_or_exit(yes=yes)
+
+    try:
+        if not resolved_agent_id:
+            create_payload: dict[str, Any] = {
+                "name": str(name).strip(),
+                "modality": normalized_modality,
+                "type": normalized_type,
+            }
+            if description is not None:
+                create_payload["description"] = description
+            if auto_reply is not None:
+                create_payload["auto_reply"] = auto_reply
+            if guardrail is not None:
+                create_payload["guardrail"] = guardrail
+            if escalation_mode is not None:
+                create_payload["escalation_mode"] = escalation_mode
+            if escalation_wait_time_mode is not None:
+                create_payload["escalation_wait_time_mode"] = escalation_wait_time_mode
+            if response_delay_in_seconds is not None:
+                create_payload["response_delay_in_seconds"] = response_delay_in_seconds
+            metadata_payload = _resolve_metadata_options(
+                merge_raw=metadata_merge_json,
+                replace_raw=None,
+                current_metadata={},
+            )
+            if metadata_payload is not None:
+                create_payload["metadata"] = metadata_payload
+            if add_suggestion:
+                create_payload["suggestions"] = [s.strip() for s in add_suggestion if s.strip()]
+            if dry_run:
+                resolved_agent_id = "(planned-create)"
+            else:
+                created = create_agent(
+                    base_url=resolved_base_url,
+                    shop_id=resolved_shop_id,
+                    api_token=resolved_token,
+                    payload=create_payload,
+                )
+                resolved_agent_id = str(created.get("id"))
+        else:
+            update_payload: dict[str, Any] = {}
+            if name is not None:
+                update_payload["name"] = name.strip()
+            if modality is not None:
+                update_payload["modality"] = normalized_modality
+            if agent_type is not None:
+                update_payload["type"] = normalized_type
+            if description is not None:
+                update_payload["description"] = description
+            if auto_reply is not None:
+                update_payload["auto_reply"] = auto_reply
+            if guardrail is not None:
+                update_payload["guardrail"] = guardrail
+            if escalation_mode is not None:
+                update_payload["escalation_mode"] = escalation_mode
+            if escalation_wait_time_mode is not None:
+                update_payload["escalation_wait_time_mode"] = escalation_wait_time_mode
+            if response_delay_in_seconds is not None:
+                update_payload["response_delay_in_seconds"] = response_delay_in_seconds
+            if add_suggestion:
+                current = get_agent(
+                    base_url=resolved_base_url,
+                    shop_id=resolved_shop_id,
+                    api_token=resolved_token,
+                    agent_id=resolved_agent_id,
+                )
+                existing = current.get("suggestions")
+                existing_list = existing if isinstance(existing, list) else []
+                merged = [str(x).strip() for x in existing_list if str(x).strip()]
+                for item in add_suggestion:
+                    norm = item.strip()
+                    if norm and norm not in merged:
+                        merged.append(norm)
+                update_payload["suggestions"] = merged
+            if metadata_merge_json is not None:
+                current = get_agent(
+                    base_url=resolved_base_url,
+                    shop_id=resolved_shop_id,
+                    api_token=resolved_token,
+                    agent_id=resolved_agent_id,
+                )
+                raw_metadata = current.get("metadata")
+                current_metadata = raw_metadata if isinstance(raw_metadata, dict) else {}
+                update_payload["metadata"] = _resolve_metadata_options(
+                    merge_raw=metadata_merge_json,
+                    replace_raw=None,
+                    current_metadata=current_metadata,
+                )
+            if update_payload and not dry_run:
+                update_agent(
+                    base_url=resolved_base_url,
+                    shop_id=resolved_shop_id,
+                    api_token=resolved_token,
+                    agent_id=resolved_agent_id,
+                    payload=update_payload,
+                )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="run agent setup"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    response_summary = {"created": 0, "updated": 0, "unchanged": 0}
+    if responses_rows and resolved_agent_id and resolved_agent_id != "(planned-create)":
+        try:
+            response_summary = _upsert_inline_responses(
+                base_url=resolved_base_url,
+                shop_id=resolved_shop_id,
+                api_token=resolved_token,
+                agent_id=resolved_agent_id,
+                response_rows=responses_rows,
+                dry_run=dry_run,
+            )
+        except (APIError, typer.BadParameter) as exc:
+            if isinstance(exc, APIError):
+                typer.echo(
+                    render_api_error(exc, action="upsert setup responses"), err=True
+                )
+            else:
+                typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1) from exc
+    elif responses_rows and dry_run:
+        response_summary = {"created": len(responses_rows), "updated": 0, "unchanged": 0}
+
+    out = {
+        "agent_id": resolved_agent_id,
+        "responses_created": response_summary["created"],
+        "responses_updated": response_summary["updated"],
+        "responses_unchanged": response_summary["unchanged"],
+        "dry_run": dry_run,
+    }
+    if output_json:
+        typer.echo(json.dumps(out, indent=2, default=str))
+    else:
+        emit_success(
+            output_json=output_json,
+            payload=out,
+            fields={
+                "agent_id": out["agent_id"],
+                "responses_created": out["responses_created"],
+                "responses_updated": out["responses_updated"],
+                "responses_unchanged": out["responses_unchanged"],
+                "dry_run": out["dry_run"],
+            },
+        )
+
+
+@settings_app.command(
+    "escalation",
+    help=(
+        "Update escalation settings. Example: applied-cli agent settings escalation "
+        "--agent-id <uuid> --escalation-mode after_response --response-delay-seconds 30"
+    ),
+)
+def settings_escalation(
+    agent_id: str = typer.Option(
+        ..., "--agent-id", "--agent", "--id", help="Target agent UUID."
+    ),
+    escalation_mode: Optional[str] = typer.Option(None, "--escalation-mode"),
+    escalation_wait_time_mode: Optional[str] = typer.Option(
+        None, "--escalation-wait-time-mode"
+    ),
+    response_delay_in_seconds: Optional[int] = typer.Option(
+        None, "--response-delay-seconds"
+    ),
+    escalation_phone_number: Optional[str] = typer.Option(
+        None, "--escalation-phone-number"
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    output_json: bool = typer.Option(False, "--json"),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        current = get_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="read agent for escalation settings"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    payload: dict[str, Any] = {}
+    if escalation_mode is not None:
+        payload["escalation_mode"] = escalation_mode
+    if escalation_wait_time_mode is not None:
+        payload["escalation_wait_time_mode"] = escalation_wait_time_mode
+    if response_delay_in_seconds is not None:
+        payload["response_delay_in_seconds"] = response_delay_in_seconds
+    if escalation_phone_number is not None:
+        raw_metadata = current.get("metadata")
+        metadata: dict[str, Any] = raw_metadata if isinstance(raw_metadata, dict) else {}
+        payload["metadata"] = _deep_merge_dict(
+            metadata,
+            {"escalation_phone_number": escalation_phone_number},
+        )
+    if not payload:
+        raise typer.BadParameter("No update fields provided.")
+
+    show_target(
+        {
+            "agent_id": agent_id,
+            "fields": ", ".join(sorted(payload.keys())),
+            "dry_run": dry_run,
+        }
+    )
+    confirm_or_exit(yes=yes)
+
+    if dry_run:
+        emit_dry_run(
+            payload={"agent_id": agent_id, "payload": payload, "dry_run": True},
+            output_json=output_json,
+        )
+
+    try:
+        updated = update_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update escalation settings"), err=True)
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=updated,
+        fields={"agent_id": updated.get("id")},
+    )
+
+
+@settings_app.command(
+    "style",
+    help=(
+        "Merge style metadata settings. Example: applied-cli agent settings style "
+        "--agent-id <uuid> --style-json '{\"tone\":\"friendly\"}'"
+    ),
+)
+def settings_style(
+    agent_id: str = typer.Option(
+        ..., "--agent-id", "--agent", "--id", help="Target agent UUID."
+    ),
+    style_json: str = typer.Option(
+        ..., "--style-json", help="JSON object merged into metadata.style."
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    output_json: bool = typer.Option(False, "--json"),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    style_patch = _parse_json_dict(style_json, field_name="style-json")
+    if style_patch is None:
+        raise typer.BadParameter("style-json is required.")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        current = get_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="read agent for style settings"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    raw_metadata = current.get("metadata")
+    metadata: dict[str, Any] = raw_metadata if isinstance(raw_metadata, dict) else {}
+    raw_style = metadata.get("style")
+    style_current: dict[str, Any] = raw_style if isinstance(raw_style, dict) else {}
+    merged_style = _deep_merge_dict(style_current, style_patch)
+    payload = {"metadata": _deep_merge_dict(metadata, {"style": merged_style})}
+
+    show_target(
+        {
+            "agent_id": agent_id,
+            "fields": "metadata.style",
+            "dry_run": dry_run,
+        }
+    )
+    confirm_or_exit(yes=yes)
+    if dry_run:
+        emit_dry_run(
+            payload={"agent_id": agent_id, "payload": payload, "dry_run": True},
+            output_json=output_json,
+        )
+    try:
+        updated = update_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update style settings"), err=True)
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=updated,
+        fields={"agent_id": updated.get("id")},
+    )
+
+
+@settings_app.command(
+    "chatbot",
+    help=(
+        "Update chatbot metadata flags. Example: applied-cli agent settings chatbot "
+        "--agent-id <uuid> --allow-uploads true --hide-chatbot false"
+    ),
+)
+def settings_chatbot(
+    agent_id: str = typer.Option(
+        ..., "--agent-id", "--agent", "--id", help="Target agent UUID."
+    ),
+    allow_uploads: Optional[str] = typer.Option(None, "--allow-uploads"),
+    hide_chatbot: Optional[str] = typer.Option(None, "--hide-chatbot"),
+    prevent_multiple_inbound_webchats: Optional[str] = typer.Option(
+        None, "--prevent-multiple-inbound-webchats"
+    ),
+    should_subscribe_to_chatbot_events: Optional[str] = typer.Option(
+        None, "--should-subscribe-to-chatbot-events"
+    ),
+    hide_upsell: Optional[str] = typer.Option(None, "--hide-upsell"),
+    conversation_hard_close: Optional[str] = typer.Option(None, "--conversation-hard-close"),
+    full_size_blank_completion: Optional[str] = typer.Option(
+        None, "--full-size-blank-completion"
+    ),
+    always_show_suggestions: Optional[str] = typer.Option(
+        None, "--always-show-suggestions"
+    ),
+    feedback_period_in_minutes: Optional[int] = typer.Option(
+        None, "--feedback-period-in-minutes"
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    output_json: bool = typer.Option(False, "--json"),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    bool_updates: dict[str, Optional[bool]] = {
+        "allow_uploads": _parse_optional_bool(allow_uploads, field_name="allow-uploads"),
+        "hide_chatbot": _parse_optional_bool(hide_chatbot, field_name="hide-chatbot"),
+        "prevent_multiple_inbound_webchats": _parse_optional_bool(
+            prevent_multiple_inbound_webchats,
+            field_name="prevent-multiple-inbound-webchats",
+        ),
+        "should_subscribe_to_chatbot_events": _parse_optional_bool(
+            should_subscribe_to_chatbot_events,
+            field_name="should-subscribe-to-chatbot-events",
+        ),
+        "hide_upsell": _parse_optional_bool(hide_upsell, field_name="hide-upsell"),
+        "conversation_hard_close": _parse_optional_bool(
+            conversation_hard_close, field_name="conversation-hard-close"
+        ),
+        "full_size_blank_completion": _parse_optional_bool(
+            full_size_blank_completion, field_name="full-size-blank-completion"
+        ),
+        "always_show_suggestions": _parse_optional_bool(
+            always_show_suggestions, field_name="always-show-suggestions"
+        ),
+    }
+    patch: dict[str, Any] = {k: v for k, v in bool_updates.items() if v is not None}
+    if feedback_period_in_minutes is not None:
+        patch["feedback_period_in_minutes"] = feedback_period_in_minutes
+    if not patch:
+        raise typer.BadParameter("No update fields provided.")
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        current = get_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="read agent for chatbot settings"), err=True)
+        raise typer.Exit(code=1) from exc
+    raw_metadata = current.get("metadata")
+    metadata: dict[str, Any] = raw_metadata if isinstance(raw_metadata, dict) else {}
+    payload = {"metadata": _deep_merge_dict(metadata, patch)}
+
+    show_target(
+        {
+            "agent_id": agent_id,
+            "fields": f"metadata ({', '.join(sorted(patch.keys()))})",
+            "dry_run": dry_run,
+        }
+    )
+    confirm_or_exit(yes=yes)
+    if dry_run:
+        emit_dry_run(
+            payload={"agent_id": agent_id, "payload": payload, "dry_run": True},
+            output_json=output_json,
+        )
+    try:
+        updated = update_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update chatbot settings"), err=True)
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=updated,
+        fields={"agent_id": updated.get("id")},
+    )
+
+
+@settings_app.command(
+    "guidance",
+    help=(
+        "Update guardrail and suggestions. Example: applied-cli agent settings guidance "
+        "--agent-id <uuid> --guardrail 'Do not provide medical advice.'"
+    ),
+)
+def settings_guidance(
+    agent_id: str = typer.Option(
+        ..., "--agent-id", "--agent", "--id", help="Target agent UUID."
+    ),
+    guardrail: Optional[str] = typer.Option(None, "--guardrail"),
+    add_suggestion: list[str] = typer.Option(
+        [], "--add-suggestion", help="Append suggestion text. Repeat option for many."
+    ),
+    replace_suggestions_json: Optional[str] = typer.Option(
+        None, "--replace-suggestions-json", help="JSON string array."
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    output_json: bool = typer.Option(False, "--json"),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    replace_suggestions: Optional[list[str]] = None
+    if replace_suggestions_json is not None:
+        try:
+            parsed = json.loads(replace_suggestions_json)
+        except json.JSONDecodeError as exc:
+            raise typer.BadParameter("replace-suggestions-json must be valid JSON.") from exc
+        if not isinstance(parsed, list) or not all(isinstance(x, str) for x in parsed):
+            raise typer.BadParameter(
+                "replace-suggestions-json must decode to a JSON string array."
+            )
+        replace_suggestions = [x.strip() for x in parsed if x.strip()]
+    if guardrail is None and not add_suggestion and replace_suggestions is None:
+        raise typer.BadParameter("No update fields provided.")
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+        current = get_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="read agent for guidance settings"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    payload: dict[str, Any] = {}
+    if guardrail is not None:
+        payload["guardrail"] = guardrail
+    if replace_suggestions is not None:
+        payload["suggestions"] = replace_suggestions
+    elif add_suggestion:
+        raw_existing = current.get("suggestions")
+        existing: list[Any] = raw_existing if isinstance(raw_existing, list) else []
+        merged = [str(x).strip() for x in existing if str(x).strip()]
+        for item in add_suggestion:
+            normalized = item.strip()
+            if normalized and normalized not in merged:
+                merged.append(normalized)
+        payload["suggestions"] = merged
+
+    show_target(
+        {
+            "agent_id": agent_id,
+            "fields": ", ".join(sorted(payload.keys())),
+            "dry_run": dry_run,
+        }
+    )
+    confirm_or_exit(yes=yes)
+    if dry_run:
+        emit_dry_run(
+            payload={"agent_id": agent_id, "payload": payload, "dry_run": True},
+            output_json=output_json,
+        )
+    try:
+        updated = update_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update guidance settings"), err=True)
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=updated,
+        fields={"agent_id": updated.get("id")},
+    )
+
+
+@settings_app.command(
+    "reply",
+    help=(
+        "Toggle auto-reply. Example: applied-cli agent settings reply "
+        "--agent-id <uuid> --auto-reply"
+    ),
+)
+def settings_reply(
+    agent_id: str = typer.Option(
+        ..., "--agent-id", "--agent", "--id", help="Target agent UUID."
+    ),
+    auto_reply: Optional[bool] = typer.Option(
+        None,
+        "--auto-reply/--no-auto-reply",
+        help="Whether agent automatically replies to incoming messages.",
+    ),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+    dry_run: bool = typer.Option(False),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    output_json: bool = typer.Option(False, "--json"),
+) -> None:
+    _validate_uuid(agent_id, field_name="agent-id")
+    if auto_reply is None:
+        raise typer.BadParameter("Provide either --auto-reply or --no-auto-reply.")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url, shop_id=shop_id, api_token=api_token
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="resolve runtime for reply settings"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    payload: dict[str, Any] = {"auto_reply": auto_reply}
+    show_target(
+        {
+            "agent_id": agent_id,
+            "fields": f"auto_reply={auto_reply}",
+            "dry_run": dry_run,
+        }
+    )
+    confirm_or_exit(yes=yes)
+
+    if dry_run:
+        emit_dry_run(
+            payload={"agent_id": agent_id, "payload": payload, "dry_run": True},
+            output_json=output_json,
+        )
+
+    try:
+        updated = update_agent(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            agent_id=agent_id,
+            payload=payload,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="update reply settings"), err=True)
+        raise typer.Exit(code=1) from exc
+    emit_success(
+        output_json=output_json,
+        payload=updated,
+        fields={"agent_id": updated.get("id")},
+    )
+
+
+app.add_typer(settings_app, name="settings")