agentkit-sdk-python 0.7.0__py3-none-any.whl → 0.7.2__py3-none-any.whl

agentkit/errors.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Top-level exception root for AgentKit.
+
+This module is a stdlib-only leaf: it has no intra-package imports so that any
+subpackage (``agentkit.auth``, ``agentkit.toolkit``, ...) can subclass the
+single root without creating dependency cycles.
+"""
+
+
+class AgentKitError(Exception):
+    """The single root of the AgentKit exception hierarchy.
+
+    Every domain-specific AgentKit exception (auth, toolkit, API, ...) ultimately
+    inherits from this class so callers can ``except AgentKitError`` to catch any
+    AgentKit-originated failure.
+    """
+
+
+__all__ = ["AgentKitError"]

agentkit/platform/configuration.py

@@ -15,7 +15,6 @@
 from __future__ import annotations
 
 import json
-import logging
 import os
 import threading
 import time
@@ -42,8 +41,9 @@ from agentkit.utils.global_config_io import (
     get_global_config_value,
     read_global_config_dict,
 )
+from agentkit.utils.logging_config import get_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 VEFAAS_IAM_CREDENTIAL_PATH = "/var/run/secrets/iam/credential"
 VEFAAS_IAM_CREDENTIAL_FALLBACK_TTL_SECONDS = 60

agentkit/sdk/account/client.py

@@ -66,9 +66,7 @@ class AgentkitAccountClient(BaseAgentkitClient):
         Returns:
             The status string ('Enabled' or 'Disabled'), or None if service not found.
         """
-        print(1)
         response = self.list_account_linked_services(ListAccountLinkedServicesRequest())
-        print(2)
         if not response.service_statuses:
             return None
         for svc in response.service_statuses:

agentkit/sdk/identity/auth.py

@@ -21,6 +21,7 @@ from agentkit.platform import (
     resolve_credentials,
     resolve_endpoint,
 )
+from agentkit.toolkit.errors import ApiError
 
 
 def requires_api_key(*, provider_name: str, into: str = "api_key"):
@@ -59,8 +60,8 @@ def requires_api_key(*, provider_name: str, into: str = "api_key"):
 
             try:
                 return response["Result"]["ApiKey"]
-            except Exception as _:
-                raise RuntimeError(f"Get api key failed: {response}")
+            except Exception as e:
+                raise ApiError("GetResourceApiKey did not return an ApiKey") from e
 
         @wraps(func)
         async def async_wrapper(*args: Any, **kwargs: Any) -> Any:

agentkit/toolkit/cli/sandbox/cli.py

@@ -22,6 +22,7 @@ from agentkit.toolkit.cli.sandbox.cli_create import create_command
 from agentkit.toolkit.cli.sandbox.cli_exec import exec_command
 from agentkit.toolkit.cli.sandbox.cli_file import file_command
 from agentkit.toolkit.cli.sandbox.cli_get import get_command
+from agentkit.toolkit.cli.sandbox.cli_model_login import codex_login_command
 from agentkit.toolkit.cli.sandbox.cli_mount import mount_command
 from agentkit.toolkit.cli.sandbox.cli_run import run_command
 from agentkit.toolkit.cli.sandbox.cli_shell import shell_command
@@ -33,7 +34,10 @@ sandbox_app = typer.Typer(
     no_args_is_help=True,
 )
 
-sandbox_app.command(name="create")(create_command)
+sandbox_app.command(
+    name="create",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)(create_command)
 sandbox_app.command(name="get")(get_command)
 sandbox_app.command(name="mount")(mount_command)
 sandbox_app.command(
@@ -46,4 +50,6 @@ sandbox_app.command(
     context_settings={"allow_extra_args": True},
 )(shell_command)
 sandbox_app.command(name="web")(web_command)
+sandbox_app.command(name="codex-login")(codex_login_command)
+sandbox_app.command(name="model-login")(codex_login_command)  # provider-agnostic alias
 sandbox_app.add_typer(file_command, name="file")

agentkit/toolkit/cli/sandbox/cli_create.py

@@ -32,16 +32,20 @@ from agentkit.toolkit.cli.sandbox.model_config import (
     CODE_ENV_HOME,
     CODEX_CONFIG_TOML_ENV,
     CODEX_MODEL_CATALOG_JSON_ENV,
-    DEFAULT_MODEL_PROVIDER,
     ModelProviderType,
     MODEL_API_KEY_ENV,
     MODEL_API_KEY_ENV_KEYS,
     MODEL_BASE_URL_ENV_KEYS,
     MODEL_NAME_ENV_KEYS,
     MODEL_PROVIDER_ENV,
-    get_model_provider_config,
+    infer_model_provider_from_base_url,
+    normalize_model_base_url,
     normalize_model_provider,
+    resolve_model_base_urls,
     resolve_model_name,
+    should_emit_codex_model_catalog,
+    should_emit_codex_model_config,
+    validate_model_provider_base_url,
     build_codex_config_toml as _shared_build_codex_config_toml,
     build_codex_model_catalog_json as _shared_build_codex_model_catalog_json,
 )
@@ -73,6 +77,8 @@ DEFAULT_BROWSER_EXTRA_ARGS = (
     "--enable-unsafe-swiftshader --use-gl=angle "
     "--use-angle=swiftshader-webgl --ignore-gpu-blocklist"
 )
+WEB_SEARCH_API_KEY_ENV = "WEB_SEARCH_API_KEY"
+SKILL_ROLE_NAME_OPTION = "--skill-role-name"
 TOOL_READY_STATUS = "Ready"
 TOOL_FAILED_STATUSES = {"Error", "Failed", "CreateFailed", "Deleting", "Deleted"}
 TOOL_WAIT_INTERVAL_SECONDS = 5
@@ -115,16 +121,16 @@ def _append_tool_envs(
         return
 
     envs.extend(
-        tools_types.EnvsItemForCreateTool(Key=key, Value=resolved)
-        for key in keys
+        tools_types.EnvsItemForCreateTool(Key=key, Value=resolved) for key in keys
     )
 
 
 def _build_codex_config_toml(
     model_name: str,
     model_provider: str | ModelProviderType | None = None,
+    model_base_url: Optional[str] = None,
 ) -> str:
-    return _shared_build_codex_config_toml(model_name, model_provider)
+    return _shared_build_codex_config_toml(model_name, model_provider, model_base_url)
 
 
 def _build_codex_model_catalog_json(
@@ -138,31 +144,43 @@ def _append_code_env_tool_envs(
     envs: list[tools_types.EnvsItemForCreateTool],
     model_name: str,
     model_provider: str | ModelProviderType | None,
+    model_base_url: Optional[str],
+    *,
+    include_codex_model_config: bool = True,
 ) -> None:
-    envs.extend(
-        [
-            tools_types.EnvsItemForCreateTool(
-                Key="OPENCODE_DISABLE_AUTOUPDATE",
-                Value="1",
-            ),
-            tools_types.EnvsItemForCreateTool(
-                Key="HOME",
-                Value=CODE_ENV_HOME,
-            ),
-            tools_types.EnvsItemForCreateTool(
-                Key="CODEX_HOME",
-                Value=CODE_ENV_CODEX_HOME,
-            ),
+    code_envs = [
+        tools_types.EnvsItemForCreateTool(
+            Key="OPENCODE_DISABLE_AUTOUPDATE",
+            Value="1",
+        ),
+        tools_types.EnvsItemForCreateTool(
+            Key="HOME",
+            Value=CODE_ENV_HOME,
+        ),
+        tools_types.EnvsItemForCreateTool(
+            Key="CODEX_HOME",
+            Value=CODE_ENV_CODEX_HOME,
+        ),
+    ]
+    if include_codex_model_config:
+        code_envs.append(
             tools_types.EnvsItemForCreateTool(
                 Key=CODEX_CONFIG_TOML_ENV,
-                Value=_build_codex_config_toml(model_name, model_provider),
-            ),
-            tools_types.EnvsItemForCreateTool(
-                Key=CODEX_MODEL_CATALOG_JSON_ENV,
-                Value=_build_codex_model_catalog_json(model_name, model_provider),
-            ),
-        ]
-    )
+                Value=_build_codex_config_toml(
+                    model_name,
+                    model_provider,
+                    model_base_url,
+                ),
+            )
+        )
+        if should_emit_codex_model_catalog(model_provider):
+            code_envs.append(
+                tools_types.EnvsItemForCreateTool(
+                    Key=CODEX_MODEL_CATALOG_JSON_ENV,
+                    Value=_build_codex_model_catalog_json(model_name, model_provider),
+                )
+            )
+    envs.extend(code_envs)
 
 
 def _build_tool_model_envs(
@@ -170,12 +188,29 @@ def _build_tool_model_envs(
     tool_type: str,
     model_name: Optional[str] = None,
     model_api_key: Optional[str] = None,
-    model_provider: str | ModelProviderType | None = DEFAULT_MODEL_PROVIDER,
+    model_provider: str | ModelProviderType | None = None,
+    model_base_url: Optional[str] = None,
+    model_provider_was_provided: Optional[bool] = None,
+    model_base_url_was_provided: Optional[bool] = None,
+    websearch_apikey: Optional[str] = None,
 ) -> list[tools_types.EnvsItemForCreateTool] | None:
     envs: list[tools_types.EnvsItemForCreateTool] = []
-    provider_config = get_model_provider_config(model_provider)
-    resolved_model_provider = normalize_model_provider(model_provider)
-    resolved_model_name = resolve_model_name(model_name, model_provider)
+    validate_model_provider_base_url(
+        model_provider=model_provider,
+        model_base_url=model_base_url,
+        model_provider_was_provided=model_provider_was_provided,
+        model_base_url_was_provided=model_base_url_was_provided,
+    )
+    resolved_model_base_url = normalize_model_base_url(model_base_url)
+    effective_model_provider = model_provider or infer_model_provider_from_base_url(
+        resolved_model_base_url
+    )
+    resolved_model_provider = normalize_model_provider(effective_model_provider)
+    resolved_model_name = resolve_model_name(model_name, resolved_model_provider)
+    resolved_base_url, resolved_anthropic_base_url = resolve_model_base_urls(
+        model_provider=resolved_model_provider,
+        model_base_url=resolved_model_base_url,
+    )
     resolved_model_api_key = model_api_key or os.getenv(MODEL_API_KEY_ENV)
     _append_tool_envs(envs, (MODEL_PROVIDER_ENV,), resolved_model_provider)
     _append_tool_envs(envs, MODEL_NAME_ENV_KEYS, resolved_model_name)
@@ -183,17 +218,30 @@ def _build_tool_model_envs(
     _append_tool_envs(
         envs,
         MODEL_BASE_URL_ENV_KEYS,
-        provider_config.model_base_url,
+        resolved_base_url,
     )
     _append_tool_envs(
         envs,
         ANTHROPIC_BASE_URL_ENV_KEYS,
-        provider_config.anthropic_base_url,
+        resolved_anthropic_base_url,
     )
     _append_tool_envs(envs, DISABLED_SERVICE_ENV_KEYS, "true")
     _append_tool_envs(envs, (BROWSER_EXTRA_ARGS_ENV,), DEFAULT_BROWSER_EXTRA_ARGS)
+    _append_tool_envs(envs, (WEB_SEARCH_API_KEY_ENV,), websearch_apikey)
     if tool_type.strip() == DEFAULT_CREATE_TOOL_TYPE:
-        _append_code_env_tool_envs(envs, resolved_model_name, model_provider)
+        _append_code_env_tool_envs(
+            envs,
+            resolved_model_name,
+            resolved_model_provider,
+            resolved_model_base_url,
+            include_codex_model_config=(
+                bool(resolved_model_name)
+                and should_emit_codex_model_config(
+                    model_provider=resolved_model_provider,
+                    model_base_url=resolved_model_base_url,
+                )
+            ),
+        )
     return envs or None
 
 
@@ -207,7 +255,12 @@ def _build_create_tool_request(
     cpu: int = DEFAULT_CPU,
     model_name: Optional[str] = None,
     model_api_key: Optional[str] = None,
-    model_provider: str | ModelProviderType | None = DEFAULT_MODEL_PROVIDER,
+    model_provider: str | ModelProviderType | None = None,
+    model_base_url: Optional[str] = None,
+    model_provider_was_provided: Optional[bool] = None,
+    model_base_url_was_provided: Optional[bool] = None,
+    role_name: Optional[str] = None,
+    websearch_apikey: Optional[str] = None,
 ) -> tools_types.CreateToolRequest:
     resolved_tool_type = tool_type.strip() or DEFAULT_CREATE_TOOL_TYPE
     resolved_name = (name or "").strip() or _generate_tool_name(resolved_tool_type)
@@ -225,6 +278,7 @@ def _build_create_tool_request(
         ToolType=resolved_tool_type,
         CpuMilli=cpu_milli,
         MemoryMb=memory_mb,
+        RoleName=role_name,
         AuthorizerConfiguration=tools_types.AuthorizerForCreateTool(
             KeyAuth=tools_types.AuthorizerKeyAuthForCreateTool(
                 ApiKeyName=generate_apikey_name(),
@@ -241,6 +295,10 @@ def _build_create_tool_request(
             model_name=model_name,
             model_api_key=model_api_key,
             model_provider=model_provider,
+            model_base_url=model_base_url,
+            model_provider_was_provided=model_provider_was_provided,
+            model_base_url_was_provided=model_base_url_was_provided,
+            websearch_apikey=websearch_apikey,
         ),
     )
 
@@ -301,6 +359,106 @@ def _wait_for_tool_ready(
         time.sleep(interval_seconds)
 
 
+def _ensure_sandbox_role(
+    role_name: str,
+    region: str,
+) -> str:
+    import json as _json
+    from agentkit.toolkit.volcengine.iam import VeIAM
+
+    iam = VeIAM(region=region)
+    existing = iam.get_role(role_name)
+    if existing is not None:
+        return role_name
+
+    agentkit_service_code = (
+        (
+            os.getenv("VOLCENGINE_AGENTKIT_SERVICE")
+            or os.getenv("VOLC_AGENTKIT_SERVICE")
+            or os.getenv("BYTEPLUS_AGENTKIT_SERVICE")
+            or ""
+        )
+        .strip()
+        .lower()
+    )
+    service = "vefaas"
+    if "stg" in agentkit_service_code:
+        service = "vefaas_dev"
+    trust_policy = _json.dumps(
+        {
+            "Statement": [
+                {
+                    "Effect": "Allow",
+                    "Action": ["sts:AssumeRole"],
+                    "Principal": {"Service": [service]},
+                }
+            ]
+        }
+    )
+    iam.create_role(role_name, trust_policy)
+    iam.attach_role_policy(
+        role_name,
+        policy_name="AgentKitSkillsSandboxAccess",
+        policy_type="System",
+    )
+    return role_name
+
+
+def _generate_default_role_name() -> str:
+    return f"agentkit-sandbox-{generate_random_id(8)}"
+
+
+def _resolve_skill_role(
+    skill_role_name: Optional[str],
+    skill_role_name_provided: bool,
+    region: str,
+) -> Optional[str]:
+    if not skill_role_name_provided:
+        return None
+    resolved_name = (skill_role_name or "").strip()
+    if not resolved_name:
+        resolved_name = _generate_default_role_name()
+    _ensure_sandbox_role(resolved_name, region)
+    return resolved_name
+
+
+def _resolve_create_extra_args(
+    ctx: typer.Context,
+) -> tuple[Optional[str], bool]:
+    raw_args = list(ctx.args)
+    skill_role_name: Optional[str] = None
+    skill_role_name_provided = False
+    remaining_args: list[str] = []
+    index = 0
+    while index < len(raw_args):
+        current = raw_args[index]
+        if current == SKILL_ROLE_NAME_OPTION:
+            if skill_role_name_provided:
+                error(f"{SKILL_ROLE_NAME_OPTION} cannot be provided multiple times")
+            skill_role_name_provided = True
+            if index + 1 < len(raw_args) and not raw_args[index + 1].startswith("-"):
+                skill_role_name = raw_args[index + 1]
+                index += 2
+                continue
+            index += 1
+            continue
+        if current.startswith(f"{SKILL_ROLE_NAME_OPTION}="):
+            if skill_role_name_provided:
+                error(f"{SKILL_ROLE_NAME_OPTION} cannot be provided multiple times")
+            skill_role_name_provided = True
+            skill_role_name = current.split("=", 1)[1]
+            index += 1
+            continue
+        remaining_args.append(current)
+        index += 1
+
+    if remaining_args:
+        unknown = " ".join(remaining_args)
+        error(f"Unknown arguments: {unknown}")
+
+    return skill_role_name, skill_role_name_provided
+
+
 def create_tool(
     *,
     tool_type: str = DEFAULT_CREATE_TOOL_TYPE,
@@ -310,11 +468,35 @@ def create_tool(
     cpu: int = DEFAULT_CPU,
     model_name: Optional[str] = None,
     model_api_key: Optional[str] = None,
-    model_provider: str | ModelProviderType | None = DEFAULT_MODEL_PROVIDER,
+    model_provider: str | ModelProviderType | None = None,
+    model_base_url: Optional[str] = None,
+    skill_role_name: Optional[str] = None,
+    skill_role_name_provided: bool = False,
+    websearch_apikey: Optional[str] = None,
 ) -> dict[str, object]:
-    resolved_model_provider = normalize_model_provider(model_provider)
+    resolved_model_base_url = normalize_model_base_url(model_base_url)
+    raw_model_provider = (
+        model_provider.value
+        if isinstance(model_provider, ModelProviderType)
+        else model_provider
+    )
+    effective_model_provider = raw_model_provider or infer_model_provider_from_base_url(
+        resolved_model_base_url
+    )
+    resolved_model_provider = normalize_model_provider(effective_model_provider)
     region = _resolve_region(SANDBOX_REGION_ENV, "agentkit")
     tos_region = _resolve_region(SANDBOX_TOS_REGION_ENV, "tos")
+
+    if skill_role_name_provided and websearch_apikey:
+        error("--skill-role-name and --websearch-apikey are mutually exclusive")
+
+    resolved_role_name = _resolve_skill_role(
+        skill_role_name,
+        skill_role_name_provided,
+        region,
+    )
+    resolved_websearch_apikey = (websearch_apikey or "").strip() or None
+
     request = _build_create_tool_request(
         tool_type=tool_type,
         name=tool_name,
@@ -324,7 +506,12 @@ def create_tool(
         cpu=cpu,
         model_name=model_name,
         model_api_key=model_api_key,
-        model_provider=resolved_model_provider,
+        model_provider=effective_model_provider,
+        model_base_url=resolved_model_base_url,
+        model_provider_was_provided=bool((raw_model_provider or "").strip()),
+        model_base_url_was_provided=bool(resolved_model_base_url),
+        role_name=resolved_role_name,
+        websearch_apikey=resolved_websearch_apikey,
     )
     client = AgentkitToolsClient(
         region=region,
@@ -340,10 +527,14 @@ def create_tool(
         "name": final_tool.name or request.name,
         "status": final_tool.status or TOOL_READY_STATUS,
         "model_provider": resolved_model_provider,
+        "model_base_url": resolved_model_base_url,
+        "role_name": resolved_role_name,
+        "websearch_apikey_set": bool(resolved_websearch_apikey),
     }
 
 
 def create_command(
+    ctx: typer.Context,
     tool_type: str = typer.Option(
         DEFAULT_CREATE_TOOL_TYPE,
         "--tool-type",
@@ -357,10 +548,7 @@ def create_command(
     tos_bucket: Optional[str] = typer.Option(
         None,
         "--tos-bucket",
-        help=(
-            "TOS bucket to mount. "
-            "Omit to create the tool without a TOS mount."
-        ),
+        help=("TOS bucket to mount. Omit to create the tool without a TOS mount."),
     ),
     tos_mount: Optional[str] = typer.Option(
         None,
@@ -392,14 +580,38 @@ def create_command(
             "and ANTHROPIC_AUTH_TOKEN when creating a tool."
         ),
     ),
-    model_provider: ModelProviderType = typer.Option(
-        ModelProviderType.MODEL_SQUARE,
+    model_provider: Optional[str] = typer.Option(
+        None,
         "--model-provider",
         help="Model provider to use for base URLs, defaults, and model catalog.",
     ),
+    model_base_url: Optional[str] = typer.Option(
+        None,
+        "--model-base-url",
+        help=(
+            "Custom model base URL to inject into OPENCODE_BASE_URL, "
+            "CODEX_BASE_URL, MODEL_BASE_URL, and ANTHROPIC_BASE_URL."
+        ),
+    ),
+    websearch_apikey: Optional[str] = typer.Option(
+        None,
+        "--websearch-apikey",
+        help=(
+            "Web search API key to inject as WEB_SEARCH_API_KEY env. "
+            f"Mutually exclusive with {SKILL_ROLE_NAME_OPTION}. "
+            "Use --disable-websearch-apikey in exec to disable it per session."
+        ),
+    ),
 ) -> None:
-    """Create an AgentKit Tool with optional TOS mount."""
+    """Create an AgentKit Tool with optional TOS mount.
+
+    Extra option:
+    - --skill-role-name ROLE_NAME: reuse the role if it exists, otherwise create it
+    - --skill-role-name: create a role with an auto-generated name
+    """
+    result = None
     try:
+        skill_role_name, skill_role_name_provided = _resolve_create_extra_args(ctx)
         if tos_mount is not None and not (tos_bucket or "").strip():
             error("--tos-mount requires --tos-bucket")
         result = create_tool(
@@ -410,7 +622,11 @@ def create_command(
             cpu=cpu,
             model_name=model_name,
             model_api_key=model_api_key,
-            model_provider=model_provider.value,
+            model_provider=model_provider,
+            model_base_url=model_base_url,
+            skill_role_name=skill_role_name,
+            skill_role_name_provided=skill_role_name_provided,
+            websearch_apikey=websearch_apikey,
         )
         save_tool_result(str(result["tool_type"]), result)
     except (typer.Abort, typer.Exit):
@@ -421,3 +637,10 @@ def create_command(
     typer.echo("工具创建成功")
     typer.echo(f"工具ID：{result['tool_id']}")
     typer.echo(f"状态：{result['status']}")
+    if result.get("role_name"):
+        typer.echo(f"角色名：{result['role_name']}")
+    if not result.get("role_name") and not result.get("websearch_apikey_set"):
+        typer.echo(
+            "提示：未配置 WebSearch（可通过 --skill-role-name 配置 Role 或 "
+            "--websearch-apikey 配置 API Key 来启用）"
+        )