agentarts-sdk 0.1.0__py3-none-any.whl

agentarts/__init__.py

@@ -0,0 +1,22 @@
+"""
+Huawei Cloud AgentArts SDK
+
+Build, deploy and manage AI agents with cloud capabilities.
+
+Usage:
+    from agentarts.sdk import AgentArtsRuntimeApp, CodeInterpreter, MemoryClient
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agentarts-sdk")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__author__ = "Huawei Cloud AgentArts Team"
+
+__all__ = [
+    "__author__",
+    "__version__",
+]

agentarts/sdk/__init__.py

@@ -0,0 +1,60 @@
+"""
+Huawei Cloud AgentArts SDK
+
+Build, deploy and manage AI agents with cloud capabilities.
+
+Quick Start:
+    # Runtime
+    from agentarts.sdk import AgentArtsRuntimeApp, RequestContext
+    app = AgentArtsRuntimeApp()
+
+    # Tools
+    from agentarts.sdk import CodeInterpreter, code_session
+
+    # Memory
+    from agentarts.sdk import MemoryClient
+
+    # MCP Gateway
+    from agentarts.sdk import MCPGatewayClient
+
+    # Identity
+    from agentarts.sdk import require_access_token, require_api_key, IdentityClient
+"""
+
+import warnings
+
+import urllib3
+
+warnings.filterwarnings("ignore", message="Unverified HTTPS request")
+warnings.filterwarnings("ignore", category=urllib3.exceptions.InsecureRequestWarning)
+
+from agentarts import __author__, __version__
+from agentarts.sdk.identity import (
+    IdentityClient,
+    require_access_token,
+    require_api_key,
+    require_sts_token,
+)
+from agentarts.sdk.mcpgateway import MCPGatewayClient
+from agentarts.sdk.memory import MemoryClient
+from agentarts.sdk.runtime.app import AgentArtsRuntimeApp
+from agentarts.sdk.runtime.context import AgentArtsRuntimeContext, RequestContext
+from agentarts.sdk.runtime.model import PingStatus
+from agentarts.sdk.tools import CodeInterpreter, code_session
+
+__all__ = [
+    "AgentArtsRuntimeApp",
+    "AgentArtsRuntimeContext",
+    "CodeInterpreter",
+    "IdentityClient",
+    "MCPGatewayClient",
+    "MemoryClient",
+    "PingStatus",
+    "RequestContext",
+    "__author__",
+    "__version__",
+    "code_session",
+    "require_access_token",
+    "require_api_key",
+    "require_sts_token",
+]

agentarts/sdk/identity/__init__.py

@@ -0,0 +1,22 @@
+"""
+AgentArts Identity Module
+
+Provides authentication, authorization, and multi-tenant support.
+
+Usage:
+    from agentarts.sdk.identity import require_access_token, require_api_key, IdentityClient
+"""
+
+from agentarts.sdk.identity.auth import (
+    require_access_token,
+    require_api_key,
+    require_sts_token,
+)
+from agentarts.sdk.service.identity.identity_client import IdentityClient
+
+__all__ = [
+    "IdentityClient",
+    "require_access_token",
+    "require_api_key",
+    "require_sts_token",
+]

agentarts/sdk/identity/auth.py

@@ -0,0 +1,304 @@
+import asyncio
+import logging
+import uuid
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, Literal
+
+from agentarts.sdk.identity.config import Config
+from agentarts.sdk.runtime.context import (
+    AgentArtsRuntimeContext,
+    run_async_in_sync_context,
+)
+from agentarts.sdk.service.identity.identity_client import IdentityClient
+from agentarts.sdk.service.identity.polling.token_poller import TokenPoller
+from agentarts.sdk.utils.constant import get_region
+from huaweicloudsdkagentidentity.v1 import (
+    GetResourceStsTokenResponseBodyCredentials,
+    StsTag,
+    WorkloadIdentity,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def require_access_token(
+    *,
+    provider_name: str,
+    into: str = "access_token",
+    scopes: list[str] | None = None,
+    on_auth_url: Callable[[str], Any] | None = None,
+    auth_flow: Literal["M2M", "USER_FEDERATION"],
+    callback_url: str | None = None,
+    force_authentication: bool = False,
+    token_poller: TokenPoller | None = None,
+    custom_state: str | None = None,
+    custom_parameters: dict[str, str] | None = None,
+    ignore_ssl_verification: bool | None = None,
+) -> Callable:
+    """Decorator that fetches an OAuth2 access token before calling the decorated function.
+
+    Args:
+        provider_name: The credential provider name
+        into: Parameter name to inject the token into
+        scopes: OAuth2 scopes to request
+        on_auth_url: Callback for handling authorization URLs
+        auth_flow: Authentication flow type ("M2M" or "USER_FEDERATION")
+        callback_url: OAuth2 callback URL
+        force_authentication: Force re-authentication
+        token_poller: Custom token poller implementation
+        custom_state: A state that allows applications to verify the validity of callbacks to callback_url
+        custom_parameters: A map of custom parameters to include in authorization request to the credential provider
+                           Note: these parameters are in addition to standard OAuth 2.0 flow parameters
+        ignore_ssl_verification: Whether to ignore SSL verification
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs_func: Any) -> Any:
+            client = IdentityClient(
+                region=get_region(), ignore_ssl_verification=ignore_ssl_verification
+            )
+            token = await _get_resource_oauth2_token(client)
+            kwargs_func[into] = token
+            return await func(*args, **kwargs_func)
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs_func: Any) -> Any:
+            client = IdentityClient(
+                region=get_region(), ignore_ssl_verification=ignore_ssl_verification
+            )
+            token = run_async_in_sync_context(_get_resource_oauth2_token(client))
+            kwargs_func[into] = token
+            return func(*args, **kwargs_func)
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        return sync_wrapper
+
+    async def _get_resource_oauth2_token(client: IdentityClient) -> str:
+        """Common token fetching logic."""
+        return await client.get_resource_oauth2_token(
+            provider_name=provider_name,
+            workload_access_token=_get_workload_access_token(client),
+            scopes=scopes,
+            on_auth_url=on_auth_url,
+            auth_flow=auth_flow,
+            callback_url=_get_oauth2_callback_url(callback_url),
+            force_authentication=force_authentication,
+            token_poller=token_poller,
+            custom_state=_get_oauth2_custom_state(custom_state),
+            custom_parameters=custom_parameters,
+        )
+
+    return decorator
+
+
+def require_api_key(
+    *,
+    provider_name: str,
+    into: str = "api_key",
+    ignore_ssl_verification: bool | None = None,
+) -> Callable:
+    """Decorator that fetches an API key before calling the decorated function.
+
+    Args:
+        provider_name: The credential provider name
+        into: Parameter name to inject the API key into
+        ignore_ssl_verification: Whether to ignore SSL verification
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            client = IdentityClient(
+                region=get_region(), ignore_ssl_verification=ignore_ssl_verification
+            )
+            kwargs[into] = _get_api_key(client)
+            return await func(*args, **kwargs)
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            client = IdentityClient(
+                region=get_region(), ignore_ssl_verification=ignore_ssl_verification
+            )
+            kwargs[into] = _get_api_key(client)
+            return func(*args, **kwargs)
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        return sync_wrapper
+
+    def _get_api_key(client: IdentityClient):
+        return client.get_resource_api_key(
+            provider_name=provider_name,
+            workload_access_token=_get_workload_access_token(client),
+        )
+
+    return decorator
+
+
+def require_sts_token(
+    *,
+    provider_name: str,
+    agency_session_name: str,
+    duration_seconds: int | None = None,
+    policy: str | None = None,
+    source_identity: str | None = None,
+    tags: list[StsTag] | None = None,
+    transitive_tag_keys: list[str] | None = None,
+    into: str = "sts_credentials",
+    ignore_ssl_verification: bool | None = None,
+) -> Callable:
+    """Decorator that fetches an STS token before calling the decorated function.
+
+    The decorator injects STS credentials into the decorated function's keyword
+    arguments. The injected value is of type :class:`StsCredentials` (aliased from
+    ``GetResourceStsTokenResponseBodyCredentials``).
+
+    **Injected Type:** :class:`~agent_identity_dev_sdk.types.StsCredentials`
+
+    **Injected Type Attributes:**
+        - ``access_key_id`` (str): The access key ID for authentication
+        - ``secret_access_key`` (str): The secret access key for authentication
+        - ``security_token`` (str): The temporary security token
+        - ``expiration`` (str): The expiration time of the credentials
+
+    Args:
+        provider_name: The credential provider name
+        agency_session_name: An identifier for the assumed agency session.
+        duration_seconds: The duration, in seconds, of the agency session
+        policy: IAM policy to further restrict the permissions of the STS token
+        source_identity: The source identity specified by the user
+        tags: A list of session tags to apply to the STS token
+        transitive_tag_keys: A list of keys for session tags that are transitive
+        into: Parameter name to inject the STS token into
+        ignore_ssl_verification: Whether to ignore SSL verification
+
+    Returns:
+        Decorator function
+
+    Example:
+        >>> from agentarts.sdk import require_sts_token
+        >>> @require_sts_token(provider_name="huaweicloud-iam", agency_session_name="example-session")
+        ... async def access_resource(sts_credentials: StsCredentials | None = None):
+        ...     print(f"AK: {sts_credentials.access_key_id}")
+        ...     print(f"SK: {sts_credentials.secret_access_key}")
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            client = IdentityClient(
+                region=get_region(), ignore_ssl_verification=ignore_ssl_verification
+            )
+            kwargs[into] = _get_sts_token(client)
+            return await func(*args, **kwargs)
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            client = IdentityClient(
+                region=get_region(), ignore_ssl_verification=ignore_ssl_verification
+            )
+            kwargs[into] = _get_sts_token(client)
+            return func(*args, **kwargs)
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        return sync_wrapper
+
+    def _get_sts_token(client: IdentityClient) -> GetResourceStsTokenResponseBodyCredentials:
+        return client.get_resource_sts_token(
+            provider_name=provider_name,
+            workload_access_token=_get_workload_access_token(client),
+            agency_session_name=agency_session_name,
+            duration_seconds=duration_seconds,
+            policy=policy,
+            source_identity=source_identity,
+            tags=tags,
+            transitive_tag_keys=transitive_tag_keys,
+        )
+
+    return decorator
+
+
+def _get_workload_access_token(client: IdentityClient) -> str:
+    token = AgentArtsRuntimeContext.get_workload_access_token()
+    if token is not None:
+        logger.info("Retrieved workload access token from context")
+        return token
+    logger.info(
+        "No workload access token found in context. Falling back to local authentication setup."
+    )
+    return _set_up_local_auth(client)
+
+
+def _get_oauth2_callback_url(
+    user_provided_oauth2_callback_url: str | None,
+) -> str | None:
+    if user_provided_oauth2_callback_url:
+        return user_provided_oauth2_callback_url
+
+    return AgentArtsRuntimeContext.get_oauth2_callback_url()
+
+
+def _get_oauth2_custom_state(
+    user_provided_custom_state: str | None,
+) -> str | None:
+    if user_provided_custom_state:
+        return user_provided_custom_state
+
+    return AgentArtsRuntimeContext.get_oauth2_custom_state()
+
+
+def _set_up_local_auth(client: IdentityClient) -> str:
+    def _ensure_workload_identity(client: IdentityClient, config: Config) -> str:
+        """Ensure a workload identity exists, either from config or by creating it."""
+        workload_identity_name = config.workload_identity_name
+        if workload_identity_name:
+            logger.info(
+                "Found existing workload identity from %s: %s",
+                config.path.absolute(),
+                workload_identity_name,
+            )
+        else:
+            workload_identity: WorkloadIdentity = client.create_workload_identity()
+            logger.info("Created a workload identity")
+            workload_identity_name = workload_identity.name
+            config.workload_identity_name = workload_identity.name
+            config.save()
+        return workload_identity_name
+
+    def _ensure_user_id(config: Config) -> str:
+        """Ensure a user ID exists, checking context, then config, then generating one."""
+        user_id = AgentArtsRuntimeContext.get_user_id()
+        if user_id:
+            logger.info("Using user id from context: %s", user_id)
+        else:
+            user_id = config.user_id
+            if user_id:
+                logger.info(
+                    "Found existing user id from %s: %s",
+                    config.path.absolute(),
+                    user_id,
+                )
+            else:
+                user_id = uuid.uuid4().hex[:8]
+                logger.info("Created an user id")
+                config.user_id = user_id
+                config.save()
+        return user_id
+
+    config = Config.load()
+
+    workload_identity_name = _ensure_workload_identity(client, config)
+
+    user_id = _ensure_user_id(config)
+
+    return client.create_workload_access_token(workload_identity_name, user_id=user_id)

agentarts/sdk/identity/config.py

@@ -0,0 +1,36 @@
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+logger = logging.getLogger(__name__)
+
+
+class Config(BaseModel):
+    model_config = ConfigDict(validate_assignment=True)
+
+    workload_identity_name: str | None = None
+    user_id: str | None = None
+    path: Path = Field(default=Path(".agent_identity.json"), repr=False, exclude=True)
+
+    @classmethod
+    def load(cls, path: str = ".agent_identity.json") -> "Config":
+        config_path = Path(path)
+        if config_path.exists():
+            try:
+                with open(config_path, encoding="utf-8") as f:
+                    data: dict[str, Any] = json.load(f) or {}
+                    return cls(**data, path=config_path)
+            except Exception:
+                logger.warning("Could not load existing config from %s", path)
+        return cls(path=config_path)
+
+    def save(self) -> None:
+        try:
+            data: dict[str, Any] = self.model_dump()
+            with open(self.path, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+        except Exception:
+            logger.warning("Could not write config to %s", self.path)

agentarts/sdk/identity/types.py

@@ -0,0 +1,60 @@
+"""Type aliases for improved developer experience.
+
+This module provides user-friendly type aliases for types used throughout the SDK.
+These aliases make injected types discoverable without reading source code.
+"""
+
+import sys
+from typing import TypeAlias
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        pass
+
+
+from huaweicloudsdkagentidentity.v1 import (
+    CredentialProviderVendor,
+    GetResourceStsTokenResponseBodyCredentials,
+    Oauth2Discovery,
+)
+
+StsCredentials: TypeAlias = GetResourceStsTokenResponseBodyCredentials
+"""Type alias for STS token credentials.
+
+This type is injected by the @require_sts_token decorator into your function.
+
+Attributes:
+    access_key_id: The access key ID for authentication
+    secret_access_key: The secret access key for authentication
+    security_token: The temporary security token
+    expiration: The expiration time of the credentials
+
+Example:
+    >>> from agentarts.sdk.identity import require_sts_token, StsCredentials
+    >>> @require_sts_token(provider_name="huaweicloud-iam", agency_session_name="example-session")
+    ... async def my_func(sts_credentials: StsCredentials | None = None):
+    ...     print(sts_credentials.access_key_id)
+"""
+
+OAuth2Discovery: TypeAlias = Oauth2Discovery
+
+
+class OAuth2Vendor(StrEnum):
+    """OAuth2 credential provider vendors.
+
+    Values are sourced from the SDK's CredentialProviderVendor class constants.
+
+    Example:
+        >>> from agentarts.sdk.identity import OAuth2Vendor
+        >>> OAuth2Vendor.GOOGLEOAUTH2
+        'GoogleOauth2'
+    """
+
+    GITHUBOAUTH2 = CredentialProviderVendor.GITHUBOAUTH2
+    GOOGLEOAUTH2 = CredentialProviderVendor.GOOGLEOAUTH2
+    MICROSOFTOAUTH2 = CredentialProviderVendor.MICROSOFTOAUTH2
+    CUSTOMOAUTH2 = CredentialProviderVendor.CUSTOMOAUTH2

agentarts/sdk/integration/__init__.py

@@ -0,0 +1,65 @@
+"""
+AgentArts Framework Integration Module
+
+Provides adapters for popular agent frameworks with lazy loading support.
+
+Supported frameworks:
+- LangGraph (Priority)
+- LangChain
+- AutoGen
+- CrewAI
+
+Usage:
+    from agentarts.sdk.integration import LangGraphAdapter
+    adapter = LangGraphAdapter()
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentarts.sdk.integration.base import BaseAdapter, WrappedAgent
+    from agentarts.sdk.integration.langgraph import LangGraphAdapter
+
+__all__ = [
+    "BaseAdapter",
+    "LangGraphAdapter",
+    "WrappedAgent",
+]
+
+_ADAPTER_MODULES = {
+    "BaseAdapter": "agentarts.sdk.integration.base",
+    "WrappedAgent": "agentarts.sdk.integration.base",
+    "LangGraphAdapter": "agentarts.sdk.integration.langgraph",
+}
+
+
+def __getattr__(name: str):
+    """
+    Lazy import adapters with friendly error messages.
+
+    Only imports the corresponding module when the user actually uses
+    a specific adapter. Provides clear installation instructions if
+    dependencies are missing.
+    """
+    if name not in _ADAPTER_MODULES:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+
+    module_path = _ADAPTER_MODULES[name]
+
+    try:
+        import importlib
+        module = importlib.import_module(module_path)
+        return getattr(module, name)
+    except ImportError as e:
+        if name == "LangGraphAdapter":
+            msg = (
+                f"{name} requires the 'langgraph' extra to be installed. "
+                f"Install it with:\n"
+                f"  pip install agentarts-sdk[langgraph]\n"
+                f"Original error: {e}"
+            )
+            raise ImportError(
+                msg
+            ) from e
+        raise

agentarts/sdk/integration/langgraph/__init__.py

@@ -0,0 +1,23 @@
+"""
+AgentArts LangGraph Integration
+
+Provides adapter for LangGraph framework.
+"""
+
+from agentarts.sdk.integration.langgraph.config import CheckpointerConfig
+from agentarts.sdk.integration.langgraph.converter import (
+    langgraph_messages_to_memory,
+    langgraph_to_memory_message,
+    memory_messages_to_langgraph,
+    memory_to_langgraph_message,
+)
+from agentarts.sdk.integration.langgraph.saver import AgentArtsMemorySessionSaver
+
+__all__ = [
+    "AgentArtsMemorySessionSaver",
+    "CheckpointerConfig",
+    "langgraph_messages_to_memory",
+    "langgraph_to_memory_message",
+    "memory_messages_to_langgraph",
+    "memory_to_langgraph_message",
+]

agentarts/sdk/integration/langgraph/config.py

@@ -0,0 +1,100 @@
+"""
+Configuration for AgentArts LangGraph Integration
+
+Provides configuration classes for checkpoint saver and other LangGraph
+integration components.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+try:
+    from langchain_core.runnables import RunnableConfig
+
+    LANGGRAPH_AVAILABLE = True
+except ImportError:
+    LANGGRAPH_AVAILABLE = False
+    RunnableConfig = dict[str, Any]
+
+
+class CheckpointerConfig(BaseModel):
+    """
+    Runtime configuration for checkpoint operations.
+
+    This class holds runtime parameters extracted from LangGraph's RunnableConfig,
+    used during checkpoint save/load operations.
+
+    Attributes:
+        thread_id: Thread/conversation ID for session management
+        actor_id: Actor/user ID participating in the conversation
+        checkpoint_ns: Checkpoint namespace for isolation
+        checkpoint_id: Specific checkpoint ID for retrieval
+
+    Class Methods:
+        from_runnable_config: Extract configuration from LangGraph RunnableConfig
+
+    Usage:
+        >>> # From RunnableConfig
+        >>> runnable_config = {"configurable": {"thread_id": "conv-123"}}
+        >>> config = CheckpointerConfig.from_runnable_config(runnable_config)
+        >>> print(config.thread_id)  # "conv-123"
+    """
+
+    thread_id: str
+    actor_id: str = ""
+    assistant_id: str = ""
+    checkpoint_ns: str | None = None
+    checkpoint_id: str | None = None
+
+    @property
+    def session_id(self)->str:
+        return self.thread_id
+
+    @classmethod
+    def from_runnable_config(cls, config: RunnableConfig) -> CheckpointerConfig:
+        """
+        Extract CheckpointerConfig from LangGraph RunnableConfig.
+
+        Args:
+            config: LangGraph RunnableConfig containing configurable parameters
+
+        Returns:
+            CheckpointerConfig instance with extracted parameters
+        """
+        configurable = config.get("configurable", {})
+        if not configurable:
+            msg = "RunableConfig has no configurable parameters in AgentArtsMemorySessionSaver"
+            raise ValueError(msg)
+        thread_id = configurable.get("thread_id")
+        if not thread_id:
+            msg = "RunableConfig has no thread_id parameter in AgentArtsMemorySessionSaver"
+            raise ValueError(msg)
+
+        return cls(
+            thread_id=thread_id,
+            actor_id=configurable.get("actor_id", ""),
+            assistant_id=configurable.get("assistant_id", ""),
+            checkpoint_ns=configurable.get("checkpoint_ns"),
+            checkpoint_id=configurable.get("checkpoint_id"),
+        )
+
+    def to_runnable_config(self) -> RunnableConfig:
+        """
+        Convert to LangGraph RunnableConfig format.
+
+        Returns:
+            RunnableConfig dictionary with configurable parameters
+        """
+        configurable: dict[str, Any] = {"thread_id": self.thread_id}
+
+        if self.actor_id:
+            configurable["actor_id"] = self.actor_id
+        if self.checkpoint_ns is not None:
+            configurable["checkpoint_ns"] = self.checkpoint_ns
+        if self.checkpoint_id is not None:
+            configurable["checkpoint_id"] = self.checkpoint_id
+
+        return {"configurable": configurable}