sfdc-agentforce-byoc-python-sdk 0.1.0__py3-none-any.whl

agentforce_byoc/cli/main.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2026, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Main CLI entry point for Agentforce BYOC SDK."""
+
+import click
+
+from agentforce_byoc import __version__
+
+
+@click.group()
+@click.version_option(version=__version__)
+def cli():
+    """
+    Agentforce BYOC SDK - Build and deploy custom agents.
+
+    Commands:
+      init           Initialize a new agent project
+      run            Run agent locally against the Agentforce runtime
+      validate       Validate agent before deployment
+      zip            Create a deployment-ready package archive
+      package        Build end-to-end: validate -> run -> zip
+      deploy         Register + upload a packaged agent to Agentforce BYOC
+      deploy-status  Poll deployment status (read-only)
+      generate-schema  Generate an OpenAPI spec from @entry_func functions
+
+    Auth/identity for run + deploy + deploy-status come from env vars (required;
+    abort if unset): ORG_JWT_TOKEN, SFDC_CORE_TENANT_ID
+      (core/<instance>-<fd>/<org-id>), SFDC_USER_ID, SFDC_APP_CONTEXT.
+
+    Examples:
+      agentforce init my-agent
+      agentforce run main.py
+      agentforce zip
+      agentforce package
+      export ORG_JWT_TOKEN=<jwt> && export SFDC_CORE_TENANT_ID=core/<inst>-<fd>/<org> && export SFDC_USER_ID=<user-id> && export SFDC_APP_CONTEXT=<app-context>
+      agentforce deploy --package-name test --package-file test-0.1.0.tar.gz
+      agentforce deploy-status --package-name test --version 1.0
+    """
+    pass
+
+
+# Import commands to register them with the CLI group
+from agentforce_byoc.cli import commands  # noqa: E402, F401

agentforce_byoc/client.py

@@ -0,0 +1,224 @@
+# Copyright (c) 2026, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+"""Client for Agentforce BYOC SDK."""
+
+import os
+from typing import Any, Dict, Optional
+
+from agentforce_byoc.logging import get_logger
+from agentforce_byoc.runtime.base import BaseRuntimeProvider
+
+logger = get_logger(__name__)
+
+
+def _is_mock_mode() -> bool:
+    """Return True if mock mode is enabled via AGENTFORCE_BYOC_MOCK."""
+    return os.getenv("AGENTFORCE_BYOC_MOCK", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
+
+def _select_runtime_provider() -> BaseRuntimeProvider:
+    """
+    Select the runtime provider.
+
+    Mock mode (AGENTFORCE_BYOC_MOCK truthy) uses the mock provider; otherwise
+    the Agentforce BYOC runtime is used (default).
+    """
+    if _is_mock_mode():
+        logger.info("AGENTFORCE_BYOC_MOCK set - using MOCK runtime")
+        from agentforce_byoc.runtime.mock_runtime import MockRuntimeProvider
+
+        return MockRuntimeProvider()
+
+    from agentforce_byoc.runtime.agentforce_runtime import AgentforceRuntimeProvider
+
+    return AgentforceRuntimeProvider()
+
+
+class Client:
+    """
+    Main client for interacting with Agentforce services.
+
+    The Client selects the runtime (Agentforce BYOC by default, or mock when
+    AGENTFORCE_BYOC_MOCK is set) and provides a unified interface for relaying
+    calls through the Agentforce Relay API.
+
+    Features:
+    - Runtime selection via AGENTFORCE_BYOC_MOCK env var
+    - Singleton pattern (one instance per application)
+    - Relay calls for LLM generations and chat generations
+
+    Example:
+        >>> from agentforce_byoc import Client
+        >>> client = Client()
+        >>> response = client.call_llm_generations(
+        ...     parameter={"prompt": "What is AI?"},
+        ... )
+
+    Note:
+        Typically you don't instantiate Client directly - use Agent base class
+        which provides self.client automatically.
+    """
+
+    _instance: Optional["Client"] = None
+    _runtime_provider: Optional[BaseRuntimeProvider] = None
+
+    def __new__(cls, runtime_provider: Optional[BaseRuntimeProvider] = None):
+        """
+        Create or return singleton Client instance.
+
+        Args:
+            runtime_provider: Optional runtime provider (for testing/advanced use)
+
+        Returns:
+            Client singleton instance
+
+        Raises:
+            ValueError: If trying to change runtime provider after initialization
+        """
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+
+            # Select runtime if not provided
+            if runtime_provider is None:
+                cls._runtime_provider = _select_runtime_provider()
+            else:
+                cls._runtime_provider = runtime_provider
+
+            logger.info(f"Initialized Client with runtime: {cls._runtime_provider.name}")
+
+        elif runtime_provider is not None and cls._instance is not None:
+            raise ValueError(
+                "Cannot set runtime_provider after Client is initialized. "
+                "Create a new Client by resetting the singleton first."
+            )
+
+        return cls._instance
+
+    @classmethod
+    def reset(cls):
+        """
+        Reset the singleton instance.
+
+        Useful for testing when you need to reinitialize with different runtime.
+
+        Example:
+            >>> Client.reset()
+            >>> client = Client(custom_runtime_provider)
+        """
+        cls._instance = None
+        cls._runtime_provider = None
+
+    @property
+    def runtime(self) -> BaseRuntimeProvider:
+        """Get the current runtime provider."""
+        if self._runtime_provider is None:
+            raise RuntimeError("Client is not initialized with a runtime provider.")
+        return self._runtime_provider
+
+    def call_llm_generations(self, parameter: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Relay an LLM generations call through the Agentforce Relay API.
+
+        The tenant id, user id, and app context are resolved from the
+        environment (``SFDC_CORE_TENANT_ID`` / ``SFDC_USER_ID`` /
+        ``SFDC_APP_CONTEXT``) injected into the managed sandbox.
+
+        Args:
+            parameter: Raw request body, passed through to the Relay API as-is.
+
+        Returns:
+            The Relay API response envelope (``{body, requestId, traceId}``).
+
+        Raises:
+            RuntimeError: If the Relay API call fails, or the tenant id / user
+                id / app context environment variables are not set.
+            ValueError: If the tenant id cannot be resolved to an endpoint.
+        """
+        provider = self.runtime
+        logger.debug(
+            "Calling Relay (llm)",
+            extra={"runtime": provider.name},
+        )
+        return provider.relay_gateway_client.call_llm_generations(parameter=parameter)
+
+    def call_llm_chat_generations(self, parameter: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Relay an LLM chat generations call through the Agentforce Relay API.
+
+        The tenant id, user id, and app context are resolved from the
+        environment (``SFDC_CORE_TENANT_ID`` / ``SFDC_USER_ID`` /
+        ``SFDC_APP_CONTEXT``) injected into the managed sandbox.
+
+        Args:
+            parameter: Raw request body, passed through to the Relay API as-is.
+
+        Returns:
+            The Relay API response envelope (``{body, requestId, traceId}``).
+
+        Raises:
+            RuntimeError: If the Relay API call fails, or the tenant id / user
+                id / app context environment variables are not set.
+            ValueError: If the tenant id cannot be resolved to an endpoint.
+        """
+        provider = self.runtime
+        logger.debug(
+            "Calling Relay (llm_chat)",
+            extra={"runtime": provider.name},
+        )
+        return provider.relay_gateway_client.call_llm_chat_generations(parameter=parameter)
+
+
+# ============================================================================
+# Functional API
+# ============================================================================
+
+
+def get_client(runtime_provider: Optional[BaseRuntimeProvider] = None) -> Client:
+    """
+    Get the singleton Client instance (functional API).
+
+    This is the recommended way to access the client in functional-style code.
+    The client selects the runtime on first call.
+
+    Args:
+        runtime_provider: Optional runtime provider (for testing/advanced use)
+
+    Returns:
+        Client singleton instance
+
+    Example:
+        >>> from agentforce_byoc import get_client
+        >>>
+        >>> def function(request: dict) -> dict:
+        ...     client = get_client()
+        ...     response = client.call_llm_generations(
+        ...         parameter={"prompt": request.get("text", "")},
+        ...     )
+        ...     return {"response": response}
+
+    Runtime Selection:
+        - Agentforce BYOC runtime (default)
+        - Mock mode: AGENTFORCE_BYOC_MOCK is set (truthy)
+
+    Note:
+        The client is a singleton - calling get_client() multiple times
+        returns the same instance.
+    """
+    return Client(runtime_provider=runtime_provider)

agentforce_byoc/deploy_client.py

@@ -0,0 +1,246 @@
+# Copyright (c) 2026, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+"""HTTP client for the Agentforce BYOC deploy/upload API.
+
+Implements the two-step package upload against the Agentforce BYOC platform:
+
+1. ``POST <base>/byoc/upload/request`` to register package metadata AND obtain a
+   presigned upload URL in one call. The body carries ``packageName``,
+   ``version``, ``packageSize``, ``entryPoints``, and ``maxLiveDurationS``; the
+   response returns the presigned ``uploadUrl``.
+2. ``PUT`` the package archive to that presigned URL.
+
+Deployment status can then be polled read-only via
+``GET <base>/byoc/upload/status?packageName=&version=``, which reports
+``registrationStatus`` (is the package registered) and ``uploadStatus`` (has the
+archive been uploaded). That endpoint never writes — registration happens in
+step 1.
+
+The base URL is resolved by
+:func:`agentforce_byoc.gateway.relay_client.resolve_sfap_base_url` — from the
+``BYOC_PROXY_URL`` environment variable when set, else the production default.
+Auth is sent as ``Authorization: Bearer <org-jwt>`` plus the
+``x-sfdc-core-tenant-id``, ``x-sfdc-user-id``, and ``x-sfdc-app-context``
+headers.
+
+Uses only the Python standard library so nothing extra is bundled into a BYOC
+package.
+"""
+
+import json
+import urllib.parse
+from pathlib import Path
+from typing import Any, Dict, List, cast
+
+from agentforce_byoc import _http
+from agentforce_byoc.logging import get_logger
+
+logger = get_logger(__name__)
+
+# The presigned URL is signed for ContentType "application/gzip". The PUT must
+# send exactly this Content-Type or the upload is rejected as a signature
+# mismatch.
+_PACKAGE_CONTENT_TYPE = "application/gzip"
+
+# Timeout (seconds) for API calls and the package upload PUT.
+_DEPLOY_TIMEOUT_S = 120
+
+
+def _post_json(
+    url: str,
+    body: Dict[str, Any],
+    org_jwt: str,
+    tenant_id: str,
+    user_id: str,
+    app_context: str,
+) -> Dict[str, Any]:
+    """
+    POST a JSON body to a BYOC API endpoint and parse the response.
+
+    Sends the org JWT as a bearer token plus the tenant id, user id, and app
+    context as the ``x-sfdc-core-tenant-id`` / ``x-sfdc-user-id`` /
+    ``x-sfdc-app-context`` headers.
+
+    Raises:
+        RuntimeError: On HTTP error, transport error, or a non-JSON response.
+    """
+    # The org JWT is sent as a bearer token; the tenant id also travels as the
+    # x-sfdc-core-tenant-id header. A 400 "x-sfdc-core-tenant-id header is
+    # required" indicates the JWT was rejected, not a missing header here. The
+    # user id and app context identify who is deploying, matching the relay path.
+    headers = {
+        "Authorization": f"Bearer {org_jwt}",
+        "x-sfdc-core-tenant-id": tenant_id,
+        "x-sfdc-user-id": user_id,
+        "x-sfdc-app-context": app_context,
+    }
+    try:
+        status, raw = _http.post_json(url, body, headers, timeout=_DEPLOY_TIMEOUT_S)
+    except OSError as e:
+        raise RuntimeError(f"BYOC API call to {url} failed: {e}") from e
+
+    # Surface the BYOC API response (status + body) so callers can see exactly
+    # what the platform returned.
+    logger.info("BYOC API %s -> status=%s body=%s", url, status, raw)
+
+    if status >= 400:
+        raise RuntimeError(f"BYOC API call to {url} failed with status {status}: {raw}")
+
+    try:
+        return cast(Dict[str, Any], json.loads(raw))
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"BYOC API at {url} returned a non-JSON response: {raw!r}") from e
+
+
+def _get_json(
+    url: str,
+    org_jwt: str,
+    tenant_id: str,
+    user_id: str,
+    app_context: str,
+) -> Dict[str, Any]:
+    """
+    GET a BYOC API endpoint and parse the JSON response.
+
+    Sends the same identity headers as :func:`_post_json`. Used for the
+    read-only ``GET /byoc/upload/status`` poll, which takes its parameters in
+    the query string and has no request body.
+
+    Raises:
+        RuntimeError: On HTTP error, transport error, or a non-JSON response.
+    """
+    headers = {
+        "Authorization": f"Bearer {org_jwt}",
+        "x-sfdc-core-tenant-id": tenant_id,
+        "x-sfdc-user-id": user_id,
+        "x-sfdc-app-context": app_context,
+    }
+    try:
+        status, raw = _http.request("GET", url, headers=headers, timeout=_DEPLOY_TIMEOUT_S)
+    except OSError as e:
+        raise RuntimeError(f"BYOC API call to {url} failed: {e}") from e
+
+    body_text = raw.decode("utf-8", errors="replace")
+    logger.info("BYOC API %s -> status=%s body=%s", url, status, body_text)
+
+    if status >= 400:
+        raise RuntimeError(f"BYOC API call to {url} failed with status {status}: {body_text}")
+
+    try:
+        return cast(Dict[str, Any], json.loads(body_text))
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"BYOC API at {url} returned a non-JSON response: {body_text!r}") from e
+
+
+def _put_file(url: str, file_path: Path, content_type: str) -> None:
+    """
+    PUT a file's bytes to a (presigned) URL.
+
+    No auth header is added: the presigned URL carries its own signature.
+
+    Raises:
+        RuntimeError: On HTTP error or transport error.
+    """
+    data = file_path.read_bytes()
+    try:
+        status, raw = _http.request(
+            "PUT",
+            url,
+            headers={"Content-Type": content_type},
+            body=data,
+            timeout=_DEPLOY_TIMEOUT_S,
+        )
+    except OSError as e:
+        raise RuntimeError(f"Upload to presigned URL failed: {e}") from e
+
+    if status >= 400:
+        body_text = raw.decode("utf-8", errors="replace")
+        raise RuntimeError(f"Upload to presigned URL failed with status {status}: {body_text}")
+
+
+def request_presigned_upload(
+    base_url: str,
+    tenant_id: str,
+    org_jwt: str,
+    user_id: str,
+    app_context: str,
+    package_name: str,
+    version: str,
+    package_size: int,
+    entry_points: List[str],
+    max_live_duration_s: int,
+) -> Dict[str, Any]:
+    """
+    Step 1: register package metadata and get a presigned upload URL.
+
+    ``POST /byoc/upload/request`` does both in one call: it registers the
+    package metadata (``packageSize``, ``entryPoints``, ``maxLiveDurationS``) and
+    returns the presigned ``uploadUrl``. The caller then PUTs the archive to that
+    URL (see :func:`upload_package`).
+
+    Returns:
+        The response ``{uploadUrl, s3Key, tenantId, packageName, version,
+        uploadTime, packageSize, entryPoints, maxLiveDurationS, status}``.
+    """
+    url = f"{base_url}/byoc/upload/request"
+    body = {
+        "packageName": package_name,
+        "version": version,
+        "packageSize": package_size,
+        "entryPoints": entry_points,
+        "maxLiveDurationS": max_live_duration_s,
+    }
+    logger.info("Registering package + requesting presigned upload URL from %s", url)
+    return _post_json(url, body, org_jwt, tenant_id, user_id, app_context)
+
+
+def upload_package(upload_url: str, file_path: Path) -> None:
+    """Step 2: upload the package archive to the presigned URL."""
+    logger.info("Uploading %s (%d bytes)", file_path.name, file_path.stat().st_size)
+    _put_file(upload_url, file_path, _PACKAGE_CONTENT_TYPE)
+
+
+def get_upload_status(
+    base_url: str,
+    tenant_id: str,
+    org_jwt: str,
+    user_id: str,
+    app_context: str,
+    package_name: str,
+    version: str,
+) -> Dict[str, Any]:
+    """
+    Poll deployment status (read-only).
+
+    Calls ``GET /byoc/upload/status`` with ``packageName`` and ``version`` in the
+    query string. The endpoint never writes — registration happens in
+    :func:`request_presigned_upload`. It reports both halves of the two-phase
+    upload independently:
+
+    - ``registrationStatus``: ``"registered"`` if the package metadata exists,
+      else ``"unregistered"``.
+    - ``uploadStatus``: ``"uploaded"`` if the archive has been uploaded,
+      ``"pending"`` if not, ``"unknown"`` if the check itself failed.
+
+    Returns:
+        ``{tenantId, packageName, version, s3Key, registrationStatus,
+        uploadStatus, ...}`` (plus ``uploadTime``/``packageSize``/``entryPoints``/
+        ``maxLiveDurationS`` when registered).
+    """
+    query = urllib.parse.urlencode({"packageName": package_name, "version": version})
+    url = f"{base_url}/byoc/upload/status?{query}"
+    logger.info("Polling upload status from %s", url)
+    return _get_json(url, org_jwt, tenant_id, user_id, app_context)

agentforce_byoc/gateway/__init__.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2026, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+"""Gateway clients for external services."""
+
+from agentforce_byoc.gateway.base import BaseRelayGatewayClient
+from agentforce_byoc.gateway.mock_relay_client import MockRelayGatewayClient
+from agentforce_byoc.gateway.relay_client import AgentforceRelayGatewayClient
+
+__all__ = [
+    "BaseRelayGatewayClient",
+    "AgentforceRelayGatewayClient",
+    "MockRelayGatewayClient",
+]

agentforce_byoc/gateway/base.py

@@ -0,0 +1,66 @@
+# Copyright (c) 2026, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+"""Base class for relay gateway clients."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+
+class BaseRelayGatewayClient(ABC):
+    """
+    Abstract base class for Relay gateway clients.
+
+    The Relay gateway routes API calls from BYOC code (running in the managed
+    sandbox, which has no direct outbound network) through the Agentforce Relay
+    API. Each relay function is exposed as a method.
+
+    Implementations must relay the raw ``parameter`` body through to the
+    Relay API unchanged.
+    """
+
+    @abstractmethod
+    def call_llm_generations(self, parameter: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Relay an LLM generations call (Relay function ``llm``).
+
+        The tenant id, user id, and app context are resolved from the
+        environment (``SFDC_CORE_TENANT_ID`` / ``SFDC_USER_ID`` /
+        ``SFDC_APP_CONTEXT``) injected into the managed sandbox.
+
+        Args:
+            parameter: Raw request body, passed through to the Relay API as-is.
+
+        Returns:
+            The Relay API response envelope (``{body, requestId, traceId}``).
+        """
+        ...
+
+    @abstractmethod
+    def call_llm_chat_generations(self, parameter: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Relay an LLM chat generations call (Relay function ``llm_chat``).
+
+        The tenant id, user id, and app context are resolved from the
+        environment (``SFDC_CORE_TENANT_ID`` / ``SFDC_USER_ID`` /
+        ``SFDC_APP_CONTEXT``) injected into the managed sandbox.
+
+        Args:
+            parameter: Raw request body, passed through to the Relay API as-is.
+
+        Returns:
+            The Relay API response envelope (``{body, requestId, traceId}``).
+        """
+        ...

agentforce_byoc/gateway/mock_relay_client.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2026, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+"""Mock Relay gateway client for local development."""
+
+import os
+from typing import Optional
+
+from agentforce_byoc.gateway.relay_client import ORG_JWT_ENV_VAR, AgentforceRelayGatewayClient
+from agentforce_byoc.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class MockRelayGatewayClient(AgentforceRelayGatewayClient):
+    """
+    Relay gateway client for local development outside the managed sandbox.
+
+    Behaves exactly like :class:`AgentforceRelayGatewayClient` — same URL
+    resolution, request shape, and transport — except the org JWT is supplied
+    by the SDK author rather than injected by the runtime. The JWT is taken
+    from the ``org_jwt`` constructor argument, falling back to the
+    ``ORG_JWT_TOKEN`` environment variable.
+    """
+
+    def __init__(self, org_jwt: Optional[str] = None):
+        self._org_jwt = org_jwt
+
+    def _get_org_jwt(self) -> str:
+        """
+        Resolve the org JWT from the constructor arg or ``ORG_JWT_TOKEN``.
+
+        Raises:
+            RuntimeError: If neither source provides a JWT.
+        """
+        org_jwt = self._org_jwt or os.getenv(ORG_JWT_ENV_VAR)
+        if not org_jwt:
+            raise RuntimeError(
+                f"No org JWT supplied for mock mode. Pass org_jwt=... or "
+                f"export {ORG_JWT_ENV_VAR}."
+            )
+        return org_jwt