agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/add/auth_options.py

@@ -0,0 +1,154 @@
+"""JWT authorizer flag validation (port of src/cli/commands/add/auth-options.ts).
+
+``options`` is a dict keyed by upstream option names (discoveryUrl, allowedAudience, ...).
+"""
+
+from typing import Any
+from urllib.parse import urlsplit
+
+from agentcore.cli.commands.add._common import ValidationResult, first_issue, js_url_ok, parse_json
+from agentcore.schema import CustomClaimValidation, PrivateEndpoint, PrivateEndpointOverride
+
+OIDC_WELL_KNOWN_SUFFIX = "/.well-known/openid-configuration"
+
+
+def _s(options: dict[str, Any], key: str) -> str:
+    value = options.get(key)
+    return value.strip() if isinstance(value, str) else ""
+
+
+def validate_jwt_authorizer_options(options: dict[str, Any]) -> ValidationResult:
+    discovery_url = options.get("discoveryUrl")
+    if not discovery_url:
+        return ValidationResult(False, "--discovery-url is required for CUSTOM_JWT authorizer")
+    if not js_url_ok(discovery_url):
+        return ValidationResult(False, "Discovery URL must be a valid URL")
+    if urlsplit(discovery_url).scheme.lower() != "https":
+        return ValidationResult(False, "Discovery URL must use HTTPS")
+    if not discovery_url.endswith(OIDC_WELL_KNOWN_SUFFIX):
+        return ValidationResult(False, f"Discovery URL must end with {OIDC_WELL_KNOWN_SUFFIX}")
+
+    custom_claims = options.get("customClaims")
+    if custom_claims:
+        ok, parsed = parse_json(custom_claims)
+        if not ok:
+            return ValidationResult(False, "--custom-claims must be valid JSON")
+        if not isinstance(parsed, list) or len(parsed) == 0:
+            return ValidationResult(False, "--custom-claims must be a non-empty JSON array")
+        for i, entry in enumerate(parsed):
+            issue = first_issue(CustomClaimValidation, entry)
+            if issue:
+                return ValidationResult(False, f"Invalid custom claim at index {i}: {issue}")
+
+    if not any(_s(options, k) for k in ("allowedAudience", "allowedClients", "allowedScopes", "customClaims")):
+        return ValidationResult(
+            False,
+            "At least one of --allowed-audience, --allowed-clients, --allowed-scopes, or --custom-claims must be "
+            "provided for CUSTOM_JWT authorizer",
+        )
+
+    if bool(options.get("clientId")) != bool(options.get("clientSecret")):
+        return ValidationResult(False, "Both --client-id and --client-secret must be provided together")
+
+    return _validate_private_endpoint_options(options)
+
+
+def _split(value: str) -> list[str]:
+    return [s.strip() for s in value.split(",")]
+
+
+def _validate_private_endpoint_options(options: dict[str, Any]) -> ValidationResult:
+    has_lattice = bool(_s(options, "privateEndpointLatticeArn"))
+    has_vpc = bool(_s(options, "privateEndpointVpcId"))
+
+    if has_lattice and has_vpc:
+        return ValidationResult(
+            False,
+            "--private-endpoint-lattice-arn and --private-endpoint-vpc-id are mutually exclusive (a private endpoint "
+            "is one of VPC Lattice or a managed VPC endpoint)",
+        )
+    vpc_sub_flags = (
+        "privateEndpointSubnets",
+        "privateEndpointIpType",
+        "privateEndpointSecurityGroups",
+        "privateEndpointRoutingDomain",
+        "privateEndpointTags",
+    )
+    if not has_vpc and any(_s(options, k) for k in vpc_sub_flags):
+        return ValidationResult(False, "--private-endpoint-* VPC flags require --private-endpoint-vpc-id")
+
+    if has_lattice:
+        issue = first_issue(
+            PrivateEndpoint,
+            {"selfManagedLatticeResource": {"resourceConfigurationIdentifier": options["privateEndpointLatticeArn"]}},
+        )
+        if issue:
+            return ValidationResult(False, f"Invalid --private-endpoint-lattice-arn: {issue}")
+
+    if has_vpc:
+        if not _s(options, "privateEndpointSubnets"):
+            return ValidationResult(False, "--private-endpoint-subnets is required with --private-endpoint-vpc-id")
+        if not _s(options, "privateEndpointIpType"):
+            return ValidationResult(
+                False, "--private-endpoint-ip-type (IPV4 or IPV6) is required with --private-endpoint-vpc-id"
+            )
+        tags: Any = None
+        has_tags = False
+        if options.get("privateEndpointTags"):
+            ok, tags = parse_json(options["privateEndpointTags"])
+            if not ok:
+                return ValidationResult(False, "--private-endpoint-tags must be valid JSON")
+            has_tags = True
+        resource: dict[str, Any] = {
+            "vpcIdentifier": options["privateEndpointVpcId"],
+            "subnetIds": _split(options["privateEndpointSubnets"]),
+            "endpointIpAddressType": options["privateEndpointIpType"],
+        }
+        if options.get("privateEndpointSecurityGroups"):
+            resource["securityGroupIds"] = _split(options["privateEndpointSecurityGroups"])
+        if options.get("privateEndpointRoutingDomain"):
+            resource["routingDomain"] = options["privateEndpointRoutingDomain"]
+        if has_tags:
+            resource["tags"] = tags
+        issue = first_issue(PrivateEndpoint, {"managedVpcResource": resource})
+        if issue:
+            return ValidationResult(False, f"Invalid managed-VPC private endpoint: {issue}")
+
+    overrides_raw = options.get("privateEndpointOverrides")
+    if overrides_raw:
+        ok, parsed = parse_json(overrides_raw)
+        if not ok:
+            return ValidationResult(False, "--private-endpoint-overrides must be valid JSON")
+        if not isinstance(parsed, list):
+            return ValidationResult(False, "--private-endpoint-overrides must be a JSON array")
+        if len(parsed) > 5:
+            return ValidationResult(False, "--private-endpoint-overrides allows at most 5 entries")
+        if not has_lattice and not has_vpc:
+            return ValidationResult(
+                False,
+                "--private-endpoint-overrides requires a base private endpoint (--private-endpoint-lattice-arn or "
+                "--private-endpoint-vpc-id)",
+            )
+        base_arm = "selfManagedLatticeResource" if has_lattice else "managedVpcResource"
+        seen: set[str] = set()
+        for i, entry in enumerate(parsed):
+            issue = first_issue(PrivateEndpointOverride, entry)
+            if issue:
+                return ValidationResult(False, f"Invalid private-endpoint override at index {i}: {issue}")
+            override = PrivateEndpointOverride.model_validate(entry)
+            arm = (
+                "selfManagedLatticeResource"
+                if override.private_endpoint.self_managed_lattice_resource
+                else "managedVpcResource"
+            )
+            if arm != base_arm:
+                kind = "VPC Lattice" if base_arm == "selfManagedLatticeResource" else "managed VPC"
+                return ValidationResult(
+                    False,
+                    f"Private-endpoint override at index {i} must be the same kind as the base endpoint (all {kind})",
+                )
+            if override.domain in seen:
+                return ValidationResult(False, f"Duplicate private-endpoint override domain: {override.domain}")
+            seen.add(override.domain)
+
+    return ValidationResult(True)

agentcore/cli/commands/add/skill_action.py

@@ -0,0 +1,105 @@
+"""`add skill` logic (port of src/cli/commands/add/skill-action.ts).
+
+Upstream records the skill source in harness.json; nothing is fetched or cloned at add time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.lib.errors.types import ValidationError
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import ConfigIO, to_jsonable
+from agentcore.operations.harness.skill_utils import get_skill_key, validate_git_skill_credential
+
+
+@dataclass
+class AddSkillOptions:
+    harness: str
+    path: str | None = None
+    s3: str | None = None
+    git: str | None = None
+    git_path: str | None = None
+    credential_name: str | None = None
+    username: str | None = None
+    aws_skills: str | bool | None = None
+
+
+def handle_add_skill(
+    options: AddSkillOptions, config_io: ConfigIO | None = None
+) -> Ok[dict[str, Any]] | Err[Exception]:
+    harness = options.harness
+    git_only = [
+        flag
+        for flag, value in (
+            ("--git-path", options.git_path),
+            ("--credential", options.credential_name),
+            ("--username", options.username),
+        )
+        if value
+    ]
+    if git_only and not options.git:
+        return Err(ValidationError(f"{', '.join(git_only)} can only be used with --git"))
+
+    if sum(1 for s in (options.path, options.s3, options.git, options.aws_skills) if s) != 1:
+        return Err(ValidationError("Exactly one of --path, --s3, --git, or --aws-skills is required"))
+    if options.s3 and not options.s3.startswith("s3://"):
+        return Err(ValidationError("--s3 must be an S3 URI starting with s3://"))
+    if options.git and not options.git.startswith("https://"):
+        return Err(ValidationError("--git must be an HTTPS URL starting with https://"))
+
+    io = config_io or ConfigIO()
+    try:
+        spec = to_jsonable(io.read_harness_spec(harness))
+    except Exception:  # noqa: BLE001
+        return Err(
+            ValidationError(f"Harness '{harness}' not found. Check the name or run 'agentcore add harness' first.")
+        )
+
+    if options.credential_name:
+        try:
+            project = io.read_project_spec()
+        except Exception:  # noqa: BLE001
+            return Err(
+                ValidationError("Could not read project configuration. Ensure agentcore.json exists and is valid.")
+            )
+        validation = validate_git_skill_credential(project, options.credential_name)
+        if not validation.success:
+            return validation
+
+    entry: dict[str, Any]
+    if options.path:
+        entry, source = {"path": options.path}, options.path
+    elif options.s3:
+        entry, source = {"s3Uri": options.s3}, options.s3
+    elif options.git:
+        entry = {"gitUrl": options.git}
+        if options.git_path:
+            entry["path"] = options.git_path
+        if options.credential_name:
+            auth = {"credentialName": options.credential_name}
+            if options.username:
+                auth["username"] = options.username
+            entry["auth"] = auth
+        source = f"{options.git} (path: {options.git_path})" if options.git_path else options.git
+    else:
+        paths = (
+            None
+            if options.aws_skills is True
+            else sorted(s.strip() for s in str(options.aws_skills).split(",") if s.strip())
+        )
+        # JS truthiness: an empty (filtered) list is still truthy, so it is written as `paths: []`.
+        entry = {"awsSkills": {} if paths is None else {"paths": paths}}
+        source = "aws-skills (all)" if paths is None else f"aws-skills ({', '.join(paths)})"
+
+    new_key = get_skill_key(entry)
+    if any(get_skill_key(s) == new_key for s in spec.get("skills") or []):
+        return Err(ValidationError(f"Skill '{source}' already exists in harness '{harness}'"))
+
+    spec.setdefault("skills", []).append(entry)
+    io.write_harness_spec(harness, spec)
+    return Ok({"harnessName": harness, "skillSource": source})
+
+
+__all__ = ["AddSkillOptions", "handle_add_skill"]

agentcore/cli/commands/add/skill_command.py

@@ -0,0 +1,87 @@
+"""`agentcore add skill` (port of src/cli/commands/add/skill-command.ts)."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from agentcore.cli.commands.add._commander import (
+    optional_value,
+    optional_value_command,
+    require_options,
+    require_project,
+)
+from agentcore.cli.commands.add.skill_action import AddSkillOptions, handle_add_skill
+from agentcore.cli.errors import get_error_message
+
+
+def _dump(payload: dict) -> str:
+    return json.dumps(payload, separators=(",", ":"))
+
+
+def register_add_skill(add_app: typer.Typer) -> None:
+    @add_app.command("skill", help="Add a skill to a harness", cls=optional_value_command("--aws-skills"))
+    def add_skill(
+        harness: str | None = typer.Option(None, "--harness", help="Target harness name"),
+        path: str | None = typer.Option(None, "--path", help="Path to an installed skill in the environment"),
+        s3: str | None = typer.Option(None, "--s3", help="S3 URI (s3://bucket/path)"),
+        git: str | None = typer.Option(None, "--git", help="HTTPS git repository URL"),
+        git_path: str | None = typer.Option(None, "--git-path", help="Subdirectory within the git repo (for --git)"),
+        credential: str | None = typer.Option(
+            None, "--credential", help="Name of an API key credential in the project (for git auth)"
+        ),
+        username: str | None = typer.Option(None, "--username", help="Username for git auth (for --git)"),
+        aws_skills: str | None = typer.Option(
+            None,
+            "--aws-skills",
+            metavar="[PATHS]",
+            help="Add built-in AWS skills (comma-separated paths, or omit for all)",
+        ),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ) -> None:
+        require_options(("--harness <name>", harness))
+        require_project()
+        try:
+            result = handle_add_skill(
+                AddSkillOptions(
+                    harness=harness or "",
+                    path=path,
+                    s3=s3,
+                    git=git,
+                    git_path=git_path,
+                    credential_name=credential,
+                    username=username,
+                    aws_skills=optional_value(aws_skills),
+                )
+            )
+            if not result.success:
+                if as_json:
+                    typer.echo(_dump({"success": False, "error": get_error_message(result.error)}))
+                else:
+                    typer.echo(get_error_message(result.error), err=True)
+                raise typer.Exit(1)
+            if as_json:
+                typer.echo(
+                    _dump(
+                        {
+                            "success": True,
+                            "harnessName": result.value["harnessName"],
+                            "skillSource": result.value["skillSource"],
+                        }
+                    )
+                )
+            else:
+                typer.echo(f"Added skill '{result.value['skillSource']}' to harness '{result.value['harnessName']}'.")
+                typer.echo("Run 'agentcore deploy' to apply changes.")
+        except typer.Exit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            if as_json:
+                typer.echo(_dump({"success": False, "error": get_error_message(exc)}))
+            else:
+                typer.echo(get_error_message(exc), err=True)
+            raise typer.Exit(1) from None
+
+
+__all__ = ["register_add_skill"]

agentcore/cli/commands/add/tool_action.py

@@ -0,0 +1,160 @@
+"""`add tool` logic (port of src/cli/commands/add/tool-action.ts).
+
+Results are plain dicts shaped like upstream's ``AddToolResult`` (``success``, ``error``,
+``harnessName``, ``toolName``).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.lib.schemas.io.config_io import ConfigIO, to_jsonable
+from agentcore.primitives.deployed_gateways import find_deployed_gateway
+
+VALID_OUTBOUND_AUTH_TYPES = ("awsIam", "none", "oauth")
+VALID_GRANT_TYPES = ("CLIENT_CREDENTIALS", "USER_FEDERATION")
+ARN_PATTERN = re.compile(r"^arn:[^:]+:")
+VALID_TOOL_TYPES = (
+    "agentcore_browser",
+    "agentcore_code_interpreter",
+    "remote_mcp",
+    "agentcore_gateway",
+    "inline_function",
+)
+
+
+@dataclass
+class AddToolOptions:
+    harness: str
+    type: str
+    name: str
+    url: str | None = None
+    browser_arn: str | None = None
+    code_interpreter_arn: str | None = None
+    gateway_arn: str | None = None
+    gateway: str | None = None
+    outbound_auth: str | None = None
+    provider_arn: str | None = None
+    scopes: str | None = None
+    grant_type: str | None = None
+    description: str | None = None
+    input_schema: str | None = None
+    json: bool | None = None
+
+
+def _fail(error: str) -> dict[str, Any]:
+    return {"success": False, "error": error}
+
+
+def handle_add_tool(options: AddToolOptions, config_io: ConfigIO | None = None) -> dict[str, Any]:
+    harness, tool_type, name = options.harness, options.type, options.name
+
+    if tool_type not in VALID_TOOL_TYPES:
+        return _fail(f"Invalid tool type '{tool_type}'. Valid types: {', '.join(VALID_TOOL_TYPES)}")
+    if tool_type == "remote_mcp" and not options.url:
+        return _fail("--url is required for remote_mcp tools")
+    if tool_type == "agentcore_gateway" and not options.gateway_arn and not options.gateway:
+        return _fail("--gateway-arn or --gateway is required for agentcore_gateway tools")
+
+    if (options.description is not None or options.input_schema is not None) and tool_type != "inline_function":
+        return _fail("--description and --input-schema are only valid for inline_function tools")
+    inline_schema: dict[str, Any] | None = None
+    if tool_type == "inline_function":
+        if not options.description:
+            return _fail("--description is required for inline_function tools")
+        if not options.input_schema:
+            return _fail("--input-schema is required for inline_function tools")
+        raw = options.input_schema
+        if raw.startswith("@"):
+            path = raw[1:]
+            try:
+                with open(path, encoding="utf-8") as fh:
+                    raw = fh.read()
+            except (OSError, UnicodeDecodeError):
+                return _fail(f"Could not read --input-schema file: {path}")
+        try:
+            parsed = json.loads(raw)
+        except ValueError:
+            return _fail("--input-schema is not valid JSON")
+        if not isinstance(parsed, dict):
+            return _fail("--input-schema must be a JSON object (a JSON Schema for the tool input)")
+        inline_schema = parsed
+
+    outbound: dict[str, Any] | None = None
+    if options.outbound_auth is not None:
+        if tool_type != "agentcore_gateway":
+            return _fail("--outbound-auth is only valid for agentcore_gateway tools")
+        if options.outbound_auth not in VALID_OUTBOUND_AUTH_TYPES:
+            return _fail(
+                f"Invalid --outbound-auth '{options.outbound_auth}'. Valid: {', '.join(VALID_OUTBOUND_AUTH_TYPES)}"
+            )
+        if options.outbound_auth in ("awsIam", "none"):
+            if options.provider_arn or options.scopes or options.grant_type:
+                return _fail("--provider-arn, --scopes, and --grant-type are only valid with --outbound-auth oauth")
+            outbound = {"awsIam": {}} if options.outbound_auth == "awsIam" else {"none": {}}
+        else:
+            if not options.provider_arn:
+                return _fail("--provider-arn is required when --outbound-auth oauth")
+            if not ARN_PATTERN.match(options.provider_arn):
+                return _fail(f"Invalid --provider-arn '{options.provider_arn}': must be a valid ARN")
+            if not options.scopes:
+                return _fail("--scopes is required when --outbound-auth oauth")
+            scopes = [s.strip() for s in options.scopes.split(",") if s.strip()]
+            if not scopes:
+                return _fail("--scopes must contain at least one scope")
+            if options.grant_type is not None and options.grant_type not in VALID_GRANT_TYPES:
+                return _fail(f"Invalid --grant-type '{options.grant_type}'. Valid: {', '.join(VALID_GRANT_TYPES)}")
+            oauth: dict[str, Any] = {"providerArn": options.provider_arn, "scopes": scopes}
+            if options.grant_type:
+                oauth["grantType"] = options.grant_type
+            outbound = {"oauth": oauth}
+
+    io = config_io or ConfigIO()
+
+    resolved_gateway_arn = options.gateway_arn
+    if tool_type == "agentcore_gateway" and options.gateway and not resolved_gateway_arn:
+        try:
+            state = io.read_deployed_state()
+            gateway_state = find_deployed_gateway(state, options.gateway)
+        except Exception:  # noqa: BLE001
+            return _fail("Could not read deployed state. Deploy the gateway first or use --gateway-arn.")
+        if not gateway_state:
+            return _fail(
+                f"Gateway '{options.gateway}' not found in deployed state. Deploy it first or use --gateway-arn."
+            )
+        resolved_gateway_arn = (
+            gateway_state.get("gatewayArn") if isinstance(gateway_state, dict) else gateway_state.gateway_arn
+        )
+
+    try:
+        spec = to_jsonable(io.read_harness_spec(harness))
+    except Exception:  # noqa: BLE001
+        return _fail(f"Harness '{harness}' not found. Check the name or run 'agentcore add harness' first.")
+
+    if any(t.get("name") == name for t in spec.get("tools") or []):
+        return _fail(f"Tool '{name}' already exists in harness '{harness}'")
+
+    entry: dict[str, Any] = {"type": tool_type, "name": name}
+    if tool_type == "remote_mcp":
+        entry["config"] = {"remoteMcp": {"url": options.url}}
+    elif tool_type == "agentcore_browser" and options.browser_arn:
+        entry["config"] = {"agentCoreBrowser": {"browserArn": options.browser_arn}}
+    elif tool_type == "agentcore_code_interpreter" and options.code_interpreter_arn:
+        entry["config"] = {"agentCoreCodeInterpreter": {"codeInterpreterArn": options.code_interpreter_arn}}
+    elif tool_type == "agentcore_gateway":
+        gateway: dict[str, Any] = {"gatewayArn": resolved_gateway_arn}
+        if outbound:
+            gateway["outboundAuth"] = outbound
+        entry["config"] = {"agentCoreGateway": gateway}
+    elif tool_type == "inline_function":
+        entry["config"] = {"inlineFunction": {"description": options.description, "inputSchema": inline_schema}}
+
+    spec.setdefault("tools", []).append(entry)
+    io.write_harness_spec(harness, spec)
+    return {"success": True, "harnessName": harness, "toolName": name}
+
+
+__all__ = ["VALID_TOOL_TYPES", "AddToolOptions", "handle_add_tool"]

agentcore/cli/commands/add/tool_command.py

@@ -0,0 +1,117 @@
+"""`agentcore add tool` (port of src/cli/commands/add/tool-command.ts)."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from agentcore.cli.commands.add._commander import require_options, require_project
+from agentcore.cli.commands.add.tool_action import AddToolOptions, handle_add_tool
+from agentcore.cli.errors import get_error_message
+
+
+def _dump(payload: dict) -> str:
+    return json.dumps({k: v for k, v in payload.items() if v is not None}, separators=(",", ":"))
+
+
+def register_add_tool(add_app: typer.Typer) -> None:
+    @add_app.command("tool", help="Add a tool to a harness")
+    def add_tool(
+        harness: str | None = typer.Option(None, "--harness", help="Target harness name"),
+        type_: str | None = typer.Option(
+            None,
+            "--type",
+            help="Tool type: agentcore_browser, agentcore_code_interpreter, remote_mcp, agentcore_gateway, "
+            "inline_function",
+        ),
+        name: str | None = typer.Option(None, "--name", help="Tool name"),
+        url: str | None = typer.Option(None, "--url", help="MCP server URL (required for remote_mcp)"),
+        browser_arn: str | None = typer.Option(
+            None, "--browser-arn", help="Custom browser ARN (optional for agentcore_browser)"
+        ),
+        code_interpreter_arn: str | None = typer.Option(
+            None,
+            "--code-interpreter-arn",
+            help="Custom code interpreter ARN (optional for agentcore_code_interpreter)",
+        ),
+        gateway_arn: str | None = typer.Option(None, "--gateway-arn", help="Gateway ARN (for agentcore_gateway)"),
+        gateway: str | None = typer.Option(
+            None,
+            "--gateway",
+            help="Project gateway name — resolves ARN from deployed state (for agentcore_gateway)",
+        ),
+        outbound_auth: str | None = typer.Option(
+            None,
+            "--outbound-auth",
+            help="Gateway outbound auth: awsIam, none, or oauth (default: awsIam if omitted) [agentcore_gateway]",
+        ),
+        provider_arn: str | None = typer.Option(
+            None, "--provider-arn", help="OAuth credential provider ARN (required when --outbound-auth oauth)"
+        ),
+        scopes: str | None = typer.Option(
+            None,
+            "--scopes",
+            help='Comma-separated OAuth scopes (required when --outbound-auth oauth), e.g. "openid,profile" or '
+            '"https://api.example.com/read"',
+        ),
+        grant_type: str | None = typer.Option(
+            None,
+            "--grant-type",
+            help="OAuth grant type: CLIENT_CREDENTIALS or USER_FEDERATION (for --outbound-auth oauth)",
+        ),
+        description: str | None = typer.Option(
+            None, "--description", help="Tool description shown to the model (required for inline_function)"
+        ),
+        input_schema: str | None = typer.Option(
+            None,
+            "--input-schema",
+            help="JSON Schema for the tool input, as a JSON string or @path/to/schema.json (required for "
+            "inline_function)",
+        ),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ) -> None:
+        require_options(("--harness <name>", harness), ("--type <type>", type_), ("--name <name>", name))
+        require_project()
+        try:
+            result = handle_add_tool(
+                AddToolOptions(
+                    harness=harness or "",
+                    type=type_ or "",
+                    name=name or "",
+                    url=url,
+                    browser_arn=browser_arn,
+                    code_interpreter_arn=code_interpreter_arn,
+                    gateway_arn=gateway_arn,
+                    gateway=gateway,
+                    outbound_auth=outbound_auth,
+                    provider_arn=provider_arn,
+                    scopes=scopes,
+                    grant_type=grant_type,
+                    description=description,
+                    input_schema=input_schema,
+                    json=as_json,
+                )
+            )
+            if not result["success"]:
+                if as_json:
+                    typer.echo(_dump(result))
+                else:
+                    typer.echo(result["error"], err=True)
+                raise typer.Exit(1)
+            if as_json:
+                typer.echo(_dump(result))
+            else:
+                typer.echo(f"Added tool '{result['toolName']}' to harness '{result['harnessName']}'.")
+                typer.echo("Run 'agentcore deploy' to apply changes.")
+        except typer.Exit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            if as_json:
+                typer.echo(_dump({"success": False, "error": get_error_message(exc)}))
+            else:
+                typer.echo(get_error_message(exc), err=True)
+            raise typer.Exit(1) from None
+
+
+__all__ = ["register_add_tool"]