agentkit-sdk-python 0.5.10__tar.gz → 0.6.0__tar.gz

{agentkit_sdk_python-0.5.10 → agentkit_sdk_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentkit-sdk-python
-Version: 0.5.10
+Version: 0.6.0
 Summary: Python SDK for transforming any AI agent into a production-ready application. Framework-agnostic primitives for runtime, memory, authentication, and tools with volcengine-managed infrastructure.
 Author-email: Xiangrui Cheng <innsdcc@gmail.com>, Yumeng Bao <baoyumeng.123@gmail.com>, Yaozheng Fang <fangyozheng@gmail.com>, Guodong Li <cu.eric.lee@gmail.com>
 License:                                  Apache License
@@ -238,6 +238,7 @@ Requires-Dist: tos>=2.8.7
 Requires-Dist: volcengine
 Requires-Dist: pyfiglet>=1.0.2
 Requires-Dist: typing_extensions>=4.12
+Requires-Dist: websocket-client>=1.8.0
 Requires-Dist: pyreadline3; sys_platform == "win32"
 Provides-Extra: extensions
 Provides-Extra: toolkit

agentkit_sdk_python-0.6.0/agentkit/auth/__init__.py

@@ -0,0 +1,100 @@
+# 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.
+
+"""agentkit.auth — passwordless / SSO authentication for AgentKit.
+
+A self-contained, dependency-free library (Python stdlib only) that lets a CLI
+or any developer's program obtain Volcengine credentials in two ways:
+
+* **AK/SK** — long-lived access keys from env / config (the existing behaviour).
+* **SSO (OAuth 2.0 / OIDC)** — interactive browser login against a UserPool
+  (federating Feishu / ByteDance-SSO / any OIDC IdP), exchanged for **short-lived
+  STS credentials** via ``AssumeRoleWithOIDC``. No AK/SK ever touches disk.
+
+The library is intentionally decoupled from the rest of the AgentKit SDK: it has
+no import dependency on ``agentkit.client`` / ``agentkit.platform`` and can be
+vendored or used on its own::
+
+    from agentkit.auth import login, load_session, AuthProfile
+
+    profile = AuthProfile(
+        name="my-pool",
+        issuer="https://userpool-<uid>.userpool.auth.id.cn-beijing.volces.com",
+        client_id="<PUBLIC_CLI_CLIENT_ID>",
+        role_trn="trn:iam::<ACCOUNT_ID>:role/<ROLE_NAME>",
+        provider_trn="trn:iam::<ACCOUNT_ID>:oidc-provider/<PROVIDER_NAME>",
+        region="cn-beijing",
+    )
+    session = login(profile)            # opens a browser, returns an AuthSession
+    creds = session.credentials()        # -> StsCredentials(ak, sk, token, expires_at)
+
+The SDK wires this into its credential-resolution chain (see
+``agentkit.platform.configuration``) so that ``agentkit login`` once makes every
+subsequent command work with the resulting STS credentials — and an expired STS
+session auto-refreshes from the cached OIDC refresh token without a new browser
+round-trip.
+"""
+
+from __future__ import annotations
+
+from agentkit.auth.errors import AuthError, NetworkError, SsoError
+from agentkit.auth.oauth import OAuthClient, run_loopback_login
+from agentkit.auth.profile import (
+    AuthProfile,
+    active_profile_name,
+    address_to_profile_name,
+    clear_active_profile,
+    list_profiles,
+    load_profile,
+    save_profile,
+    set_active_profile,
+)
+from agentkit.auth.providers import (
+    AkSkCredentialProvider,
+    CredentialProvider,
+    SsoStsCredentialProvider,
+)
+from agentkit.auth.resolve import discover_cli_config, resolve_profile
+from agentkit.auth.session import AuthSession, StsCredentials
+from agentkit.auth.sso import login, load_session, logout, whoami
+from agentkit.auth.sts import assume_role_with_oidc, get_caller_identity
+
+__all__ = [
+    "AuthError",
+    "AuthProfile",
+    "AuthSession",
+    "AkSkCredentialProvider",
+    "CredentialProvider",
+    "NetworkError",
+    "OAuthClient",
+    "SsoError",
+    "SsoStsCredentialProvider",
+    "StsCredentials",
+    "active_profile_name",
+    "address_to_profile_name",
+    "assume_role_with_oidc",
+    "clear_active_profile",
+    "discover_cli_config",
+    "get_caller_identity",
+    "list_profiles",
+    "load_profile",
+    "load_session",
+    "login",
+    "logout",
+    "resolve_profile",
+    "run_loopback_login",
+    "save_profile",
+    "set_active_profile",
+    "whoami",
+]

agentkit_sdk_python-0.6.0/agentkit/auth/_openapi.py

@@ -0,0 +1,173 @@
+# 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.
+
+"""Minimal signed Volcengine OpenAPI client for the auth ADMIN commands.
+
+Stdlib-only SigV4 (reusing :mod:`agentkit.auth._sigv4`) so the admin path that
+provisions the UserPool client / IAM OIDC provider / STS role carries no
+third-party dependency. Used only by ``agentkit auth admin`` — the end-user login
+path never touches it. A mandatory ``GetCallerIdentity`` guard runs before any write.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from agentkit.auth._sigv4 import sign_headers
+from agentkit.auth.errors import AuthError
+from agentkit.auth.ssl_trust import harden_default_ssl_context
+
+_HOST = "open.volcengineapi.com"
+# Services whose OpenAPI reads parameters from the query string, not a JSON body.
+_QUERY_PARAM_SERVICES = {"iam"}
+
+# Map common Volcengine error-code fragments to an actionable next step. Surfaced on
+# ApiError.hint so a raw mid-provision failure tells the operator what to fix, not just
+# the opaque code (important on a cold account where services/quotas aren't set up).
+_REMEDIATION = (
+    ("notinwhitelist", "this feature needs per-account whitelisting — request it, or use the default path (ticket mode / inline JWKS)."),
+    ("servicenotfound", "this Volcengine service may not be enabled on this account — enable it in the console, then re-run."),
+    ("invalidaction", "this service/action may be unavailable on this account — confirm the service is enabled (run `agentkit auth admin doctor`)."),
+    ("nosuchentity", "the referenced IAM/AgentKit resource is missing — if it is 'AgentKitSandboxAccess', activate AgentKit on this account first."),
+    ("policynotexist", "the referenced policy is missing — activate AgentKit on this account so its system policies exist."),
+    ("accessdenied", "the provisioning credentials lack permission for this action — use an admin AK/SK with IAM/AgentKit rights."),
+    ("nopermission", "the provisioning credentials lack permission for this action — use an admin AK/SK with IAM/AgentKit rights."),
+    ("unauthorized", "the provisioning credentials lack permission for this action — use an admin AK/SK with IAM/AgentKit rights."),
+    ("limitexceeded", "an account quota/limit was hit — request a quota increase or remove unused resources."),
+    ("quota", "an account quota/limit was hit — request a quota increase or remove unused resources."),
+    ("throttl", "the API is throttling — retry shortly."),
+)
+
+
+def remediation_for(code: str) -> str | None:
+    """Best-effort actionable hint for a Volcengine error code, or None."""
+    c = (code or "").lower()
+    for frag, hint in _REMEDIATION:
+        if frag in c:
+            return hint
+    return None
+
+
+class ApiError(AuthError):
+    """A Volcengine OpenAPI call returned an error. Subclasses AuthError so the CLI's
+    ``except AuthError`` handlers surface it as a clean message, not a traceback.
+
+    Carries an actionable ``hint`` derived from the error code where possible."""
+
+    def __init__(self, action: str, code: str, message: str) -> None:
+        super().__init__(f"{action}: {code}: {message}", hint=remediation_for(code))
+        self.action = action
+        self.code = code
+        self.message = message
+
+
+class OpenApiClient:
+    """Signed Volcengine OpenAPI caller with an account guard (admin use only)."""
+
+    def __init__(
+        self,
+        *,
+        access_key: str | None = None,
+        secret_key: str | None = None,
+        session_token: str | None = None,
+        region: str = "cn-beijing",
+        expect_account: str | None = None,
+        harden_ssl: bool = True,
+    ) -> None:
+        if harden_ssl:
+            harden_default_ssl_context()
+        self.ak = access_key or os.getenv("VOLCENGINE_ACCESS_KEY") or os.getenv("VOLC_ACCESSKEY")
+        self.sk = secret_key or os.getenv("VOLCENGINE_SECRET_KEY") or os.getenv("VOLC_SECRETKEY")
+        self.token = session_token or os.getenv("VOLCENGINE_SESSION_TOKEN")
+        if not (self.ak and self.sk):
+            raise AuthError(
+                "admin provisioning needs Volcengine credentials.",
+                hint="export VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY for the account that owns the UserPool.",
+            )
+        self.region = region
+        ident = self.call("sts", "GetCallerIdentity", "2018-01-01", {})
+        self.account_id = str(ident.get("AccountId") or "")
+        if expect_account and self.account_id != expect_account:
+            raise AuthError(
+                f"refusing to provision: caller account {self.account_id} != expected {expect_account}"
+            )
+
+    def call(self, service: str, action: str, version: str, body: dict) -> dict:
+        if service in _QUERY_PARAM_SERVICES:
+            query = {"Action": action, "Version": version}
+            for k, v in body.items():
+                if isinstance(v, (list, tuple)):
+                    for i, item in enumerate(v):
+                        query[f"{k}.{i + 1}"] = str(item)
+                else:
+                    query[k] = str(v)
+            payload = b""
+        else:
+            query = {"Action": action, "Version": version}
+            payload = json.dumps(body).encode()
+        headers = sign_headers(
+            "POST", _HOST, query, payload,
+            access_key=self.ak, secret_key=self.sk, service=service, region=self.region,
+            session_token=self.token,
+        )
+        url = f"https://{_HOST}/?{urllib.parse.urlencode(query)}"
+        req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
+        try:
+            raw = urllib.request.urlopen(req, timeout=30).read()
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+        data = json.loads(raw)
+        err = (data.get("ResponseMetadata") or {}).get("Error")
+        if err:
+            raise ApiError(action, str(err.get("Code")), str(err.get("Message")))
+        return data.get("Result") or {}
+
+    def call_get(self, service: str, action: str, version: str, params: dict) -> dict:
+        """GET-style signed call (params in the query string) — e.g. the vpc service."""
+        query = {"Action": action, "Version": version}
+        for k, v in params.items():
+            if isinstance(v, (list, tuple)):
+                for i, item in enumerate(v):
+                    query[f"{k}.{i + 1}"] = str(item)
+            else:
+                query[k] = str(v)
+        headers = sign_headers(
+            "GET", _HOST, query, b"",
+            access_key=self.ak, secret_key=self.sk, service=service, region=self.region,
+            session_token=self.token,
+        )
+        url = f"https://{_HOST}/?{urllib.parse.urlencode(query)}"
+        req = urllib.request.Request(url, headers=headers, method="GET")
+        try:
+            raw = urllib.request.urlopen(req, timeout=30).read()
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+        data = json.loads(raw)
+        err = (data.get("ResponseMetadata") or {}).get("Error")
+        if err:
+            raise ApiError(action, str(err.get("Code")), str(err.get("Message")))
+        return data.get("Result") or {}
+
+    def call_ok(self, service, action, version, body, *, ok=("Exist", "Duplicate", "Conflict", "AlreadyExist")):
+        """Like :meth:`call` but swallow 'already exists'-style errors (idempotent ensure)."""
+        try:
+            return self.call(service, action, version, body)
+        except ApiError as exc:
+            if any(tok.lower() in exc.code.lower() for tok in ok):
+                return {}
+            raise

agentkit_sdk_python-0.6.0/agentkit/auth/_redact.py

@@ -0,0 +1,55 @@
+# 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.
+
+"""Secret redaction for log/error output.
+
+Auth flows shuttle tokens and STS secrets around; any of them can end up in an
+exception body or a debug print. :func:`redact` scrubs the high-entropy strings
+(JWTs, bearer/STS tokens, ``ak/sk`` style secrets) before they are surfaced.
+"""
+
+from __future__ import annotations
+
+import re
+
+# JWTs: three base64url segments separated by dots.
+_JWT = re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b")
+# Volcengine STS / access tokens and long opaque secrets (>= 16 url-safe chars).
+_OPAQUE = re.compile(r"\b[A-Za-z0-9/+_-]{16,}={0,2}\b")
+# Explicit secret-bearing query/JSON/header fields.
+_FIELD = re.compile(
+    r"(?i)(\"?(?:access_token|refresh_token|id_token|client_secret|secret_access_key"
+    r"|secretkey|accesskeyid|accesskey|sessiontoken|session_token|authorization"
+    r"|apikey|api_key|token|password)\"?\s*[:=]\s*\"?(?:bearer\s+)?)"
+    r"([^\"&\s,}]+)"
+)
+
+
+def redact(text: str) -> str:
+    """Return ``text`` with credential-looking substrings replaced by ``***``."""
+    if not text:
+        return text
+    text = _FIELD.sub(lambda m: m.group(1) + "***", text)
+    text = _JWT.sub("***", text)
+    text = _OPAQUE.sub("***", text)
+    return text
+
+
+def mask(secret: str | None, *, keep: int = 4) -> str:
+    """Mask a secret, keeping only the last ``keep`` characters for recognition."""
+    if not secret:
+        return "<none>"
+    if len(secret) <= keep:
+        return "*" * len(secret)
+    return "*" * (len(secret) - keep) + secret[-keep:]

agentkit_sdk_python-0.6.0/agentkit/auth/_sigv4.py

@@ -0,0 +1,95 @@
+# 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.
+
+"""Volcengine SigV4 (HMAC-SHA256) request signer — stdlib only.
+
+A minimal, self-contained signer so :mod:`agentkit.auth` has no dependency on the
+``volcengine`` base SDK. Critically it supports an **STS session token**
+(``X-Security-Token``), which the base SDK's helpers do not always expose, so STS
+short-lived credentials can sign control-plane calls.
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import hmac
+import urllib.parse
+
+
+def _hmac(key: bytes, msg: str) -> bytes:
+    return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
+
+
+def sign_headers(
+    method: str,
+    host: str,
+    query: dict[str, str],
+    body: bytes,
+    *,
+    access_key: str,
+    secret_key: str,
+    service: str,
+    region: str,
+    session_token: str | None = None,
+    content_type: str = "application/json",
+    path: str = "/",
+) -> dict[str, str]:
+    """Sign a Volcengine OpenAPI request and return the full set of HTTP headers.
+
+    The returned dict can be replayed verbatim by any HTTP client; the signature
+    commits to ``content_type`` exactly, so callers must send that content type.
+    """
+    now = datetime.datetime.now(datetime.timezone.utc)
+    xdate = now.strftime("%Y%m%dT%H%M%SZ")
+    datestamp = xdate[:8]
+    payload_hash = hashlib.sha256(body).hexdigest()
+
+    signed: dict[str, str] = {
+        "content-type": content_type,
+        "host": host,
+        "x-content-sha256": payload_hash,
+        "x-date": xdate,
+    }
+    if session_token:
+        signed["x-security-token"] = session_token
+
+    signed_headers = ";".join(sorted(signed))
+    canon_headers = "".join(f"{k}:{signed[k]}\n" for k in sorted(signed))
+    canon_query = "&".join(
+        f"{urllib.parse.quote(k, safe='-_.~')}={urllib.parse.quote(str(v), safe='-_.~')}"
+        for k, v in sorted(query.items())
+    )
+    canon_req = f"{method}\n{path}\n{canon_query}\n{canon_headers}\n{signed_headers}\n{payload_hash}"
+
+    scope = f"{datestamp}/{region}/{service}/request"
+    string_to_sign = "\n".join(
+        ["HMAC-SHA256", xdate, scope, hashlib.sha256(canon_req.encode("utf-8")).hexdigest()]
+    )
+    k_signing = _hmac(_hmac(_hmac(_hmac(secret_key.encode("utf-8"), datestamp), region), service), "request")
+    signature = hmac.new(k_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+    headers = {
+        "Content-Type": content_type,
+        "Host": host,
+        "X-Date": xdate,
+        "X-Content-Sha256": payload_hash,
+        "Authorization": (
+            f"HMAC-SHA256 Credential={access_key}/{scope}, "
+            f"SignedHeaders={signed_headers}, Signature={signature}"
+        ),
+    }
+    if session_token:
+        headers["X-Security-Token"] = session_token
+    return headers