agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/jobs/insights/format.py

@@ -0,0 +1,65 @@
+"""Presentation helpers for insights jobs (port of operations/jobs/insights/format.ts)."""
+
+from typing import Any
+
+import typer
+
+from agentcore.operations.jobs.batch_evaluation.format import summary_line
+from agentcore.operations.jobs.shared.format import format_job_date
+
+
+def print_insights_history(records: list[dict[str, Any]]) -> None:
+    if not records:
+        typer.echo("No insights jobs found. Run `agentcore run insights` to create one.")
+        return
+    typer.echo(f"\n{'Date'.ljust(22)} {'Status'.ljust(22)} {'Insights'.ljust(28)} ID")
+    typer.echo("─" * 100)
+    for r in records:
+        typer.echo(
+            f"{format_job_date(r.get('createdAt')).ljust(22)} {str(r.get('status')).ljust(22)} "
+            f"{', '.join(r.get('insights') or []).ljust(28)} {r['id']}"
+        )
+    typer.echo("")
+
+
+def print_insights_detail(record: dict[str, Any]) -> None:
+    typer.echo(f"\nInsights job: {record['id']}")
+    typer.echo(f"Name: {record.get('name')}")
+    typer.echo(f"Status: {record.get('status')}")
+    typer.echo(f"Agent: {record.get('agent')}")
+    typer.echo(f"Insights: {', '.join(record.get('insights') or [])}")
+    if record.get("evaluators"):
+        typer.echo(f"Evaluators: {', '.join(record['evaluators'])}")
+    typer.echo(f"Started: {format_job_date(record.get('createdAt'))}")
+    if record.get("completedAt"):
+        typer.echo(f"Completed: {format_job_date(record['completedAt'])}")
+
+    categories = (record.get("failureAnalysisResult") or {}).get("failureCategories")
+    if categories:
+        typer.echo("\nFailure Analysis:")
+        for cat in categories:
+            typer.echo(f"\n  Category: {cat.get('failureCategoryName') or 'Unknown'}")
+            if cat.get("failureCategoryDescription"):
+                typer.echo(f"  Description: {cat['failureCategoryDescription']}")
+            if cat.get("categoryGroupName"):
+                typer.echo(f"  Group: {cat['categoryGroupName']}")
+            for rc in cat.get("rootCauses") or []:
+                typer.echo(f"    Root cause: {rc.get('rootCauseCategory') or 'Unknown'}")
+                if rc.get("rootCauseDescription"):
+                    typer.echo(f"      {rc['rootCauseDescription']}")
+                if rc.get("recommendation"):
+                    typer.echo(f"      Recommendation: {rc['recommendation']}")
+                if rc.get("relatedSessions"):
+                    sessions = ", ".join(str(s.get("sessionId") or "") for s in rc["relatedSessions"])
+                    typer.echo(f"      Sessions: {sessions}")
+    else:
+        summaries = (record.get("evaluationResults") or {}).get("evaluatorSummaries")
+        if summaries:
+            typer.echo("\nEvaluation Results:")
+            for s in summaries:
+                typer.echo(summary_line(s))
+        else:
+            typer.echo("\nResults not yet available.")
+    if record.get("logFilePath"):
+        typer.echo(f"\nLog: {record['logFilePath']}")
+    typer.echo("")

agentcore/operations/jobs/insights/handler.py

@@ -0,0 +1,178 @@
+"""Insights job handler (port of operations/jobs/insights/handler.ts). Insights jobs are not stoppable."""
+
+import re
+import time
+from typing import Any
+
+from agentcore.aws import agentcore_batch_evaluation as api
+from agentcore.aws.cloudwatch import resolve_endpoint_name, runtime_log_group
+from agentcore.lib import ConfigIO, JobNotFoundError, ResourceNotFoundError, ValidationError
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.lib.utils.json_format import to_json_string
+from agentcore.operations.jobs.batch_evaluation.build_source import resolve_batch_evaluator_ids
+from agentcore.operations.jobs.batch_evaluation.handler import new_logger
+from agentcore.operations.jobs.shared.constants import NOT_FOUND_STATUS
+from agentcore.operations.jobs.shared.format import iso_from_ms, iso_now
+from agentcore.operations.jobs.shared.region import region_of, resolve_job_region
+from agentcore.operations.jobs.shared.resolve_agent_state import deployed_dict, resolve_agent_state
+from agentcore.operations.jobs.shared.storage import drop_undefined
+
+NAME_PATTERN = re.compile(r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$")
+
+
+def validate_lookback_days(lookback_days: Any) -> None:
+    if not isinstance(lookback_days, int) or isinstance(lookback_days, bool) or lookback_days < 1:
+        raise ValidationError("--lookback-days must be a positive integer (at least 1).")
+
+
+def resolve_insights_name(name: str | None, project_name: str, agent: str) -> str:
+    if name:
+        if not NAME_PATTERN.match(name):
+            raise ValidationError(
+                f'Job name "{name}" is invalid. Must begin with a letter and contain only alphanumeric characters '
+                "and underscores (max 48 chars)."
+            )
+        return name
+    return re.sub(r"[^a-zA-Z0-9_]", "_", f"{project_name}_{agent}_insights_{int(time.time() * 1000)}")[:48]
+
+
+def build_filter_config(
+    session_ids: list[str] | None, lookback_days: int | None, start_time: str | None, end_time: str | None
+) -> dict[str, Any] | None:
+    effective = list(dict.fromkeys(session_ids or []))
+    if effective:
+        return {"sessionIds": effective}
+    if start_time or end_time:
+        return {"timeRange": drop_undefined({"startTime": start_time, "endTime": end_time})}
+    if lookback_days is not None:
+        validate_lookback_days(lookback_days)
+        return {
+            "timeRange": {
+                "startTime": iso_from_ms(time.time() * 1000 - lookback_days * 24 * 60 * 60 * 1000),
+                "endTime": iso_now(),
+            }
+        }
+    return None
+
+
+def create(opts: dict[str, Any], config_io: ConfigIO) -> Ok | Err:
+    logger = new_logger("insights")
+    try:
+        if logger:
+            logger.start_step("Load project config")
+        project = to_jsonable(config_io.read_project_spec())
+        deployed_state = deployed_dict(config_io.read_deployed_state())
+        aws_targets = config_io.resolve_aws_deployment_targets()
+        region = resolve_job_region(opts.get("region"), aws_targets)
+        if logger:
+            logger.end_step("success")
+
+        runtimes = project.get("runtimes") or []
+        agent_name = opts.get("agent") or (runtimes[0]["name"] if runtimes else "")
+        online_arn = opts.get("onlineEvalConfigArn")
+
+        if online_arn:
+            if logger:
+                logger.start_step("Use online eval config source")
+            data_source: dict[str, Any] = {"onlineEvaluationConfigSource": {"onlineEvaluationConfigArn": online_arn}}
+            if logger:
+                logger.end_step("success")
+        else:
+            if logger:
+                logger.start_step("Resolve agent")
+            agent_state = resolve_agent_state(deployed_state, agent_name)
+            if not agent_state:
+                err = ResourceNotFoundError(f'Agent "{agent_name}" not deployed. Run `agentcore deploy` first.')
+                if logger:
+                    logger.end_step("error", err.message)
+                    logger.finalize(False)
+                return Err(err)
+            service_name = f"{project['name']}_{agent_name}.{resolve_endpoint_name(opts.get('endpoint'))}"
+            log_group = runtime_log_group(agent_state["runtimeId"], opts.get("endpoint"))
+            if logger:
+                logger.log(f"Service name: {service_name}")
+                logger.log(f"Log group: {log_group}")
+                logger.end_step("success")
+            filter_config = build_filter_config(
+                opts.get("sessionIds"), opts.get("lookbackDays"), opts.get("startTime"), opts.get("endTime")
+            )
+            cw: dict[str, Any] = {"serviceNames": [service_name], "logGroupNames": [log_group]}
+            if filter_config:
+                cw["filterConfig"] = filter_config
+            data_source = {"cloudWatchLogs": cw}
+
+        eval_name = resolve_insights_name(opts.get("name"), project["name"], agent_name)
+        resolved = (
+            resolve_batch_evaluator_ids(deployed_state, agent_name, opts["evaluators"])
+            if opts.get("evaluators")
+            else None
+        )
+
+        if logger:
+            logger.start_step("Start insights job")
+        on_progress = opts.get("onProgress")
+        if on_progress:
+            on_progress("starting", f'Starting insights job "{eval_name}"...')
+        start = api.start_batch_evaluation(
+            region=region,
+            name=eval_name,
+            insights=None if online_arn else [{"insightId": i} for i in opts.get("insights") or []],
+            evaluators=[{"evaluatorId": i} for i in resolved] if (not online_arn and resolved) else None,
+            data_source_config=data_source,  # type: ignore[arg-type]
+            client_token=api.generate_client_token(),
+            kms_key_arn=opts.get("kmsKeyArn"),
+        )
+        if logger:
+            logger.log(f"Response: {to_json_string(start)}")
+            logger.end_step("success")
+        if on_progress:
+            on_progress("started", f"Insights job created: {start['batchEvaluationId']} ({start['status']})")
+        if logger:
+            logger.finalize(True)
+
+        record = {
+            "type": "insights",
+            "id": start["batchEvaluationId"],
+            "arn": start["batchEvaluationArn"],
+            "status": start["status"],
+            "createdAt": start.get("createdAt") or iso_now(),
+            "agent": agent_name,
+            "logFilePath": logger.log_file_path if logger else None,
+            "name": eval_name,
+            "insights": opts.get("insights") or [],
+            "evaluators": resolved,
+        }
+        return Ok(drop_undefined(record))
+    except Exception as exc:  # noqa: BLE001
+        if logger:
+            logger.finalize(False)
+        return Err(to_error(exc))
+
+
+def refresh(record: dict[str, Any]) -> Ok | Err:
+    try:
+        response = api.get_batch_evaluation(region=region_of(record["arn"]), batch_evaluation_id=record["id"])
+    except JobNotFoundError:
+        return Ok({**record, "status": NOT_FOUND_STATUS})
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))
+    updated = {
+        **record,
+        "status": response["status"],
+        "completedAt": response.get("updatedAt") or record.get("completedAt"),
+        "evaluationResults": response.get("evaluationResults") or record.get("evaluationResults"),
+        "failureAnalysisResult": response.get("failureAnalysisResult") or record.get("failureAnalysisResult"),
+    }
+    return Ok(drop_undefined(updated))
+
+
+def archive(record: dict[str, Any]) -> Ok | Err:
+    try:
+        api.delete_batch_evaluation(region=region_of(record["arn"]), batch_evaluation_id=record["id"])
+        return Ok(None)
+    except JobNotFoundError:
+        return Ok(None)
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))

agentcore/operations/jobs/recommendation/apply_to_bundle.py

@@ -0,0 +1,76 @@
+"""Sync agentcore.json after the server applies a recommendation to a config bundle
+(port of operations/jobs/recommendation/apply-to-bundle.ts)."""
+
+import re
+from typing import Any
+
+from agentcore.aws import agentcore_config_bundles as bundles_api
+from agentcore.lib import ConfigIO, ResourceNotFoundError
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.operations.jobs.shared.resolve_agent_state import deployed_dict
+
+
+def _bundle_id_from_arn(arn: str) -> str | None:
+    m = re.search(r"configuration-bundle/(.+)$", arn)
+    return m.group(1) if m else None
+
+
+def apply_recommendation_to_bundle(
+    *,
+    result: dict[str, Any],
+    region: str,
+    bundle_name: str | None = None,
+    bundle_arn: str | None = None,
+    config_io: ConfigIO | None = None,
+) -> Ok | Err:
+    """Ok({"newVersionId": ...}) after syncing local components to the new bundle version."""
+    config_io = config_io or ConfigIO()
+    result_bundle = (result.get("systemPromptRecommendationResult") or {}).get("configurationBundle") or (
+        result.get("toolDescriptionRecommendationResult") or {}
+    ).get("configurationBundle")
+    if not result_bundle:
+        return Err(
+            Exception(
+                "Recommendation result does not contain a new config bundle version. The server may not have "
+                "applied the recommendation to the bundle."
+            )
+        )
+    bundle_id = _bundle_id_from_arn(result_bundle["bundleArn"])
+    if not bundle_id:
+        return Err(Exception(f"Could not extract bundle ID from ARN: {result_bundle['bundleArn']}"))
+
+    new_version = bundles_api.get_configuration_bundle_version(
+        region=region, bundle_id=bundle_id, version_id=result_bundle["versionId"]
+    )
+    spec = to_jsonable(config_io.read_project_spec())
+    deployed_state = deployed_dict(config_io.read_deployed_state())
+
+    name = bundle_name
+    if not name and bundle_arn:
+        for target in (deployed_state.get("targets") or {}).values():
+            for n, state in (((target or {}).get("resources") or {}).get("configBundles") or {}).items():
+                if state.get("bundleArn") == bundle_arn:
+                    name = n
+                    break
+            if name:
+                break
+
+    identifier = name or bundle_arn or "unknown"
+    bundle = next((b for b in spec.get("configBundles") or [] if b.get("name") == name), None) if name else None
+    if not bundle:
+        return Err(ResourceNotFoundError(f'Config bundle "{identifier}" not found in agentcore.json.'))
+
+    bundle["components"] = new_version.get("components")
+    commit_message = (new_version.get("lineageMetadata") or {}).get("commitMessage")
+    if commit_message:
+        bundle["commitMessage"] = commit_message
+    config_io.write_project_spec(spec)
+
+    for target in (deployed_state.get("targets") or {}).values():
+        state = (((target or {}).get("resources") or {}).get("configBundles") or {}).get(identifier)
+        if state:
+            state["versionId"] = result_bundle["versionId"]
+            break
+    config_io.write_deployed_state(deployed_state)
+    return Ok({"newVersionId": result_bundle["versionId"]})

agentcore/operations/jobs/recommendation/build_config.py

@@ -0,0 +1,271 @@
+"""Recommendation start-time pipeline (port of operations/jobs/recommendation/build-config.ts).
+
+Evaluator name -> ARN resolution, account-id extraction, config-bundle JSONPath component
+resolution, failure extraction, and the recommendationConfig builder (incl. the span fetch).
+"""
+
+import json
+import re
+import time
+from collections.abc import Callable
+from typing import Any
+
+from agentcore.aws.cloudwatch import runtime_log_group
+from agentcore.aws.partition import arn_prefix
+from agentcore.lib import ValidationError
+from agentcore.operations.jobs.recommendation import fetch_session_spans as _spans
+from agentcore.operations.jobs.shared.constants import MAX_INLINE_SPANS, MAX_TOOL_NAME_LENGTH, TOOL_NAME_REGEX
+from agentcore.operations.jobs.shared.format import iso_from_ms, iso_now
+from agentcore.operations.jobs.shared.resolve_agent_state import iter_target_resources
+
+
+def resolve_evaluator_id(deployed_state: dict[str, Any], evaluator: str, region: str) -> str | None:
+    """ARN passthrough, Builtin.* expansion to a full ARN, or deployed custom-evaluator lookup."""
+    if evaluator.startswith("arn:"):
+        return evaluator
+    if evaluator.startswith("Builtin."):
+        return f"{arn_prefix(region)}:bedrock-agentcore:::evaluator/{evaluator}"
+    for resources in iter_target_resources(deployed_state):
+        state = (resources.get("evaluators") or {}).get(evaluator)
+        if state:
+            return state.get("evaluatorArn")
+    return None
+
+
+def extract_account_id_from_arn(arn: str) -> str:
+    parts = arn.split(":")
+    return parts[4] if len(parts) > 4 and re.fullmatch(r"\d{12}", parts[4]) else "*"
+
+
+def resolve_component_key_for_json_path(key: str, deployed_state: dict[str, Any]) -> str:
+    """Resolve ``{{runtime:...}}`` / ``{{gateway:...}}`` component keys to deployed ARNs."""
+    if key.startswith("arn:"):
+        return key
+    rt = re.fullmatch(r"\{\{runtime:(.+)\}\}", key)
+    if rt:
+        for resources in iter_target_resources(deployed_state):
+            runtime = (resources.get("runtimes") or {}).get(rt.group(1))
+            if runtime:
+                return runtime["runtimeArn"]
+    gw = re.fullmatch(r"\{\{gateway:(.+)\}\}", key)
+    if gw:
+        for resources in iter_target_resources(deployed_state):
+            http_gw = (resources.get("gateways") or {}).get(gw.group(1))
+            if http_gw:
+                return http_gw["gatewayArn"]
+            mcp_gw = (((resources.get("mcp") or {}).get("gateways")) or {}).get(gw.group(1))
+            if mcp_gw:
+                return mcp_gw["gatewayArn"]
+    return key
+
+
+def resolve_bundle_version_id(bundle_arn: str, version_ref: str, deployed_state: dict[str, Any]) -> str | None:
+    """Expand 'LATEST' to the deployed versionId; explicit versions are returned verbatim."""
+    if version_ref != "LATEST":
+        return version_ref
+    for resources in iter_target_resources(deployed_state):
+        for bundle in (resources.get("configBundles") or {}).values():
+            if bundle.get("bundleArn") == bundle_arn and bundle.get("versionId"):
+                return bundle["versionId"]
+    return None
+
+
+def extract_failure_details(status_reasons: list[str] | None, recommendation_result: dict | None) -> str | None:
+    parts: list[str] = []
+    if status_reasons:
+        parts.append("; ".join(status_reasons))
+    if recommendation_result:
+        source = recommendation_result.get("systemPromptRecommendationResult") or recommendation_result.get(
+            "toolDescriptionRecommendationResult"
+        )
+        if source:
+            if source.get("errorCode"):
+                parts.append(f"[{source['errorCode']}]")
+            if source.get("errorMessage"):
+                parts.append(source["errorMessage"])
+    return " ".join(parts) if parts else None
+
+
+def _days_ago_iso(days: float) -> str:
+    return iso_from_ms(time.time() * 1000 - days * 24 * 60 * 60 * 1000)
+
+
+def build_recommendation_config(
+    *,
+    type: str,
+    input_source: str,
+    trace_source: str,
+    runtime_id: str,
+    account_id: str,
+    region: str,
+    evaluator_ids: list[str],
+    inline_content: str | None = None,
+    bundle_arn: str | None = None,
+    bundle_version: str | None = None,
+    system_prompt_json_path: str | None = None,
+    tool_desc_json_paths: list[dict[str, str]] | None = None,
+    tools: list[str] | None = None,
+    lookback_days: int | None = None,
+    session_ids: list[str] | None = None,
+    spans_file: str | None = None,
+    from_insights: str | None = None,
+    batch_evaluation_arn: str | None = None,
+    online_evaluation_arn: str | None = None,
+    on_progress: Callable[[str, str], None] | None = None,
+    logger: Any = None,
+) -> dict[str, Any]:
+    """Build the recommendationConfig request body (may fetch spans for 'sessions')."""
+    progress = on_progress or (lambda _s, _m: None)
+    if trace_source == "batch-evaluation":
+        if batch_evaluation_arn:
+            batch_eval_arn = batch_evaluation_arn
+        elif from_insights:
+            from agentcore.operations.jobs.shared.storage import load_record
+
+            record = load_record("insights", from_insights)
+            if not record:
+                raise Exception(f'Insights run "{from_insights}" not found.')
+            if record.get("status") not in ("COMPLETED", "COMPLETED_WITH_ERRORS"):
+                raise Exception(
+                    f'Insights run "{from_insights}" has status {record.get("status")}. '
+                    "Only COMPLETED runs can be used as recommendation source."
+                )
+            batch_eval_arn = record["arn"]
+        else:
+            raise Exception(
+                "Either --from-insights or --batch-evaluation-arn is required for batch-evaluation trace source."
+            )
+        agent_traces: dict[str, Any] = {"batchEvaluation": {"batchEvaluationArn": batch_eval_arn}}
+    elif trace_source == "online-evaluation":
+        if not online_evaluation_arn:
+            raise Exception("--online-evaluation-arn is required for online-evaluation trace source.")
+        days = lookback_days if lookback_days is not None else 7
+        agent_traces = {
+            "onlineEvaluation": {
+                "onlineEvaluationConfigArn": online_evaluation_arn,
+                "startTime": _days_ago_iso(days),
+                "endTime": iso_now(),
+            }
+        }
+    elif trace_source == "spans-file" and spans_file:
+        with open(spans_file, encoding="utf-8") as fh:
+            session_spans = json.load(fh)
+        spans_list = session_spans if isinstance(session_spans, list) else [session_spans]
+        if len(spans_list) > MAX_INLINE_SPANS:
+            raise ValidationError(
+                f"Spans file contains {len(spans_list)} spans, which exceeds the maximum of {MAX_INLINE_SPANS}. "
+                "Reduce the number of spans or use CloudWatch-based trace collection instead."
+            )
+        agent_traces = {"sessionSpans": spans_list}
+    elif trace_source == "sessions" and session_ids:
+        progress("fetching-spans", "Fetching session spans from CloudWatch...")
+        if logger:
+            logger.log(
+                "Auto-fetching spans for selected sessions (CloudWatch config does not support session ID filtering)"
+            )
+        all_spans: list[Any] = []
+
+        def on_span_progress(msg: str) -> None:
+            if logger:
+                logger.log(msg)
+            progress("fetching-spans", msg)
+
+        for session_id in session_ids:
+            result = _spans.fetch_session_spans(
+                region=region,
+                runtime_id=runtime_id,
+                session_id=session_id,
+                lookback_days=lookback_days if lookback_days is not None else 7,
+                on_progress=on_span_progress,
+            )
+            all_spans.extend(result["spans"])
+        if not all_spans:
+            raise Exception(
+                "No spans found for the specified session(s). Ensure the agent has been invoked and traces have "
+                "propagated to CloudWatch (may take 5-10 minutes)."
+            )
+        if len(all_spans) > MAX_INLINE_SPANS:
+            raise ValidationError(
+                f"Fetched {len(all_spans)} spans across the specified sessions, which exceeds the maximum of "
+                f"{MAX_INLINE_SPANS}. Reduce the number of sessions or use CloudWatch-based trace collection instead."
+            )
+        if logger:
+            logger.log(f"Total spans fetched: {len(all_spans)}")
+        progress("fetching-spans", f"Fetched {len(all_spans)} spans")
+        agent_traces = {"sessionSpans": all_spans}
+    else:
+        prefix = f"{arn_prefix(region)}:logs:{region}:{account_id}:log-group:"
+        service_name = re.sub(r"-[^-]+$", ".DEFAULT", runtime_id, count=1)
+        days = lookback_days if lookback_days is not None else 7
+        agent_traces = {
+            "cloudwatchLogs": {
+                "logGroupArns": [f"{prefix}{runtime_log_group(runtime_id)}", f"{prefix}aws/spans"],
+                "serviceNames": [service_name],
+                "startTime": _days_ago_iso(days),
+                "endTime": iso_now(),
+            }
+        }
+
+    evaluation_config = {"evaluators": [{"evaluatorArn": evaluator_ids[0]}]} if evaluator_ids else None
+
+    if input_source == "config-bundle" and bundle_arn and not bundle_version:
+        raise Exception("Config bundle version is required. Provide --bundle-version or deploy the bundle first.")
+    if input_source == "config-bundle" and bundle_arn:
+        if type == "SYSTEM_PROMPT_RECOMMENDATION" and not system_prompt_json_path:
+            raise Exception(
+                "Config bundle requires --system-prompt-json-path to locate the system prompt field.\n"
+                "Use the field name (e.g. --system-prompt-json-path 'systemPrompt') and it will be resolved from "
+                "agentcore.json.\n"
+                "Or provide the full JSONPath (e.g. '$.ARN.configuration.systemPrompt')."
+            )
+        if type == "TOOL_DESCRIPTION_RECOMMENDATION" and not tool_desc_json_paths:
+            raise Exception(
+                "Config bundle requires --tool-desc-json-path to locate tool description fields.\n"
+                "Example: --tool-desc-json-path 'toolName:$.ARN.configuration.toolDescription'"
+            )
+
+    if type == "SYSTEM_PROMPT_RECOMMENDATION":
+        if input_source == "config-bundle" and bundle_arn:
+            bundle_ref: dict[str, Any] = {"bundleArn": bundle_arn, "versionId": bundle_version}
+            if system_prompt_json_path is not None:
+                bundle_ref["systemPromptJsonPath"] = system_prompt_json_path
+            system_prompt: dict[str, Any] = {"configurationBundle": bundle_ref}
+        else:
+            system_prompt = {"text": inline_content or ""}
+        config: dict[str, Any] = {"systemPrompt": system_prompt, "agentTraces": agent_traces}
+        if evaluation_config:
+            config["evaluationConfig"] = evaluation_config
+        return {"systemPromptRecommendationConfig": config}
+
+    if input_source == "config-bundle" and bundle_arn and tool_desc_json_paths:
+        return {
+            "toolDescriptionRecommendationConfig": {
+                "toolDescription": {
+                    "configurationBundle": {
+                        "bundleArn": bundle_arn,
+                        "versionId": bundle_version,
+                        "tools": tool_desc_json_paths,
+                    }
+                },
+                "agentTraces": agent_traces,
+            }
+        }
+
+    tool_entries = []
+    for t in tools or []:
+        colon = t.find(":")
+        tool_name = t[:colon] if colon > 0 else t
+        if not TOOL_NAME_REGEX.match(tool_name) or len(tool_name) > MAX_TOOL_NAME_LENGTH:
+            raise ValidationError(
+                f'Tool name "{tool_name}" is invalid. Must contain only alphanumeric characters, underscores, '
+                f"hyphens, or dots (max {MAX_TOOL_NAME_LENGTH} chars)."
+            )
+        text = t[colon + 1 :] if colon > 0 else (inline_content or "")
+        tool_entries.append({"toolName": tool_name, "toolDescription": {"text": text}})
+
+    return {
+        "toolDescriptionRecommendationConfig": {
+            "toolDescription": {"toolDescriptionText": {"tools": tool_entries}},
+            "agentTraces": agent_traces,
+        }
+    }