From 873a0a6b3a72aeb005b2ebadefa34a2c5d273f2d Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 16:05:06 -0500 Subject: [PATCH 01/20] Add broken links as TODOs --- docs-python/getting-started.mdx | 38 ++++++++++++++++++++ docs-python/overview.mdx | 53 ++++++++++++++++++++++++++++ docs-python/release-notes.mdx | 30 ++++++++++++++++ docs-python/support.mdx | 31 +++++++++++++++++ docs-python/troubleshooting.mdx | 61 +++++++++++++++++++++++++++++++++ docs/about.mdx | 1 + docusaurus.config.js | 27 ++++++++++++++- sidebarsDocsPython.js | 9 +++++ 8 files changed, 249 insertions(+), 1 deletion(-) create mode 100644 docs-python/getting-started.mdx create mode 100644 docs-python/overview.mdx create mode 100644 docs-python/release-notes.mdx create mode 100644 docs-python/support.mdx create mode 100644 docs-python/troubleshooting.mdx create mode 100644 sidebarsDocsPython.js diff --git a/docs-python/getting-started.mdx b/docs-python/getting-started.mdx new file mode 100644 index 00000000000..82482f00903 --- /dev/null +++ b/docs-python/getting-started.mdx @@ -0,0 +1,38 @@ +--- +id: getting-started +title: Getting Started +hide_title: false +hide_table_of_contents: false +sidebar_label: Getting Started +description: Get up to speed with the SAP Cloud SDK for Python in no time +keywords: + - sap + - cloud + - sdk + - cloud native + - cloud sdk + - sap cloud sdk + - python +--- + +## What Is the SAP Cloud SDK + +The SAP Cloud SDK is a set of libraries that helps you end-to-end when developing applications on SAP Business Technology Platform that communicate with SAP solutions and services such as SAP S/4HANA, SAP S/4HANA Cloud, SAP SuccessFactors, and many others. + +## Installation + +Install the SAP Cloud SDK for Python from [PyPI](https://pypi.org/search/?q=sap-cloud-sdk): + +```bash +pip install sap-cloud-sdk +``` + +## Sample Projects + +- TODO: Sample projects + +## Tutorials + +Check out the tutorials to get started with the SAP Cloud SDK for Python. + +- TODO: Tutorial Link \ No newline at end of file diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx new file mode 100644 index 00000000000..b6853a14508 --- /dev/null +++ b/docs-python/overview.mdx @@ -0,0 +1,53 @@ +--- +id: overview +title: Overview +hide_title: false +hide_table_of_contents: false +sidebar_label: Overview +description: The SAP Cloud SDK for Python significantly simplifies extending and developing applications with the SAP Business Technology Platform +keywords: + - sap + - cloud + - sdk + - cloud native + - cloud sdk + - sap cloud sdk + - python +--- + +## Quick Start + +For a quick start check out the ["Getting Started"](./getting-started.mdx) page. + +## What is the SAP Cloud SDK for Python? + +The SAP Cloud SDK for Python is a set of libraries that reduces the effort of building applications on the SAP Business Technology Platform (SAP BTP). +It abstracts common tasks on SAP BTP so that you can concentrate on the business logic instead of writing boilerplate code. + +### The Core Libraries + +The core libraries are the heart of the SAP Cloud SDK for Python. +They contain the request execution and connectivity logic as well as command line interfaces (CLIs) to generate OData and OpenAPI clients. + +Install the core libraries via pip: + +```bash +pip install sap-cloud-sdk +``` + +## Supported Python Versions + +| Python Version | Supported | +| -------------- | --------- | +| 3.12 | ✅ | +| 3.11 | ✅ | +| 3.10 | ✅ | +| 3.9 | ✅ | + +## Licensing + +The SAP Cloud SDK for Python is open-source and available under the [Apache 2.0 license](https://github.com/SAP/cloud-sdk-python/blob/main/LICENSE). + +## Feature Matrix + +For a complete overview of supported features, \ No newline at end of file diff --git a/docs-python/release-notes.mdx b/docs-python/release-notes.mdx new file mode 100644 index 00000000000..8fe208a6ae6 --- /dev/null +++ b/docs-python/release-notes.mdx @@ -0,0 +1,30 @@ +--- +id: release-notes +title: Release Notes +sidebar_label: Release Notes +description: Release notes of the SAP Cloud SDK for Python, stay up to date with the recent features, fixes, dependency updates, and recommendations. +keywords: + - sap + - cloud + - sdk + - cloud-native + - cloud sdk + - sap cloud sdk + - python +--- + + + + +## 1.0.0 - August 12, 2026 + +### New Features + +- Initial release of the SAP Cloud SDK for Python. +- Connectivity abstractions for SAP BTP: handling destinations, proxies, and authentication for cloud and on-premise systems. +- Support for OData v2 and v4 client generation. +- Support for OpenAPI client generation. + +### Fixed Issues + +- None. diff --git a/docs-python/support.mdx b/docs-python/support.mdx new file mode 100644 index 00000000000..71d0d59bb8f --- /dev/null +++ b/docs-python/support.mdx @@ -0,0 +1,31 @@ +--- +id: support +title: Support +sidebar_label: Support +description: If you're stuck and can't find a solution to your problem with SAP Cloud SDK for Python, we're here to help you. +keywords: + - sap + - cloud + - sdk + - cloud native + - cloud sdk + - sap cloud sdk + - python +--- + +:::caution +Be sure to remove **any confidential** information (examples: credentials or internal URLs) before publishing the issue on the internet. +::: + +## Support Channels + +### GitHub + +Please, create an issue in one of the public repositories of the SAP Cloud SDK. + +- **Python open source Repository**: ask a question, give feedback or create an issue [here](https://github.com/SAP/cloud-sdk-python/issues/new/choose). +- **Documentation**: request documentation or suggest fixes [here](https://github.com/SAP/cloud-sdk/issues/new/choose). + +### Stack Overflow + +Use the `sap-cloud-sdk` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sap-cloud-sdk) to search for solved issues or create yours. diff --git a/docs-python/troubleshooting.mdx b/docs-python/troubleshooting.mdx new file mode 100644 index 00000000000..361cb5abb27 --- /dev/null +++ b/docs-python/troubleshooting.mdx @@ -0,0 +1,61 @@ +--- +id: troubleshooting +title: Troubleshooting +hide_title: false +hide_table_of_contents: false +sidebar_label: Troubleshooting +description: Troubleshooting guide for the SAP Cloud SDK for Python +keywords: + - sap + - cloud + - sdk + - cloud native + - cloud sdk + - sap cloud sdk + - python + - troubleshooting + - connectivity +--- + +## Installation Issues + +### `pip install sap-cloud-sdk` Fails + +If the installation fails, ensure you are using a supported Python version (3.9 or higher) and that pip is up to date: + +```bash +python -m pip install --upgrade pip +pip install sap-cloud-sdk +``` + +If you are working in a virtual environment, make sure it is activated before running the install command. + +### ImportError After Installation + +If you see an `ImportError` after a successful installation, verify that the package was installed into the correct Python environment: + +```bash +python -c "import sap.cloud.sdk; print(sap.cloud.sdk.__version__)" +``` + +If the import fails, the package may have been installed into a different Python environment than the one you are running. Use `python -m pip install sap-cloud-sdk` to ensure the package is installed for the active interpreter. + +## Connectivity Issues + +### Destination Not Found + +If a destination cannot be resolved, check the following: + +1. The destination name is spelled correctly (case-sensitive). +2. The `VCAP_SERVICES` environment variable is set when running locally. +3. The destination service binding is present and correctly configured. + +For more information, see the connectivity documentation. + +### Authentication Failures + +If requests fail with an authentication error: + +1. Verify the credentials in your destination configuration. +2. Check that the authentication type matches what the target system expects. +3. Ensure the service key for the Destination Service has the required permissions. diff --git a/docs/about.mdx b/docs/about.mdx index 33abc1a064d..2ba7b1889ad 100644 --- a/docs/about.mdx +++ b/docs/about.mdx @@ -24,6 +24,7 @@ The SAP Cloud SDK is available in two flavors: - [SAP Cloud SDK for Java](/docs/java/overview-cloud-sdk-for-java) - [SAP Cloud SDK for JavaScript](/docs/js/overview) +- [SAP Cloud SDK for Python](/docs/python/overview) ## Capabilities diff --git a/docusaurus.config.js b/docusaurus.config.js index b76d12bce94..e6c82612bc2 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -39,7 +39,7 @@ module.exports = { disableSwitch: true }, prism: { - additionalLanguages: ['powershell', 'java', 'groovy'], + additionalLanguages: ['powershell', 'java', 'groovy', 'python'], theme: require('prism-react-renderer').themes.github, darkTheme: require('prism-react-renderer').themes.dracula }, @@ -79,6 +79,14 @@ module.exports = { activeBasePath: 'docs/js', sdkSwitch: true }, + { + label: '🐍 Python', + to: 'docs/python/overview', + position: 'left', + docsPluginId: 'docs-python', + activeBasePath: 'docs/python', + sdkSwitch: true + }, { label: 'SAP Cloud SDK for AI', href: 'https://sap.github.io/ai-sdk', @@ -270,6 +278,23 @@ module.exports = { } } ], + [ + '@docusaurus/plugin-content-docs', + { + id: 'docs-python', + path: 'docs-python', + editUrl: 'https://github.com/SAP/cloud-sdk/edit/main', + routeBasePath: 'docs/python', + sidebarPath: require.resolve('./sidebarsDocsPython.js'), + lastVersion: 'current', + versions: { + current: { + label: 'v1', + badge: false + } + } + } + ], [ '@docusaurus/plugin-client-redirects', { diff --git a/sidebarsDocsPython.js b/sidebarsDocsPython.js new file mode 100644 index 00000000000..a92b4474759 --- /dev/null +++ b/sidebarsDocsPython.js @@ -0,0 +1,9 @@ +module.exports = { + docsPythonSidebar: [ + 'overview', + 'getting-started', + 'release-notes', + 'support', + 'troubleshooting' + ] +}; From 8eb4c7c9500c8690f1e41b5aa856af6188fd9658 Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 16:42:41 -0500 Subject: [PATCH 02/20] refactoring overview and adding module examples --- docs-python/getting-started.mdx | 4 +- docs-python/overview.mdx | 179 +++++++++++++++++++++++++++++--- 2 files changed, 166 insertions(+), 17 deletions(-) diff --git a/docs-python/getting-started.mdx b/docs-python/getting-started.mdx index 82482f00903..f34fc0ba0df 100644 --- a/docs-python/getting-started.mdx +++ b/docs-python/getting-started.mdx @@ -15,13 +15,13 @@ keywords: - python --- -## What Is the SAP Cloud SDK +## What is the SAP Cloud SDK The SAP Cloud SDK is a set of libraries that helps you end-to-end when developing applications on SAP Business Technology Platform that communicate with SAP solutions and services such as SAP S/4HANA, SAP S/4HANA Cloud, SAP SuccessFactors, and many others. ## Installation -Install the SAP Cloud SDK for Python from [PyPI](https://pypi.org/search/?q=sap-cloud-sdk): +Install the SAP Cloud SDK for Python from [PyPI](https://pypi.org/project/sap-cloud-sdk/): ```bash pip install sap-cloud-sdk diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index b6853a14508..02f03036886 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -17,37 +17,186 @@ keywords: ## Quick Start -For a quick start check out the ["Getting Started"](./getting-started.mdx) page. +For a quick start check out the [Getting Started](./getting-started.mdx) page. -## What is the SAP Cloud SDK for Python? +## Why the SAP Cloud SDK for Python? -The SAP Cloud SDK for Python is a set of libraries that reduces the effort of building applications on the SAP Business Technology Platform (SAP BTP). -It abstracts common tasks on SAP BTP so that you can concentrate on the business logic instead of writing boilerplate code. +The SAP Cloud SDK for Python makes it easy to build cloud-native applications on the SAP Business Technology Platform (SAP BTP). +It provides consistent, type-safe interfaces for the foundational BTP and SAP services — destination management, identity, audit logging, storage, telemetry, and more — so you can focus on business logic instead of boilerplate integration code. -### The Core Libraries +Below, you will find main features described with examples. -The core libraries are the heart of the SAP Cloud SDK for Python. -They contain the request execution and connectivity logic as well as command line interfaces (CLIs) to generate OData and OpenAPI clients. +## Main Features -Install the core libraries via pip: +### Destination Service -```bash -pip install sap-cloud-sdk +The Destination Service module provides an abstraction for connecting to remote systems defined in the SAP BTP Cockpit. +It resolves credentials, handles OAuth flows (including principal propagation and client credentials), and supports both cloud and on-premise systems via the SAP Connectivity Service. + +```python +from sap.cloud.sdk.destination import DestinationService + +service = DestinationService() +destination = service.get_destination("my-destination") +``` + +### Identity and Access (IAS) + +The Identity and Access Service (IAS) module handles authentication and token management for applications secured with SAP Cloud Identity Services. +It provides utilities for token verification, user context propagation, and service-to-service authentication. + +### AI Core + +The AI Core module provides a client for [SAP AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from Python applications. +It integrates with the SDK's credential and destination resolution to simplify connection setup. + +```python +from sap.cloud.sdk.ai_core import AICoreClient + +client = AICoreClient() +deployments = client.list_deployments(resource_group="default") +``` + +### Audit Logging + +The Audit Logging module provides a structured way to emit audit log events to the SAP Audit Log Service. +Both the standard and the next-generation (NG) audit log APIs are supported. + +```python +from sap.cloud.sdk.audit_log import AuditLogger + +logger = AuditLogger() +logger.log_data_access(object_type="BusinessPartner", object_id="1000001", attributes=["Name", "Address"]) +``` + +### Secret Management + +The Secret Management module provides a unified interface for reading credentials and secrets. +The SDK resolves secrets from multiple sources in priority order: + +1. Kubernetes-mounted secrets via `SERVICE_BINDING_ROOT` (following the [servicebinding.io](https://servicebinding.io/) specification) +2. Environment variables using the pattern `CLOUD_SDK_CFG___` + +This means the same application code works locally (using env vars) and in Kubernetes (using mounted secrets) without modification. + +### Telemetry + +The Telemetry module provides observability utilities built on top of [OpenTelemetry](https://opentelemetry.io/). +It instruments SDK operations with traces and metrics that can be exported to any OpenTelemetry-compatible backend such as SAP Cloud Logging. + +### Object Storage and Document Management + +The Object Storage and Document Management modules provide clients for SAP BTP's storage services, allowing you to upload, download, and manage files and documents directly from your Python application. + +### Agent Framework + +The Agent module provides building blocks for creating AI-powered agents on SAP BTP. + +#### Decorators + +Annotate Python functions with `@tool` to register them as callable tools within the agent loop. +The decorator forwards the function's type annotations as the tool's input schema and the `description` to the LLM. + +```python +from sap_cloud_sdk.agent import tool + +@tool(description="Fetch the order status for a given order ID.") +def get_order_status(order_id: str) -> str: + # your business logic here + return f"Order {order_id} is currently: In Transit" +``` + +#### Agent Gateway Service + +The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents. +It discovers MCP tools exposed by connected SAP LoB systems (such as SAP S/4HANA and SAP SuccessFactors) and wraps them as LangChain-compatible tools ready for use in an agent loop. + +```python +from sap_cloud_sdk.agentgateway import create_client +from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain + +agw_client = create_client(tenant_subdomain=get_tenant_subdomain) +mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) +tools = [ + mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) + for t in mcp_tools +] +``` + +:::note +`get_tenant_subdomain` and `get_user_token` should be callables (for example, functions reading from contextvars) so that credentials are resolved per request and never captured at construction time. +::: + +#### Agent Memory Service + +The Agent Memory Service provides a persistent, tenant-isolated store backed by SAP HANA Cloud. +It exposes two APIs: a **Messages API** for short-term conversation history, and a **Memories API** for long-term semantic search across sessions. + +```python +from sap_cloud_sdk.agent_memory import create_client, MessageRole + +client = create_client(tenant=tenant_subdomain) + +# Store a conversation turn +client.add_message( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, role=MessageRole.USER, content=query +) +client.add_message( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, role=MessageRole.ASSISTANT, content=response +) + +# Replay history for a returning session +messages = client.list_messages( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, limit=50 +) +``` + +Use the Memories API to persist and retrieve facts across sessions with semantic similarity search: + +```python +# Store a long-term fact +client.add_memory(agent_id="my-agent", invoker_id=user_id, + content="User prefers responses in English.") + +# Retrieve relevant memories before answering +results = client.search_memories( + agent_id="my-agent", invoker_id=user_id, + query="preferred language", threshold=0.6, limit=5 +) +for r in results: + print(f"[{r.similarity:.2f}] {r.content}") ``` ## Supported Python Versions +The SAP Cloud SDK for Python requires **Python 3.11 or higher**. + | Python Version | Supported | | -------------- | --------- | +| 3.13 | ✅ | | 3.12 | ✅ | | 3.11 | ✅ | -| 3.10 | ✅ | -| 3.9 | ✅ | +| 3.10 | ❌ | + +## Supported Environments + +The SAP Cloud SDK for Python is designed to run on any environment supported by SAP BTP: + +1. [SAP BTP Cloud Foundry](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9c7092c7b7ae4d49bc8ae35fdd0e0b18.html) +2. [Kubernetes / SAP Gardener](https://gardener.cloud/) +3. [SAP BTP Kyma](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/468c2f3c3ca24c2c8497ef9f83154c44.html) ## Licensing -The SAP Cloud SDK for Python is open-source and available under the [Apache 2.0 license](https://github.com/SAP/cloud-sdk-python/blob/main/LICENSE). +The SAP Cloud SDK for Python is open-source and available on [PyPI](https://pypi.org/project/sap-cloud-sdk/) under the [Apache 2.0 license](https://github.com/SAP/cloud-sdk-python/blob/main/LICENSE). + +## Release Schedule + +For details on the release cadence and version support, check the [release policy](./release-policy.mdx). -## Feature Matrix +## Contributing -For a complete overview of supported features, \ No newline at end of file +For details on contributing, check the [contribution guide](https://github.com/SAP/cloud-sdk/blob/main/CONTRIBUTING.md). From 17d9b88e92e770457e1f9bc5d315ebd1f367950f Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 16:47:05 -0500 Subject: [PATCH 03/20] refactoring release-notes and adding recent improvements --- docs-python/release-notes.mdx | 89 ++++++++++++++++++++++++++++++++--- 1 file changed, 83 insertions(+), 6 deletions(-) diff --git a/docs-python/release-notes.mdx b/docs-python/release-notes.mdx index 8fe208a6ae6..0d8078d9702 100644 --- a/docs-python/release-notes.mdx +++ b/docs-python/release-notes.mdx @@ -16,15 +16,92 @@ keywords: -## 1.0.0 - August 12, 2026 +:::info v1.0.0 Release Candidate Coming Soon +We are working toward the first stable release of the SAP Cloud SDK for Python. +A **v1.0.0 release candidate** will be published in the near future, marking the stabilization of the public APIs. +If you are evaluating the SDK, we encourage you to test the latest pre-release version and share feedback via [GitHub Issues](https://github.com/SAP/cloud-sdk-python/issues). +::: + +## 0.43.2 - August 12, 2026 + +### Improvements + +- Renamed OpenTelemetry resource attribute `sap.cld.subaccount_id` to `sap.cloud.provider.subaccount_id` to align with SAP cloud naming conventions. + +## 0.43.1 - August 12, 2026 + +### Fixed Issues + +- `AuthToken` now surfaces error messages returned by the Destination Service when the service response contains non-empty error fields. +- Improved token validation handling for error-carrying tokens with empty `type` or `value` fields. + +## 0.43.0 - August 10, 2026 + +### Compatibility Notes + +- The `APPFND_UMS_DESTINATION_NAME` environment variable has been removed. Use `ExtensibilityConfig(destination_name="...")` instead. +- The UMS destination name prefix changed from `sap-managed-runtime-ums-` to `sap-managed-runtime-ias-`. +- `APPFND_CONHOS_UMS_URL` is now required; the UMS base URL is no longer read from the destination's URL field. + +### Improvements + +- Deferred destination-name resolution failure to fetch time for clearer error reporting. +- Enhanced error messaging for misconfigured extensibility settings. + +## 0.42.0 - August 7, 2026 ### New Features -- Initial release of the SAP Cloud SDK for Python. -- Connectivity abstractions for SAP BTP: handling destinations, proxies, and authentication for cloud and on-premise systems. -- Support for OData v2 and v4 client generation. -- Support for OpenAPI client generation. +- `bootstrap(app)` now automatically sets up telemetry as part of SDK runtime initialization — no separate telemetry configuration call needed. + +## 0.41.0 - August 7, 2026 + +### New Features + +- `list_mcp_tools()` on the Agent Gateway client now accepts an optional `MCPToolFilter` parameter to narrow discovered tools by name and/or ORD ID. + +## 0.40.1 - August 7, 2026 + +### Improvements + +- Updated OpenTelemetry core from 1.42.1 to 1.43.0. +- Updated OpenTelemetry instrumentation packages from 0.63b1 to 0.64b0. +- Updated Protobuf minimum requirement to `>=7.0.0`. + +## 0.40.0 - August 4, 2026 + +### New Features + +- New `sap_cloud_sdk.outputmanagement` module for integrating with the SAP Output Management Service. + Available operations: `send_email`, `send_email_with_mcp`, `create_output_request`, `send_output_request`. +- `DestinationCredentialConfig` now supports `PROVIDER_ONLY` and `SUBSCRIBER_ONLY` access strategies. +- Full OpenTelemetry telemetry support for the Output Management client. + +## 0.39.1 - August 3, 2026 ### Fixed Issues -- None. +- Agent Gateway: `get_mcp_tools_customer` now returns an empty list instead of raising an error when `integrationDependencies` is empty. +- Improved MCP server error logging to include HTTP status codes and response bodies. +- Improved tool invocation error logging. +- Fixed `streamable_http_client` unpacking compatibility. + +## 0.39.0 - July 24, 2026 + +### New Features + +- New `bootstrap(app)` entry point for SDK runtime initialization — replaces manual per-feature setup. +- New `sap_cloud_sdk.core.runtime_context` module with provider-agnostic context handling. + Supported context providers: `IASContextProvider`, `SAPTriggerContextProvider`, `DWCContextProvider`. +- `auto_instrument()` now automatically instruments supported HTTP clients, frameworks, and libraries including: httpx, requests, grpcio, Starlette, FastAPI, aiohttp, Django, Flask, SQLAlchemy, Redis, and logging. + +## 0.38.0 - July 22, 2026 + +### New Features + +- `AuditClient.send()` now auto-injects tenant and user context into audit log events. +- New `ias/_context.py` module exposing `set_auth_context` and `get_auth_context` APIs for IAS token propagation. + +### Improvements + +- `StarletteIASTelemetryMiddleware` refactored for improved token parsing reliability. From 06c52cde77750b32057087c2965feb4bfcf96fce Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 16:54:24 -0500 Subject: [PATCH 04/20] including troubleshooting cases --- docs-python/overview.mdx | 8 +- docs-python/troubleshooting.mdx | 220 +++++++++++++++++++++++++++++--- 2 files changed, 205 insertions(+), 23 deletions(-) diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index 02f03036886..2f14db56149 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -183,11 +183,7 @@ The SAP Cloud SDK for Python requires **Python 3.11 or higher**. ## Supported Environments -The SAP Cloud SDK for Python is designed to run on any environment supported by SAP BTP: - -1. [SAP BTP Cloud Foundry](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9c7092c7b7ae4d49bc8ae35fdd0e0b18.html) -2. [Kubernetes / SAP Gardener](https://gardener.cloud/) -3. [SAP BTP Kyma](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/468c2f3c3ca24c2c8497ef9f83154c44.html) +The SAP Cloud SDK for Python is currently focused in Agentic use-cases running in the Joule Studio Runtime. ## Licensing @@ -195,7 +191,7 @@ The SAP Cloud SDK for Python is open-source and available on [PyPI](https://pypi ## Release Schedule -For details on the release cadence and version support, check the [release policy](./release-policy.mdx). +For details on the release cadence and version support, check the TODO: release policy document. ## Contributing diff --git a/docs-python/troubleshooting.mdx b/docs-python/troubleshooting.mdx index 361cb5abb27..cd1e6252ba1 100644 --- a/docs-python/troubleshooting.mdx +++ b/docs-python/troubleshooting.mdx @@ -17,45 +17,231 @@ keywords: - connectivity --- -## Installation Issues +## Solving Common Problems + +- Check if you are using the [latest release](./release-notes.mdx) — new fixes ship frequently. +- Search [Stack Overflow](https://stackoverflow.com/questions/tagged/sap-cloud-sdk) with the `sap-cloud-sdk` tag for solved issues. +- Check this page for known solutions to the most common problems. +- If nothing helps, [open an issue on GitHub](https://github.com/SAP/cloud-sdk-python/issues). + +--- + +## Installation ### `pip install sap-cloud-sdk` Fails -If the installation fails, ensure you are using a supported Python version (3.9 or higher) and that pip is up to date: +:::info Symptoms +The installation fails with a resolver error or a Python version warning. +::: + +Ensure you are using Python 3.11 or higher and that pip is up to date: ```bash +python --version # must be 3.11+ python -m pip install --upgrade pip pip install sap-cloud-sdk ``` If you are working in a virtual environment, make sure it is activated before running the install command. -### ImportError After Installation +### `ImportError` After Installation + +:::info Symptoms +`import sap_cloud_sdk` raises `ModuleNotFoundError` even though `pip install` succeeded. +::: + +The package was likely installed into a different Python interpreter than the one you are running. +Use `python -m pip` to guarantee the active interpreter is the target: + +```bash +python -m pip install sap-cloud-sdk +python -c "import sap_cloud_sdk; print(sap_cloud_sdk.__version__)" +``` + +### Dependency Conflict After Upgrading + +:::info Symptoms +After upgrading `sap-cloud-sdk`, an `ImportError` or `AttributeError` appears at runtime, or another package such as `a2a-sdk` stops working. +::: -If you see an `ImportError` after a successful installation, verify that the package was installed into the correct Python environment: +The SDK ships transitive dependencies at pinned versions. +Check for conflicting requirements with: ```bash -python -c "import sap.cloud.sdk; print(sap.cloud.sdk.__version__)" +pip check ``` -If the import fails, the package may have been installed into a different Python environment than the one you are running. Use `python -m pip install sap-cloud-sdk` to ensure the package is installed for the active interpreter. +If a conflict is reported, align the versions or use a fresh virtual environment. +You can also pin a known-good SDK version while waiting for a fix: -## Connectivity Issues +```bash +pip install "sap-cloud-sdk==0.43.1" +``` + +--- + +## Connectivity and Destinations ### Destination Not Found -If a destination cannot be resolved, check the following: +:::info Symptoms +`DestinationService.get_destination()` raises a not-found error at runtime. +::: + +**Possible causes:** + +- The destination name is misspelled — names are case-sensitive. +- When running locally, `VCAP_SERVICES` is not set. Export the JSON from the BTP Cockpit's service key and set it as an environment variable. +- The Destination Service binding is missing or misconfigured. Verify it is present in your `VCAP_SERVICES` or Kubernetes secret mount. + +### Authentication Failure (401 / 403) + +:::info Symptoms +Requests to a destination fail with HTTP 401 Unauthorized or 403 Forbidden. +::: + +**Possible causes:** + +- The credentials in the destination configuration are expired or incorrect. +- The authentication type configured on the destination does not match what the target system expects (for example, `BasicAuthentication` used where OAuth is required). +- The service key for the Destination Service lacks the required scopes. +- For OAuth destinations, verify the Token Service URL includes the full path, for example `/oauth/token`. + +### Client Certificates Not Applied + +:::info Symptoms +Requests succeed without client certificate authentication even though the destination is configured with `ClientCertificateAuthentication`. +::: + +This is a known issue tracked in [#254](https://github.com/SAP/cloud-sdk-python/issues/254). +As a workaround, attach the certificate manually to the HTTP client until the fix is available. + +--- + +## Agent Gateway Service + +### No MCP Tools Returned + +:::info Symptoms +`list_mcp_tools()` returns an empty list unexpectedly. +::: + +**Possible causes:** + +- The Agent Gateway formation is not yet in `READY` state for the current tenant. + Check the formation status in the SAP BTP Cockpit. +- `integrationDependencies` is empty in the ORD document — the tools have no declared dependencies to discover. +- The `user_token` passed to `list_mcp_tools()` is expired or invalid. + Ensure it is a callable that fetches a fresh token on each call, not a captured string: + +```python +# Correct — token resolved on every invocation +agw_client = create_client(tenant_subdomain=get_tenant_subdomain) +tools = await agw_client.list_mcp_tools(user_token=get_user_token) # callable + +# Incorrect — stale token captured at startup +token = get_user_token() +tools = await agw_client.list_mcp_tools(user_token=token) # string +``` + +### MCP Tool Call Result Is Truncated to a String + +:::info Symptoms +`call_mcp_tool()` returns a plain string instead of a structured object, losing nested data. +::: + +This is a known issue tracked in [#214](https://github.com/SAP/cloud-sdk-python/issues/214) — `CallToolResult` is flattened to `str`. +As a workaround, parse the returned string manually with `json.loads()`: + +```python +import json + +raw = await agw_client.call_mcp_tool(tool=tool, user_token=get_user_token, **args) +result = json.loads(raw) if isinstance(raw, str) else raw +``` + +### Duplicate Tool Names From Multiple MCP Servers + +:::info Symptoms +Two MCP servers expose a tool with the same name, causing the wrong tool to be called. +::: + +This is a known limitation tracked in [#208](https://github.com/SAP/cloud-sdk-python/issues/208). +Until resolved, use `MCPToolFilter` to scope tool discovery to a specific ORD ID: + +```python +from sap_cloud_sdk.agentgateway import AgentCardFilter + +tools = await agw_client.list_mcp_tools( + filter=MCPToolFilter(ord_ids=["sap.s4:purchaseOrder:v1"]) +) +``` + +### Missing Correlation ID in MCP Tool Error Logs + +:::info Symptoms +An MCP tool call fails but the error log does not include a correlation ID, making it hard to trace in SAP Cloud Logging. +::: + +This is a known issue tracked in [#195](https://github.com/SAP/cloud-sdk-python/issues/195). +In the meantime, extract the correlation ID from the response headers in your error handler and log it manually. + +--- + +## Agent Memory Service -1. The destination name is spelled correctly (case-sensitive). -2. The `VCAP_SERVICES` environment variable is set when running locally. -3. The destination service binding is present and correctly configured. +### `AgentMemoryConfigError` on Startup -For more information, see the connectivity documentation. +:::info Symptoms +`create_client()` raises `AgentMemoryConfigError` immediately, before any memory operation is attempted. +::: -### Authentication Failures +The HANA Agent Memory binding is not mounted. +Verify that `hanaAgentMemoryEnabled: true` is set in `app.yaml` and that the secret is mounted at `/etc/secrets/appfnd/hana-agent-memory/default`. -If requests fail with an authentication error: +For local development, set the following environment variables instead: + +```bash +export HC_API_URL=https://.hanacloud.ondemand.com +export HC_CLIENT_ID= +export HC_CLIENT_SECRET= +export HC_AUTH_URL=https:///oauth/token +``` + +### `AgentMemoryValidationError`: Missing Tenant + +:::info Symptoms +`create_client()` raises `AgentMemoryValidationError` with a message about a missing tenant argument. +::: + +Since v0.36.0, the `tenant` argument is required for subscriber-isolated clients. +Pass the current tenant's subdomain explicitly: + +```python +# Before v0.36 (no longer valid) +client = create_client() + +# v0.36+ — tenant subdomain is required +client = create_client(tenant=tenant_subdomain) +``` + +--- + +## Configuration and Breaking Changes + +### `APPFND_UMS_DESTINATION_NAME` No Longer Recognized (v0.43.0) + +:::info Symptoms +After upgrading to v0.43.0, the extensibility module fails to resolve the UMS destination. +::: + +The `APPFND_UMS_DESTINATION_NAME` environment variable was removed in v0.43.0. +Replace it with the programmatic config: + +```python +from sap_cloud_sdk.extensibility import ExtensibilityConfig + +config = ExtensibilityConfig(destination_name="my-ums-destination") +``` -1. Verify the credentials in your destination configuration. -2. Check that the authentication type matches what the target system expects. -3. Ensure the service key for the Destination Service has the required permissions. +Also note that the UMS destination name prefix changed from `sap-managed-runtime-ums-` to `sap-managed-runtime-ias-`, and `APPFND_CONHOS_UMS_URL` is now required. From dee608afad847e3a6c6bce07248779763072e89f Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 17:18:42 -0500 Subject: [PATCH 05/20] adding python to table layout --- src/components/JsFeatureTable.js | 4 ++-- src/components/data/table-layouts.js | 22 ++++++++++++++++++++++ 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/src/components/JsFeatureTable.js b/src/components/JsFeatureTable.js index 0a465ab3d58..a953249ba93 100644 --- a/src/components/JsFeatureTable.js +++ b/src/components/JsFeatureTable.js @@ -1,9 +1,9 @@ import React from 'react'; import ReactMarkdown from 'react-markdown'; +import emoji from 'remark-emoji'; +import gfm from 'remark-gfm'; import { jsFeatureTableLayout } from './data/table-layouts'; // Table layour for JS feature matrix with bindings import { features } from './data/features'; -import gfm from 'remark-gfm'; -import emoji from 'remark-emoji'; import Table from './Table'; /** diff --git a/src/components/data/table-layouts.js b/src/components/data/table-layouts.js index 27ce8470ab7..61a0795e966 100644 --- a/src/components/data/table-layouts.js +++ b/src/components/data/table-layouts.js @@ -51,6 +51,27 @@ export const mainFeatureTableLayout = [ accessorKey: 'js.note' } ] + }, + { + Header: 'SAP Cloud SDK Python', + id: 'python', + columns: [ + { + id: 'python-status', + Header: 'Status', + accessorKey: 'python.status' + }, + { + id: 'python-docs', + Header: 'Docs', + accessorKey: 'python.docsLink' + }, + { + id: 'python-notes', + Header: 'Notes', + accessorKey: 'python.note' + } + ] } ]; @@ -133,6 +154,7 @@ export const jsFeatureTableLayout = [ ] } ]; + export const ODataFeatureTableLayout = [ { Header: 'Feature', From 11a28c33e0abd9136c490053a33bb92a1f0d0b5d Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 17:27:51 -0500 Subject: [PATCH 06/20] update python modules to features json obj. --- src/components/data/features.js | 341 ++++++++++++++++++++++++++++++++ 1 file changed, 341 insertions(+) diff --git a/src/components/data/features.js b/src/components/data/features.js index c3641665c10..d993e13d23f 100644 --- a/src/components/data/features.js +++ b/src/components/data/features.js @@ -22,6 +22,11 @@ export const features = [ status: NO, docsLink: ``, note: 'Take a look at the [node-soap](https://github.com/vpulim/node-soap) library' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -36,6 +41,11 @@ export const features = [ status: NO, docsLink: ``, note: 'Take a look at the [SAP NetWeaver RFC SDK client bindings for Node.js](https://github.com/SAP/node-rfc)' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -50,6 +60,11 @@ export const features = [ status: NO, docsLink: ``, note: 'Take a look at the [SAP NetWeaver RFC SDK client bindings for Node.js](https://github.com/SAP/node-rfc)' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -64,6 +79,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/odata/v2-client)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -78,6 +98,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/odata/v4-client)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -92,6 +117,11 @@ export const features = [ status: NO, docsLink: ``, note: `We expose [generic HTTP client](${baseUrl}/js/features/connectivity/http-client) aware of connectivity abstractions` + }, + python: { + status: NO, + docsLink: ``, + note: 'Use the HTTP Client wrapper with destination awareness instead' } }, { @@ -106,6 +136,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/odata/generate-client)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -120,6 +155,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/openapi/execute-request)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -134,6 +174,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/openapi/execute-request)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -148,6 +193,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/openapi/generate-client)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -162,6 +212,11 @@ export const features = [ status: NO, docsLink: ``, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: '' } }, { @@ -176,6 +231,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/guides/resilience)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: '' } }, { @@ -190,6 +250,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/destination-cache)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: '' } }, { @@ -204,6 +269,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/getting-started)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: '' } }, { @@ -218,6 +288,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/environments/kubernetes)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: '' } }, { @@ -232,6 +307,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/environments/kyma)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: '' } }, { @@ -246,6 +326,11 @@ export const features = [ status: NO, docsLink: ``, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: 'Via `DWCContextProvider` in `sap_cloud_sdk.core.runtime_context`' } }, { @@ -260,6 +345,11 @@ export const features = [ status: NO, docsLink: ``, note: 'Out of scope.' + }, + python: { + status: NO, + docsLink: ``, + note: 'Out of scope' } }, { @@ -274,6 +364,11 @@ export const features = [ status: NO, docsLink: '', note: 'Out of scope' + }, + python: { + status: NO, + docsLink: '', + note: 'Out of scope' } }, { @@ -288,6 +383,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/destinations)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: '' } }, { @@ -302,6 +402,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/destinations)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: '' } }, { @@ -316,6 +421,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/destinations)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: 'IAS is the primary identity provider;' } }, { @@ -330,6 +440,11 @@ export const features = [ status: YES, docsLink: ``, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: 'Via [servicebinding.io](https://servicebinding.io/) spec and `SERVICE_BINDING_ROOT`' } }, { @@ -344,6 +459,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/destinations#authentication-and-json-web-token-retrievjal)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: 'OAuth flows handled via IAS module and Destination Service' } }, { @@ -358,6 +478,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/destinations#multi-tenancy)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: 'Tenant isolation applied throughout; `create_client(tenant=subdomain)` pattern' } }, { @@ -372,6 +497,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/destinations#multi-tenancy)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: '' } }, { @@ -386,6 +516,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/http-client)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: '`DestinationHttpClient` — destination-aware HTTP client' } }, { @@ -400,6 +535,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/on-premise#principal-propagation)`, note: '' + }, + python: { + status: YES, + docsLink: ``, + note: 'User token exchange via IAS Destination Fragments' } }, { @@ -414,6 +554,11 @@ export const features = [ status: YES, docsLink: `[docs](${baseUrl}/js/features/connectivity/on-premise)`, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: '' } }, { @@ -428,6 +573,202 @@ export const features = [ status: NO, docsLink: ``, note: '' + }, + python: { + status: NO, + docsLink: ``, + note: '' + } + }, + // Python-only features + { + name: '[Identity and Access Service (IAS)](https://help.sap.com/docs/identity-authentication)', + category: 'Connectivity', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: ``, + note: 'Token verification, user context propagation, service-to-service auth' + } + }, + { + name: '[Audit Logging](https://help.sap.com/docs/audit-log-service)', + category: 'Advanced', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: ``, + note: 'Standard and next-generation (NG) SAP Audit Log Service APIs supported' + } + }, + { + name: 'Telemetry / OpenTelemetry', + category: 'Advanced', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: ``, + note: 'Auto-instrumentation of HTTP clients and frameworks via `auto_instrument()`; exports to SAP Cloud Logging' + } + }, + { + name: 'Secret Management', + category: 'Advanced', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: ``, + note: 'Resolves secrets from Kubernetes-mounted bindings and env vars (`CLOUD_SDK_CFG_*`)' + } + }, + { + name: 'Object Storage', + category: 'BTP Services', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: ``, + note: '' + } + }, + { + name: 'Document Management Service', + category: 'BTP Services', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: ``, + note: '' + } + }, + { + name: 'Output Management Service', + category: 'BTP Services', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: ``, + note: 'Send emails, create and send output requests via `sap_cloud_sdk.outputmanagement`' + } + }, + { + name: '[SAP AI Core](https://help.sap.com/docs/sap-ai-core)', + category: 'AI', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: `[docs](${baseUrl}/python/overview)`, + note: 'Manage AI scenarios, deployments, and executions via `AICoreClient`' + } + }, + { + name: 'Agent Gateway Service', + category: 'AI', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: `[docs](${baseUrl}/python/overview)`, + note: 'MCP tool discovery from SAP LoB systems; A2A agent routing; principal propagation' + } + }, + { + name: 'Agent Memory Service', + category: 'AI', + java: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + js: { + status: NO, + docsLink: ``, + note: 'Out of scope' + }, + python: { + status: YES, + docsLink: `[docs](${baseUrl}/python/overview)`, + note: 'Persistent conversation history and semantic memory search backed by SAP HANA Cloud' } } ]; From 6c83d85b5ff7241261c346f0d9190dd8daaae1d2 Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 17:43:57 -0500 Subject: [PATCH 07/20] creation of python logo --- docs-python/overview.mdx | 6 +- static/img/logo-python.svg | 113 +++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 3 deletions(-) create mode 100644 static/img/logo-python.svg diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index 2f14db56149..3edb8e94694 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -34,7 +34,7 @@ The Destination Service module provides an abstraction for connecting to remote It resolves credentials, handles OAuth flows (including principal propagation and client credentials), and supports both cloud and on-premise systems via the SAP Connectivity Service. ```python -from sap.cloud.sdk.destination import DestinationService +from sap_cloud_sdk.destination import DestinationService service = DestinationService() destination = service.get_destination("my-destination") @@ -51,7 +51,7 @@ The AI Core module provides a client for [SAP AI Core](https://help.sap.com/docs It integrates with the SDK's credential and destination resolution to simplify connection setup. ```python -from sap.cloud.sdk.ai_core import AICoreClient +from sap_cloud_sdk.ai_core import AICoreClient client = AICoreClient() deployments = client.list_deployments(resource_group="default") @@ -63,7 +63,7 @@ The Audit Logging module provides a structured way to emit audit log events to t Both the standard and the next-generation (NG) audit log APIs are supported. ```python -from sap.cloud.sdk.audit_log import AuditLogger +from sap_cloud_sdk.audit_log import AuditLogger logger = AuditLogger() logger.log_data_access(object_type="BusinessPartner", object_id="1000001", attributes=["Name", "Address"]) diff --git a/static/img/logo-python.svg b/static/img/logo-python.svg new file mode 100644 index 00000000000..38f8787049a --- /dev/null +++ b/static/img/logo-python.svg @@ -0,0 +1,113 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +for Python + From 284e9c35fe0d1bcbfe23abfcabb0e6696b0b3955 Mon Sep 17 00:00:00 2001 From: I769216 Date: Fri, 14 Aug 2026 17:47:15 -0500 Subject: [PATCH 08/20] adding python to homepage --- src/pages/components/HomepageFeatures.js | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/pages/components/HomepageFeatures.js b/src/pages/components/HomepageFeatures.js index 27307928226..f54285c9bf6 100644 --- a/src/pages/components/HomepageFeatures.js +++ b/src/pages/components/HomepageFeatures.js @@ -43,6 +43,23 @@ const FeatureList = [ ) + }, + { + title: <>SAP Cloud SDK for Python, + link: 'docs/python/overview', + Svg: require('../../../static/img/logo-python.svg').default, + badge: , + description: ( +
+ The SAP Cloud SDK for Python helps you build cloud-native AI agents and + BTP integrations using Python, with built-in support for the Agent + Gateway, Agent Memory, and SAP BTP services. +
+ + Get started with the SDK for Python + +
+ ) } ]; From 902e592cc02b0339b87801d793102a2ce9d5f49c Mon Sep 17 00:00:00 2001 From: I769216 Date: Wed, 19 Aug 2026 14:14:08 -0300 Subject: [PATCH 09/20] update overview and add a new section called features to contain all SDK modules grouped by type --- docs-python/features/agent-framework.mdx | 202 +++++++++++++++++++++++ docs-python/features/btp-services.mdx | 51 ++++++ docs-python/features/connectivity.mdx | 125 ++++++++++++++ docs-python/features/core-modules.mdx | 99 +++++++++++ docs-python/overview.mdx | 177 +++++--------------- sidebarsDocsPython.js | 11 ++ 6 files changed, 526 insertions(+), 139 deletions(-) create mode 100644 docs-python/features/agent-framework.mdx create mode 100644 docs-python/features/btp-services.mdx create mode 100644 docs-python/features/connectivity.mdx create mode 100644 docs-python/features/core-modules.mdx diff --git a/docs-python/features/agent-framework.mdx b/docs-python/features/agent-framework.mdx new file mode 100644 index 00000000000..994ee9ce221 --- /dev/null +++ b/docs-python/features/agent-framework.mdx @@ -0,0 +1,202 @@ +--- +id: agent-framework +title: Agent Framework +hide_title: false +hide_table_of_contents: false +sidebar_label: Agent Framework +description: Build AI-powered agents on SAP BTP using tool decorators, the Agent Gateway Service, and the Agent Memory Service +keywords: + - sap + - cloud + - sdk + - python + - agent + - ai + - mcp + - langchain + - agent gateway + - agent memory + - ai core +--- + +The Agent Framework provides the building blocks to create AI-powered agents on SAP BTP. +It consists of three main components: + +- **Tool Decorators** — register Python functions as callable tools within an agent loop +- **Agent Gateway Service** — discover MCP tools from connected SAP LoB systems +- **Agent Memory Service** — persist and retrieve conversation history and long-term memories + +--- + +## Tool Decorators + +Annotate any Python function with `@tool` to register it as a callable tool. +The decorator uses the function's type annotations to generate the tool's input schema and forwards the `description` to the LLM. + +```python +from sap_cloud_sdk.agent import tool + +@tool(description="Fetch the current status for a given order ID.") +def get_order_status(order_id: str) -> str: + # your business logic here + return f"Order {order_id} is currently: In Transit" + +@tool(description="List all open purchase orders for a given supplier.") +def list_open_orders(supplier_id: str, max_results: int = 10) -> list[dict]: + # call your backend system here + return [] +``` + +Decorated functions can be passed directly to a LangChain agent or any framework that accepts a list of tools. + +--- + +## Agent Gateway Service + +The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents. +It discovers MCP tools exposed by connected SAP LoB systems — such as SAP S/4HANA and SAP SuccessFactors — and wraps them as LangChain-compatible tools ready for use in an agent loop. + +### Discovering Tools + +```python +from sap_cloud_sdk.agentgateway import create_client +from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain + +agw_client = create_client(tenant_subdomain=get_tenant_subdomain) +mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) +tools = [ + mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) + for t in mcp_tools +] +``` + +:::note +`get_tenant_subdomain` and `get_user_token` must be **callables** (for example, functions reading from contextvars), not captured strings. +This ensures that credentials are resolved per request and never become stale. +::: + +### Calling a Tool Directly + +You can also call an MCP tool directly without converting to LangChain format: + +```python +result = await agw_client.call_mcp_tool( + tool=mcp_tools[0], + user_token=get_user_token, + order_id="4500012345" +) +``` + +### Filtering Tools by ORD ID + +When multiple MCP servers expose tools with overlapping names, use `MCPToolFilter` to scope discovery to a specific system: + +```python +from sap_cloud_sdk.agentgateway import AgentCardFilter + +tools = await agw_client.list_mcp_tools( + filter=MCPToolFilter(ord_ids=["sap.s4:purchaseOrder:v1"]) +) +``` + +--- + +## Agent Memory Service + +The Agent Memory Service provides a persistent, tenant-isolated store backed by SAP HANA Cloud. +It exposes two APIs: + +- **Messages API** — short-term conversation history, scoped to an agent, user, and session +- **Memories API** — long-term semantic storage with similarity search across sessions + +### Configuration + +The service is configured via a Kubernetes-mounted binding at `/etc/secrets/appfnd/hana-agent-memory/default`. +For local development, set the following environment variables: + +```bash +export HC_API_URL=https://.hanacloud.ondemand.com +export HC_CLIENT_ID= +export HC_CLIENT_SECRET= +export HC_AUTH_URL=https:///oauth/token +``` + +### Messages API + +Use the Messages API to store and replay conversation turns within a session: + +```python +from sap_cloud_sdk.agent_memory import create_client, MessageRole + +client = create_client(tenant=tenant_subdomain) + +# Store a conversation turn +client.add_message( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, role=MessageRole.USER, content=query +) +client.add_message( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, role=MessageRole.ASSISTANT, content=response +) + +# Replay history for a returning session +messages = client.list_messages( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, limit=50 +) +``` + +:::note +Since v0.36.0, the `tenant` argument is required when calling `create_client()`. Omitting it raises `AgentMemoryValidationError`. +::: + +### Memories API + +Use the Memories API to persist facts across sessions and retrieve the most relevant ones using semantic similarity search: + +```python +# Store a long-term fact about the user +client.add_memory( + agent_id="my-agent", invoker_id=user_id, + content="User prefers responses in English." +) + +# Retrieve relevant memories before generating a response +results = client.search_memories( + agent_id="my-agent", invoker_id=user_id, + query="preferred language", threshold=0.6, limit=5 +) +for r in results: + print(f"[{r.similarity:.2f}] {r.content}") +``` + +The `threshold` parameter (0.0–1.0) controls the minimum cosine similarity score for a memory to be returned. +A value of `0.6` is a reasonable starting point for most use cases. + +--- + +## SAP AI Core + +The AI Core module provides a Python client for [SAP AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from your application. +The SDK handles credential resolution and authentication automatically via the service binding. + +```python +from sap_cloud_sdk.ai_core import AICoreClient + +client = AICoreClient() +deployments = client.list_deployments(resource_group="default") + +for d in deployments: + print(d.id, d.status, d.model_name) +``` + +### Starting an Execution + +```python +execution = client.create_execution( + resource_group="default", + configuration_id="my-config-id" +) +print(execution.id, execution.status) +``` diff --git a/docs-python/features/btp-services.mdx b/docs-python/features/btp-services.mdx new file mode 100644 index 00000000000..93d7df07d8d --- /dev/null +++ b/docs-python/features/btp-services.mdx @@ -0,0 +1,51 @@ +--- +id: btp-services +title: RBS Services +hide_title: false +hide_table_of_contents: false +sidebar_label: RBS Services +description: Use RBS services from Python — Document Management and Output Management +keywords: + - sap + - cloud + - sdk + - python + - document management + - output management +--- + +## Document Management Service + +The Document Management module provides a client for [SAP Document Management Service](https://help.sap.com/docs/document-management-service), enabling you to manage documents and folders in a repository. + +```python +from sap_cloud_sdk.document_management import DocumentManagementClient + +client = DocumentManagementClient() +folder = client.create_folder(repository_id="my-repo", path="/invoices/2026") +document = client.upload_document( + repository_id="my-repo", + folder_id=folder.id, + file_name="invoice-001.pdf", + content=pdf_bytes +) +``` + +--- + +## Output Management Service + +The Output Management module provides a client for creating and sending output requests — including emails and print documents — via the [SAP Output Management Service](https://help.sap.com/docs/output-management). + +```python +from sap_cloud_sdk.outputmanagement import OutputManagementClient + +client = OutputManagementClient() + +# Send an email +client.send_output_request( + template_id="invoice-email-template", + recipient="customer@example.com", + data={"invoice_number": "INV-001", "amount": "1,500.00 EUR"} +) +``` diff --git a/docs-python/features/connectivity.mdx b/docs-python/features/connectivity.mdx new file mode 100644 index 00000000000..b8b76065b97 --- /dev/null +++ b/docs-python/features/connectivity.mdx @@ -0,0 +1,125 @@ +--- +id: connectivity +title: Connectivity and Identity +hide_title: false +hide_table_of_contents: false +sidebar_label: Connectivity & Identity +description: Connect to remote systems, handle authentication, and manage user identity with the SAP Cloud SDK for Python +keywords: + - sap + - cloud + - sdk + - python + - destination + - connectivity + - ias + - identity + - authentication +--- + +## Destination Service + +The Destination Service module provides an abstraction for connecting to remote systems defined in the SAP BTP Cockpit. +It resolves credentials, handles OAuth flows, and supports both cloud and on-premise systems via the SAP Connectivity Service. + +```python +from sap_cloud_sdk.destination import DestinationService + +service = DestinationService() +destination = service.get_destination("my-destination") +``` + +The SDK supports all standard destination authentication types, including Basic Authentication, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Principal Propagation. + +### Using a Destination with an HTTP Client + +Once you have a destination, you can pass it directly to the destination-aware HTTP client: + +```python +from sap_cloud_sdk.destination import DestinationService +from sap_cloud_sdk.http_client import DestinationHttpClient + +service = DestinationService() +destination = service.get_destination("my-s4-system") + +client = DestinationHttpClient(destination) +response = client.get("/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner") +``` + +The client automatically applies the destination's credentials, headers, and proxy configuration to every request. + +--- + +## Identity and Access Service (IAS) + +The IAS module handles authentication and token management for applications secured with [SAP Cloud Identity Services](https://help.sap.com/docs/identity-authentication). +IAS is the primary identity provider for new Python SDK applications — XSUAA is out of scope. + +### Token Verification + +Verify incoming JWTs from SAP Cloud Identity Services: + +```python +from sap_cloud_sdk.ias import IASTokenVerifier + +verifier = IASTokenVerifier() +token_claims = verifier.verify(request_token) +user_id = token_claims.subject +tenant = token_claims.zone_uuid +``` + +### Service-to-Service Authentication + +For service-to-service calls, the SDK handles the client credentials flow automatically when the IAS binding is present: + +```python +from sap_cloud_sdk.ias import IASClient + +ias_client = IASClient() +token = ias_client.get_service_token(target_service="my-backend-service") +``` + +--- + +## Multi-Tenancy + +The SDK applies tenant isolation throughout by default. +The current tenant is resolved from the incoming request token and propagated automatically to destination lookups, memory operations, and other SDK calls. + +You can also provide the tenant subdomain explicitly when needed: + +```python +from sap_cloud_sdk.destination import DestinationService + +service = DestinationService() +destination = service.get_destination("my-destination", tenant_subdomain="acme-corp") +``` + +--- + +## Secret Management + +The Secret Management module provides a unified interface for reading credentials and configuration values. +The SDK resolves secrets from multiple sources in the following priority order: + +1. Kubernetes-mounted secrets via `SERVICE_BINDING_ROOT` (following the [servicebinding.io](https://servicebinding.io/) specification) +2. Environment variables using the pattern `CLOUD_SDK_CFG___` + +This means the same application code runs locally (using env vars) and in Kubernetes (using mounted secrets) without any modification. + +### Example: Reading a Secret + +```python +from sap_cloud_sdk.secret_management import SecretManager + +manager = SecretManager() +api_key = manager.get_secret(module="my-service", instance="default", field="api-key") +``` + +### Local Development with Environment Variables + +Set the environment variable pattern to simulate a Kubernetes binding locally: + +```bash +export CLOUD_SDK_CFG_MY_SERVICE_DEFAULT_API_KEY=my-local-api-key +``` diff --git a/docs-python/features/core-modules.mdx b/docs-python/features/core-modules.mdx new file mode 100644 index 00000000000..f27448399ca --- /dev/null +++ b/docs-python/features/core-modules.mdx @@ -0,0 +1,99 @@ +--- +id: core-modules +title: Core Modules +hide_title: false +hide_table_of_contents: false +sidebar_label: Core Modules +description: Cross-cutting SDK modules — Audit Logging, Telemetry, and Object Storage +keywords: + - sap + - cloud + - sdk + - python + - audit log + - telemetry + - opentelemetry + - object storage +--- + +## Audit Logging + +The Audit Logging module provides a structured way to emit audit log events to the [SAP Audit Log Service](https://help.sap.com/docs/audit-log-service). +Both the standard and the next-generation (NG) audit log APIs are supported. + +### Data Access Events + +```python +from sap_cloud_sdk.audit_log import AuditLogger + +logger = AuditLogger() +logger.log_data_access( + object_type="BusinessPartner", + object_id="1000001", + attributes=["Name", "Address"] +) +``` + +### Data Modification Events + +```python +logger.log_data_modification( + object_type="SalesOrder", + object_id="SO-4500012345", + attributes=[{"name": "Status", "old_value": "Open", "new_value": "Closed"}] +) +``` + +--- + +## Telemetry + +The Telemetry module provides observability utilities built on top of [OpenTelemetry](https://opentelemetry.io/). +It auto-instruments SDK HTTP clients and common Python frameworks, exporting traces and metrics to any OpenTelemetry-compatible backend such as SAP Cloud Logging. + +### Setup + +Call `auto_instrument()` once at application startup: + +```python +from sap_cloud_sdk.telemetry import auto_instrument + +auto_instrument() +``` + +This sets up trace propagation and metric collection for all SDK operations and outbound HTTP requests without any further configuration. + +### Custom Spans + +You can also create custom spans to trace your own business logic: + +```python +from opentelemetry import trace + +tracer = trace.get_tracer("my-agent") + +with tracer.start_as_current_span("process-order"): + result = process_order(order_id) +``` + +--- + +## Object Storage + +The Object Storage module provides a client for SAP BTP Object Store Service, allowing you to upload, download, list, and delete objects. + +```python +from sap_cloud_sdk.object_storage import ObjectStorageClient + +client = ObjectStorageClient() + +# Upload a file +with open("report.pdf", "rb") as f: + client.upload(bucket="my-bucket", key="reports/2026/report.pdf", body=f) + +# Download a file +content = client.download(bucket="my-bucket", key="reports/2026/report.pdf") + +# List objects +objects = client.list(bucket="my-bucket", prefix="reports/") +``` diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index 3edb8e94694..51be02c8046 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -19,158 +19,51 @@ keywords: For a quick start check out the [Getting Started](./getting-started.mdx) page. -## Why the SAP Cloud SDK for Python? +## What is the SAP Cloud SDK for Python? -The SAP Cloud SDK for Python makes it easy to build cloud-native applications on the SAP Business Technology Platform (SAP BTP). -It provides consistent, type-safe interfaces for the foundational BTP and SAP services — destination management, identity, audit logging, storage, telemetry, and more — so you can focus on business logic instead of boilerplate integration code. +The SAP Cloud SDK for Python makes it easy to build cloud-native AI agents and BTP integrations on the SAP Business Technology Platform (SAP BTP). +It provides consistent, type-safe interfaces for foundational BTP services — destinations, identity, audit logging, storage, telemetry, and more — so you can focus on business logic instead of boilerplate integration code. -Below, you will find main features described with examples. - -## Main Features - -### Destination Service - -The Destination Service module provides an abstraction for connecting to remote systems defined in the SAP BTP Cockpit. -It resolves credentials, handles OAuth flows (including principal propagation and client credentials), and supports both cloud and on-premise systems via the SAP Connectivity Service. - -```python -from sap_cloud_sdk.destination import DestinationService - -service = DestinationService() -destination = service.get_destination("my-destination") -``` - -### Identity and Access (IAS) - -The Identity and Access Service (IAS) module handles authentication and token management for applications secured with SAP Cloud Identity Services. -It provides utilities for token verification, user context propagation, and service-to-service authentication. - -### AI Core - -The AI Core module provides a client for [SAP AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from Python applications. -It integrates with the SDK's credential and destination resolution to simplify connection setup. +For example, with the SAP Cloud SDK for Python you can discover MCP tools from connected SAP LoB systems and use them directly in an agent loop: ```python -from sap_cloud_sdk.ai_core import AICoreClient - -client = AICoreClient() -deployments = client.list_deployments(resource_group="default") -``` - -### Audit Logging - -The Audit Logging module provides a structured way to emit audit log events to the SAP Audit Log Service. -Both the standard and the next-generation (NG) audit log APIs are supported. - -```python -from sap_cloud_sdk.audit_log import AuditLogger +from sap_cloud_sdk.agentgateway import create_client +from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain -logger = AuditLogger() -logger.log_data_access(object_type="BusinessPartner", object_id="1000001", attributes=["Name", "Address"]) +agw_client = create_client(tenant_subdomain=get_tenant_subdomain) +mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) +tools = [mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) for t in mcp_tools] ``` -### Secret Management - -The Secret Management module provides a unified interface for reading credentials and secrets. -The SDK resolves secrets from multiple sources in priority order: - -1. Kubernetes-mounted secrets via `SERVICE_BINDING_ROOT` (following the [servicebinding.io](https://servicebinding.io/) specification) -2. Environment variables using the pattern `CLOUD_SDK_CFG___` +This discovers MCP tools from connected SAP LoB systems (S/4HANA, SuccessFactors) and exposes them as LangChain-compatible tools ready to drop into any agent loop. -This means the same application code works locally (using env vars) and in Kubernetes (using mounted secrets) without modification. +## Main Features of the SAP Cloud SDK for Python -### Telemetry +### Connectivity and Identity -The Telemetry module provides observability utilities built on top of [OpenTelemetry](https://opentelemetry.io/). -It instruments SDK operations with traces and metrics that can be exported to any OpenTelemetry-compatible backend such as SAP Cloud Logging. +The SDK abstracts the details of connecting to remote systems defined in the SAP BTP Cockpit. +The Destination Service module resolves credentials, handles OAuth flows (including principal propagation and client credentials), and supports both cloud and on-premise systems. +The Identity and Access Service (IAS) module handles token verification and user context propagation for applications secured with SAP Cloud Identity Services. -### Object Storage and Document Management - -The Object Storage and Document Management modules provide clients for SAP BTP's storage services, allowing you to upload, download, and manage files and documents directly from your Python application. +For details and code examples, see the [Connectivity and Identity](features/connectivity) guide. ### Agent Framework -The Agent module provides building blocks for creating AI-powered agents on SAP BTP. - -#### Decorators - -Annotate Python functions with `@tool` to register them as callable tools within the agent loop. -The decorator forwards the function's type annotations as the tool's input schema and the `description` to the LLM. +The Agent Framework is the core differentiator of the Python SDK. +It provides building blocks for AI-powered agents running on SAP BTP: a `@tool` decorator to register Python functions as agent tools, the **Agent Gateway Service** for discovering MCP tools from connected LoB systems with tenant-aware principal propagation, and the **Agent Memory Service** for storing and retrieving conversation history and long-term semantic memories backed by SAP HANA Cloud. -```python -from sap_cloud_sdk.agent import tool - -@tool(description="Fetch the order status for a given order ID.") -def get_order_status(order_id: str) -> str: - # your business logic here - return f"Order {order_id} is currently: In Transit" -``` +For details and code examples, see the [Agent Framework](features/agent-framework) guide. -#### Agent Gateway Service +### BTP Services -The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents. -It discovers MCP tools exposed by connected SAP LoB systems (such as SAP S/4HANA and SAP SuccessFactors) and wraps them as LangChain-compatible tools ready for use in an agent loop. +The SDK provides clients for a range of SAP BTP services, including SAP AI Core (deployment and execution management), the Audit Log Service, Object Storage, Document Management, and Output Management. +It also includes a Telemetry module built on OpenTelemetry for traces and metrics that export to SAP Cloud Logging, and a Secret Management module that resolves credentials from Kubernetes-mounted bindings or environment variables using a consistent priority-based lookup. -```python -from sap_cloud_sdk.agentgateway import create_client -from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain +For details and code examples, see the [RBS Services](features/btp-services) guide. -agw_client = create_client(tenant_subdomain=get_tenant_subdomain) -mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) -tools = [ - mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) - for t in mcp_tools -] -``` +## Further Information -:::note -`get_tenant_subdomain` and `get_user_token` should be callables (for example, functions reading from contextvars) so that credentials are resolved per request and never captured at construction time. -::: - -#### Agent Memory Service - -The Agent Memory Service provides a persistent, tenant-isolated store backed by SAP HANA Cloud. -It exposes two APIs: a **Messages API** for short-term conversation history, and a **Memories API** for long-term semantic search across sessions. - -```python -from sap_cloud_sdk.agent_memory import create_client, MessageRole - -client = create_client(tenant=tenant_subdomain) - -# Store a conversation turn -client.add_message( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, role=MessageRole.USER, content=query -) -client.add_message( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, role=MessageRole.ASSISTANT, content=response -) - -# Replay history for a returning session -messages = client.list_messages( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, limit=50 -) -``` - -Use the Memories API to persist and retrieve facts across sessions with semantic similarity search: - -```python -# Store a long-term fact -client.add_memory(agent_id="my-agent", invoker_id=user_id, - content="User prefers responses in English.") - -# Retrieve relevant memories before answering -results = client.search_memories( - agent_id="my-agent", invoker_id=user_id, - query="preferred language", threshold=0.6, limit=5 -) -for r in results: - print(f"[{r.similarity:.2f}] {r.content}") -``` - -## Supported Python Versions +### Supported Python Versions The SAP Cloud SDK for Python requires **Python 3.11 or higher**. @@ -181,18 +74,24 @@ The SAP Cloud SDK for Python requires **Python 3.11 or higher**. | 3.11 | ✅ | | 3.10 | ❌ | -## Supported Environments +### Supported Environments + +The SAP Cloud SDK for Python currently targets cloud-native deployments on SAP BTP: -The SAP Cloud SDK for Python is currently focused in Agentic use-cases running in the Joule Studio Runtime. +1. SAP BTP Cloud Foundry +2. Kubernetes / SAP Gardener +3. SAP BTP Kyma +4. Deploy with Confidence (DwC) — via `DWCContextProvider` in `sap_cloud_sdk.core.runtime_context` -## Licensing +### Licensing -The SAP Cloud SDK for Python is open-source and available on [PyPI](https://pypi.org/project/sap-cloud-sdk/) under the [Apache 2.0 license](https://github.com/SAP/cloud-sdk-python/blob/main/LICENSE). +The SAP Cloud SDK for Python is available on [PyPI](https://pypi.org/project/sap-cloud-sdk/) under the [Apache 2.0 license](https://github.com/SAP/cloud-sdk-python/blob/main/LICENSE). -## Release Schedule +### Release Schedule -For details on the release cadence and version support, check the TODO: release policy document. +We release minor versions on a regular cadence. +For details, see the [release notes](./release-notes.mdx). -## Contributing +### Contributing For details on contributing, check the [contribution guide](https://github.com/SAP/cloud-sdk/blob/main/CONTRIBUTING.md). diff --git a/sidebarsDocsPython.js b/sidebarsDocsPython.js index a92b4474759..7ae4f2d29e3 100644 --- a/sidebarsDocsPython.js +++ b/sidebarsDocsPython.js @@ -2,6 +2,17 @@ module.exports = { docsPythonSidebar: [ 'overview', 'getting-started', + { + type: 'category', + label: 'Features', + collapsed: false, + items: [ + 'features/agent-framework', + 'features/connectivity', + 'features/core-modules', + 'features/btp-services', + ] + }, 'release-notes', 'support', 'troubleshooting' From d4ce550dfd1631b0a63d16de558b4dc1b29bf283 Mon Sep 17 00:00:00 2001 From: I769216 Date: Wed, 19 Aug 2026 14:32:01 -0300 Subject: [PATCH 10/20] adding a modules diagram for Python --- docs-python/overview.mdx | 32 +++++++++++--- static/img/python-sdk-overview.svg | 70 ++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+), 7 deletions(-) create mode 100644 static/img/python-sdk-overview.svg diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index 51be02c8046..cf79fe0f6a7 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -15,6 +15,9 @@ keywords: - python --- +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + ## Quick Start For a quick start check out the [Getting Started](./getting-started.mdx) page. @@ -39,6 +42,23 @@ This discovers MCP tools from connected SAP LoB systems (S/4HANA, SuccessFactors ## Main Features of the SAP Cloud SDK for Python + + +### Agent Framework + +The Agent Framework is the core differentiator of the Python SDK. +It provides building blocks for AI-powered agents running on SAP BTP: a `@tool` decorator to register Python functions as agent tools, the **Agent Gateway Service** for discovering MCP tools from connected LoB systems with tenant-aware principal propagation, the **Agent Memory Service** for storing and retrieving conversation history and long-term semantic memories backed by SAP HANA Cloud, and a client for **SAP AI Core** to manage deployments and executions. + +For details and code examples, see the [Agent Framework](features/agent-framework) guide. + ### Connectivity and Identity The SDK abstracts the details of connecting to remote systems defined in the SAP BTP Cockpit. @@ -47,17 +67,15 @@ The Identity and Access Service (IAS) module handles token verification and user For details and code examples, see the [Connectivity and Identity](features/connectivity) guide. -### Agent Framework +### Core Modules -The Agent Framework is the core differentiator of the Python SDK. -It provides building blocks for AI-powered agents running on SAP BTP: a `@tool` decorator to register Python functions as agent tools, the **Agent Gateway Service** for discovering MCP tools from connected LoB systems with tenant-aware principal propagation, and the **Agent Memory Service** for storing and retrieving conversation history and long-term semantic memories backed by SAP HANA Cloud. +The SDK includes cross-cutting modules that apply to any application type: **Audit Logging** for emitting structured events to the SAP Audit Log Service, **Telemetry** for auto-instrumented OpenTelemetry traces and metrics exported to SAP Cloud Logging, and **Object Storage** for managing files on SAP BTP Object Store Service. -For details and code examples, see the [Agent Framework](features/agent-framework) guide. +For details and code examples, see the [Core Modules](features/core-modules) guide. -### BTP Services +### RBS Services -The SDK provides clients for a range of SAP BTP services, including SAP AI Core (deployment and execution management), the Audit Log Service, Object Storage, Document Management, and Output Management. -It also includes a Telemetry module built on OpenTelemetry for traces and metrics that export to SAP Cloud Logging, and a Secret Management module that resolves credentials from Kubernetes-mounted bindings or environment variables using a consistent priority-based lookup. +The SDK provides clients for SAP RBS services, including **Document Management** for managing documents and folders in a repository, and **Output Management** for creating and sending output requests such as emails and print documents. For details and code examples, see the [RBS Services](features/btp-services) guide. diff --git a/static/img/python-sdk-overview.svg b/static/img/python-sdk-overview.svg new file mode 100644 index 00000000000..d9d14667bfc --- /dev/null +++ b/static/img/python-sdk-overview.svg @@ -0,0 +1,70 @@ + + + + + + + Agent Framework + + + Tool Decorators + + + Agent Gateway Service + + + Agent Memory Service + + + SAP AI Core + + + + Connectivity & Identity + + + Destination Service + + + Identity (IAS) + + + Multi-tenancy + + + Secret Management + + + + Core Modules + + + Audit Logging + + + Telemetry + + + Object Storage + + + + RBS Services + + + Document Management + + + Output Management + + From d1df92a7e8d7b76d91658ab4910a642be1068a6a Mon Sep 17 00:00:00 2001 From: I769216 Date: Wed, 19 Aug 2026 15:06:43 -0300 Subject: [PATCH 11/20] adding missing modules --- docs-python/features/btp-services.mdx | 138 +++++++++++++++++++++++++- docs-python/features/core-modules.mdx | 82 ++++++++++++++- docs-python/overview.mdx | 4 +- static/img/python-sdk-overview.svg | 34 ++++--- 4 files changed, 240 insertions(+), 18 deletions(-) diff --git a/docs-python/features/btp-services.mdx b/docs-python/features/btp-services.mdx index 93d7df07d8d..e111333ce3f 100644 --- a/docs-python/features/btp-services.mdx +++ b/docs-python/features/btp-services.mdx @@ -4,17 +4,20 @@ title: RBS Services hide_title: false hide_table_of_contents: false sidebar_label: RBS Services -description: Use RBS services from Python — Document Management and Output Management +description: Use SAP RBS services from Python — DMS, ADMS, Output Management, and Print Service keywords: - sap - cloud - sdk - python + - dms + - adms - document management - output management + - print service --- -## Document Management Service +## DMS The Document Management module provides a client for [SAP Document Management Service](https://help.sap.com/docs/document-management-service), enabling you to manage documents and folders in a repository. @@ -33,6 +36,85 @@ document = client.upload_document( --- +## ADMS + +The Advanced Document Management Service (ADMS) module provides a typed Python client for the [SAP Advanced Document Management Service](https://help.sap.com/docs/advanced-document-management) OData V4 API. +Credentials are read from the service binding at `/etc/secrets/appfnd/adms/default/` or the `CLOUD_SDK_CFG_ADMS_DEFAULT_*` environment variables. + +### Creating a Client + +```python +from sap_cloud_sdk.adms import create_client + +client = create_client() +``` + +For per-user policy enforcement, pass a user JWT: + +```python +client = create_client(user_jwt=request_token) +# or scope an existing client to a user: +user_client = client.with_user_jwt(request_token) +``` + +### Managing Documents + +```python +# List all document relations +relations = client.relations.get_all() + +# Create a new document relation and generate upload URLs +relation = client.relations.create(input=CreateDocumentRelationInput(...)) +upload_urls = client.relations.generate_upload_urls( + document_relation_id=relation.id, + file_count=1, + file_size_in_bytes=len(pdf_bytes) +) + +# Retrieve a document +document = client.documents.get(document_relation_id=relation.id) +download_url = client.documents.get_download_url( + document_relation_id=relation.id, + doc_content_version_id=document.content_version_id +) +``` + +### Draft Workflow + +```python +from sap_cloud_sdk.adms import DraftInput, DraftActivateInput + +# Create and activate a draft +draft_relations = client.relations.create_draft(draft_input=DraftInput(...)) +client.relations.validate_draft(draft_input=DraftInput(...)) +client.relations.activate_draft(input=DraftActivateInput(...)) + +# Or discard +client.relations.discard_draft(draft_input=DraftInput(...)) +``` + +### Background Jobs + +```python +from sap_cloud_sdk.adms import ZipDownloadJobParameters + +job = client.jobs.start_zip_download(params=ZipDownloadJobParameters( + document_relation_ids=["id-1", "id-2"] +)) +status = client.jobs.get_status(job_id=job.job_id) +``` + +### Async Client + +```python +from sap_cloud_sdk.adms import create_async_client + +async with create_async_client() as client: + relations = await client.relations.get_all() +``` + +--- + ## Output Management Service The Output Management module provides a client for creating and sending output requests — including emails and print documents — via the [SAP Output Management Service](https://help.sap.com/docs/output-management). @@ -49,3 +131,55 @@ client.send_output_request( data={"invoice_number": "INV-001", "amount": "1,500.00 EUR"} ) ``` + +--- + +## Print Service + +The Print Service module provides a client for [SAP Print Service](https://help.sap.com/docs/print-service), enabling you to manage print queues, upload documents, and submit print tasks. +Credentials are read from the service binding at `$SERVICE_BINDING_ROOT/print/default/` or the `CLOUD_SDK_CFG_PRINT_DEFAULT_*` environment variables. + +### Creating a Client + +```python +from sap_cloud_sdk.print import create_client + +client = create_client() +``` + +### Uploading and Printing a Document + +```python +from sap_cloud_sdk.print import PrintTask, PrintContent + +# Upload the document to cloud storage +with open("invoice.pdf", "rb") as f: + doc_id = client.upload_document(f, filename="invoice.pdf") + +# Submit a print task +client.create_print_task(PrintTask( + item_id=doc_id, + qname="my-print-queue", + print_contents=[PrintContent(object_key=doc_id, document_name="invoice.pdf")], + number_of_copies=1, +)) +``` + +### Managing Print Queues + +```python +from sap_cloud_sdk.print import PrintQueue + +# List available queues +queues = client.list_queues() + +# Create a new queue +client.create_queue(PrintQueue( + qname="INVOICES", + qdescription="Invoice printing queue", + cleanup_prd=3, +)) + +# Get print profiles for a queue +profiles = client.get_print_profiles(qname="INVOICES") +``` diff --git a/docs-python/features/core-modules.mdx b/docs-python/features/core-modules.mdx index f27448399ca..b83eb42156b 100644 --- a/docs-python/features/core-modules.mdx +++ b/docs-python/features/core-modules.mdx @@ -4,7 +4,7 @@ title: Core Modules hide_title: false hide_table_of_contents: false sidebar_label: Core Modules -description: Cross-cutting SDK modules — Audit Logging, Telemetry, and Object Storage +description: Cross-cutting SDK modules — Audit Logging, Telemetry & Observability, Object Storage, and Runtime Context keywords: - sap - cloud @@ -14,6 +14,7 @@ keywords: - telemetry - opentelemetry - object storage + - runtime context --- ## Audit Logging @@ -46,7 +47,7 @@ logger.log_data_modification( --- -## Telemetry +## Telemetry & Observability The Telemetry module provides observability utilities built on top of [OpenTelemetry](https://opentelemetry.io/). It auto-instruments SDK HTTP clients and common Python frameworks, exporting traces and metrics to any OpenTelemetry-compatible backend such as SAP Cloud Logging. @@ -97,3 +98,80 @@ content = client.download(bucket="my-bucket", key="reports/2026/report.pdf") # List objects objects = client.list(bucket="my-bucket", prefix="reports/") ``` + +--- + +## Runtime Context + +The Runtime Context module propagates caller-identity information — tenant, user, and trigger type — across any invocation source (HTTP, gRPC, message queue) without coupling to a specific framework. +It uses a `ContextVar` so context is scoped per async task or thread. + +### Setup + +Call `bootstrap()` once at application startup to wire the built-in providers into your framework (Starlette / FastAPI are supported out of the box): + +```python +from sap_cloud_sdk import bootstrap + +bootstrap(app) +``` + +This automatically registers the `IASContextProvider` (tenant and user from the `Authorization` JWT), `SAPTriggerContextProvider` (trigger type from `x-sap-origin`), and `DWCContextProvider` (Deploy with Confidence headers). + +### Reading Context + +```python +from sap_cloud_sdk.core.runtime_context import get_context, APP_TENANT_ID, USER_ID, TRIGGER_TYPE + +ctx = get_context() +tenant = ctx.get(APP_TENANT_ID) # -> "abc-123" or None +user = ctx.get(USER_ID) # -> "user-uuid" or None +``` + +### Custom Context Keys and Providers + +You can extend the context with your own keys and providers: + +```python +from sap_cloud_sdk.core.runtime_context import ( + ContextKey, ContextProvider, RuntimeContext, RequestEnvelope, + IASContextProvider, SAPTriggerContextProvider, DWCContextProvider, +) + +CORRELATION_ID = ContextKey[str]("correlation_id") + +class CorrelationIdProvider(ContextProvider): + def extract(self, envelope: RequestEnvelope) -> RuntimeContext: + value = envelope.headers.get("x-correlation-id") + return RuntimeContext({CORRELATION_ID: value} if value else {}) + +bootstrap(app, providers=[ + IASContextProvider(), + SAPTriggerContextProvider(), + DWCContextProvider(), + CorrelationIdProvider(), +]) +``` + +### Manual Context Management + +For non-HTTP use cases such as background workers or tests, set and read context directly: + +```python +from sap_cloud_sdk.core.runtime_context import sdk_context, RuntimeContext, APP_TENANT_ID + +ctx = RuntimeContext({APP_TENANT_ID: "acme-corp"}) + +with sdk_context(ctx): + # ctx is active for the duration of this block + process_job() +``` + +Use `async_sdk_context` for async code: + +```python +from sap_cloud_sdk.core.runtime_context import async_sdk_context + +async with async_sdk_context(ctx): + await process_async_job() +``` diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index cf79fe0f6a7..ae17bf2103e 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -69,13 +69,13 @@ For details and code examples, see the [Connectivity and Identity](features/conn ### Core Modules -The SDK includes cross-cutting modules that apply to any application type: **Audit Logging** for emitting structured events to the SAP Audit Log Service, **Telemetry** for auto-instrumented OpenTelemetry traces and metrics exported to SAP Cloud Logging, and **Object Storage** for managing files on SAP BTP Object Store Service. +The SDK includes cross-cutting modules that apply to any application type: **Audit Logging** for emitting structured events to the SAP Audit Log Service, **Telemetry & Observability** for auto-instrumented OpenTelemetry traces and metrics exported to SAP Cloud Logging, **Object Storage** for managing files on SAP BTP Object Store Service, and **Runtime Context** for propagating tenant, user, and trigger-type information across async tasks without coupling to a specific framework. For details and code examples, see the [Core Modules](features/core-modules) guide. ### RBS Services -The SDK provides clients for SAP RBS services, including **Document Management** for managing documents and folders in a repository, and **Output Management** for creating and sending output requests such as emails and print documents. +The SDK provides clients for SAP RBS services: **DMS** for managing documents and folders in a repository, **ADMS** for the Advanced Document Management Service, **Output Management** for creating and sending output requests, and **Print Service** for managing print queues and submitting print tasks. For details and code examples, see the [RBS Services](features/btp-services) guide. diff --git a/static/img/python-sdk-overview.svg b/static/img/python-sdk-overview.svg index d9d14667bfc..466e55a7f31 100644 --- a/static/img/python-sdk-overview.svg +++ b/static/img/python-sdk-overview.svg @@ -1,11 +1,12 @@ + viewBox="0 0 760 275" + width="760" height="275"> @@ -43,28 +44,37 @@ Secret Management - Core Modules - - Audit Logging + + Audit Logging - - Telemetry + + Telemetry & Observability - - Object Storage + + Object Storage + + + Runtime Context - RBS Services - Document Management + DMS - Output Management + ADMS + + + Output Management + + + Print Service From 140f825e2f3e314d56f3e92c63fca155327c0e69 Mon Sep 17 00:00:00 2001 From: I769216 Date: Wed, 19 Aug 2026 15:34:38 -0300 Subject: [PATCH 12/20] refactoring name --- docs-python/features/agent-framework.mdx | 4 ++-- docs-python/overview.mdx | 6 +++--- static/img/python-sdk-overview.svg | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs-python/features/agent-framework.mdx b/docs-python/features/agent-framework.mdx index 994ee9ce221..07397d75d28 100644 --- a/docs-python/features/agent-framework.mdx +++ b/docs-python/features/agent-framework.mdx @@ -1,9 +1,9 @@ --- id: agent-framework -title: Agent Framework +title: Agent Modules hide_title: false hide_table_of_contents: false -sidebar_label: Agent Framework +sidebar_label: Agent Modules description: Build AI-powered agents on SAP BTP using tool decorators, the Agent Gateway Service, and the Agent Memory Service keywords: - sap diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index ae17bf2103e..0e3eb35e175 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -52,12 +52,12 @@ This discovers MCP tools from connected SAP LoB systems (S/4HANA, SuccessFactors width="100%" /> -### Agent Framework +### Agent Modules -The Agent Framework is the core differentiator of the Python SDK. +The Agent Modules are the core differentiator of the Python SDK. It provides building blocks for AI-powered agents running on SAP BTP: a `@tool` decorator to register Python functions as agent tools, the **Agent Gateway Service** for discovering MCP tools from connected LoB systems with tenant-aware principal propagation, the **Agent Memory Service** for storing and retrieving conversation history and long-term semantic memories backed by SAP HANA Cloud, and a client for **SAP AI Core** to manage deployments and executions. -For details and code examples, see the [Agent Framework](features/agent-framework) guide. +For details and code examples, see the [Agent Modules](features/agent-framework) guide. ### Connectivity and Identity diff --git a/static/img/python-sdk-overview.svg b/static/img/python-sdk-overview.svg index 466e55a7f31..a620e339654 100644 --- a/static/img/python-sdk-overview.svg +++ b/static/img/python-sdk-overview.svg @@ -12,7 +12,7 @@ - Agent Framework + Agent Modules Tool Decorators From 8707b4e04db792000d012fed6b8cd2d57f20075f Mon Sep 17 00:00:00 2001 From: I769216 Date: Thu, 20 Aug 2026 13:49:07 -0300 Subject: [PATCH 13/20] reestructuring Python modules section --- docs-python/features/agent-framework.mdx | 202 ------------------ .../features/agent-modules/agent-gateway.mdx | 62 ++++++ .../features/agent-modules/agent-memory.mdx | 88 ++++++++ .../features/agent-modules/ai-core.mdx | 39 ++++ .../agent-modules/tool-decorators.mdx | 34 +++ docs-python/features/btp-services.mdx | 185 ---------------- docs-python/features/connectivity.mdx | 125 ----------- .../connectivity/destination-service.mdx | 46 ++++ .../features/connectivity/identity-ias.mdx | 44 ++++ .../features/connectivity/multi-tenancy.mdx | 27 +++ .../connectivity/secret-management.mdx | 42 ++++ .../features/core-modules/audit-logging.mdx | 41 ++++ .../features/core-modules/object-storage.mdx | 34 +++ .../runtime-context.mdx} | 101 +-------- .../features/core-modules/telemetry.mdx | 45 ++++ docs-python/features/rbs-services/adms.mdx | 91 ++++++++ docs-python/features/rbs-services/dms.mdx | 30 +++ .../rbs-services/output-management.mdx | 31 +++ .../features/rbs-services/print-service.mdx | 63 ++++++ docs-python/overview.mdx | 8 +- sidebarsDocsPython.js | 48 ++++- 21 files changed, 772 insertions(+), 614 deletions(-) delete mode 100644 docs-python/features/agent-framework.mdx create mode 100644 docs-python/features/agent-modules/agent-gateway.mdx create mode 100644 docs-python/features/agent-modules/agent-memory.mdx create mode 100644 docs-python/features/agent-modules/ai-core.mdx create mode 100644 docs-python/features/agent-modules/tool-decorators.mdx delete mode 100644 docs-python/features/btp-services.mdx delete mode 100644 docs-python/features/connectivity.mdx create mode 100644 docs-python/features/connectivity/destination-service.mdx create mode 100644 docs-python/features/connectivity/identity-ias.mdx create mode 100644 docs-python/features/connectivity/multi-tenancy.mdx create mode 100644 docs-python/features/connectivity/secret-management.mdx create mode 100644 docs-python/features/core-modules/audit-logging.mdx create mode 100644 docs-python/features/core-modules/object-storage.mdx rename docs-python/features/{core-modules.mdx => core-modules/runtime-context.mdx} (50%) create mode 100644 docs-python/features/core-modules/telemetry.mdx create mode 100644 docs-python/features/rbs-services/adms.mdx create mode 100644 docs-python/features/rbs-services/dms.mdx create mode 100644 docs-python/features/rbs-services/output-management.mdx create mode 100644 docs-python/features/rbs-services/print-service.mdx diff --git a/docs-python/features/agent-framework.mdx b/docs-python/features/agent-framework.mdx deleted file mode 100644 index 07397d75d28..00000000000 --- a/docs-python/features/agent-framework.mdx +++ /dev/null @@ -1,202 +0,0 @@ ---- -id: agent-framework -title: Agent Modules -hide_title: false -hide_table_of_contents: false -sidebar_label: Agent Modules -description: Build AI-powered agents on SAP BTP using tool decorators, the Agent Gateway Service, and the Agent Memory Service -keywords: - - sap - - cloud - - sdk - - python - - agent - - ai - - mcp - - langchain - - agent gateway - - agent memory - - ai core ---- - -The Agent Framework provides the building blocks to create AI-powered agents on SAP BTP. -It consists of three main components: - -- **Tool Decorators** — register Python functions as callable tools within an agent loop -- **Agent Gateway Service** — discover MCP tools from connected SAP LoB systems -- **Agent Memory Service** — persist and retrieve conversation history and long-term memories - ---- - -## Tool Decorators - -Annotate any Python function with `@tool` to register it as a callable tool. -The decorator uses the function's type annotations to generate the tool's input schema and forwards the `description` to the LLM. - -```python -from sap_cloud_sdk.agent import tool - -@tool(description="Fetch the current status for a given order ID.") -def get_order_status(order_id: str) -> str: - # your business logic here - return f"Order {order_id} is currently: In Transit" - -@tool(description="List all open purchase orders for a given supplier.") -def list_open_orders(supplier_id: str, max_results: int = 10) -> list[dict]: - # call your backend system here - return [] -``` - -Decorated functions can be passed directly to a LangChain agent or any framework that accepts a list of tools. - ---- - -## Agent Gateway Service - -The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents. -It discovers MCP tools exposed by connected SAP LoB systems — such as SAP S/4HANA and SAP SuccessFactors — and wraps them as LangChain-compatible tools ready for use in an agent loop. - -### Discovering Tools - -```python -from sap_cloud_sdk.agentgateway import create_client -from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain - -agw_client = create_client(tenant_subdomain=get_tenant_subdomain) -mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) -tools = [ - mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) - for t in mcp_tools -] -``` - -:::note -`get_tenant_subdomain` and `get_user_token` must be **callables** (for example, functions reading from contextvars), not captured strings. -This ensures that credentials are resolved per request and never become stale. -::: - -### Calling a Tool Directly - -You can also call an MCP tool directly without converting to LangChain format: - -```python -result = await agw_client.call_mcp_tool( - tool=mcp_tools[0], - user_token=get_user_token, - order_id="4500012345" -) -``` - -### Filtering Tools by ORD ID - -When multiple MCP servers expose tools with overlapping names, use `MCPToolFilter` to scope discovery to a specific system: - -```python -from sap_cloud_sdk.agentgateway import AgentCardFilter - -tools = await agw_client.list_mcp_tools( - filter=MCPToolFilter(ord_ids=["sap.s4:purchaseOrder:v1"]) -) -``` - ---- - -## Agent Memory Service - -The Agent Memory Service provides a persistent, tenant-isolated store backed by SAP HANA Cloud. -It exposes two APIs: - -- **Messages API** — short-term conversation history, scoped to an agent, user, and session -- **Memories API** — long-term semantic storage with similarity search across sessions - -### Configuration - -The service is configured via a Kubernetes-mounted binding at `/etc/secrets/appfnd/hana-agent-memory/default`. -For local development, set the following environment variables: - -```bash -export HC_API_URL=https://.hanacloud.ondemand.com -export HC_CLIENT_ID= -export HC_CLIENT_SECRET= -export HC_AUTH_URL=https:///oauth/token -``` - -### Messages API - -Use the Messages API to store and replay conversation turns within a session: - -```python -from sap_cloud_sdk.agent_memory import create_client, MessageRole - -client = create_client(tenant=tenant_subdomain) - -# Store a conversation turn -client.add_message( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, role=MessageRole.USER, content=query -) -client.add_message( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, role=MessageRole.ASSISTANT, content=response -) - -# Replay history for a returning session -messages = client.list_messages( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, limit=50 -) -``` - -:::note -Since v0.36.0, the `tenant` argument is required when calling `create_client()`. Omitting it raises `AgentMemoryValidationError`. -::: - -### Memories API - -Use the Memories API to persist facts across sessions and retrieve the most relevant ones using semantic similarity search: - -```python -# Store a long-term fact about the user -client.add_memory( - agent_id="my-agent", invoker_id=user_id, - content="User prefers responses in English." -) - -# Retrieve relevant memories before generating a response -results = client.search_memories( - agent_id="my-agent", invoker_id=user_id, - query="preferred language", threshold=0.6, limit=5 -) -for r in results: - print(f"[{r.similarity:.2f}] {r.content}") -``` - -The `threshold` parameter (0.0–1.0) controls the minimum cosine similarity score for a memory to be returned. -A value of `0.6` is a reasonable starting point for most use cases. - ---- - -## SAP AI Core - -The AI Core module provides a Python client for [SAP AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from your application. -The SDK handles credential resolution and authentication automatically via the service binding. - -```python -from sap_cloud_sdk.ai_core import AICoreClient - -client = AICoreClient() -deployments = client.list_deployments(resource_group="default") - -for d in deployments: - print(d.id, d.status, d.model_name) -``` - -### Starting an Execution - -```python -execution = client.create_execution( - resource_group="default", - configuration_id="my-config-id" -) -print(execution.id, execution.status) -``` diff --git a/docs-python/features/agent-modules/agent-gateway.mdx b/docs-python/features/agent-modules/agent-gateway.mdx new file mode 100644 index 00000000000..defd8f096b1 --- /dev/null +++ b/docs-python/features/agent-modules/agent-gateway.mdx @@ -0,0 +1,62 @@ +--- +id: agent-gateway +title: Agent Gateway Service +hide_title: false +hide_table_of_contents: false +sidebar_label: Agent Gateway Service +description: Discover MCP tools from connected SAP LoB systems and use them in an agent loop +keywords: + - sap + - cloud + - sdk + - python + - agent gateway + - mcp + - langchain +--- + +The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents. +It discovers MCP tools exposed by connected SAP LoB systems — such as SAP S/4HANA and SAP SuccessFactors — and wraps them as LangChain-compatible tools ready for use in an agent loop. + +### Discovering Tools + +```python +from sap_cloud_sdk.agentgateway import create_client +from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain + +agw_client = create_client(tenant_subdomain=get_tenant_subdomain) +mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) +tools = [ + mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) + for t in mcp_tools +] +``` + +:::note +`get_tenant_subdomain` and `get_user_token` must be **callables** (for example, functions reading from contextvars), not captured strings. +This ensures that credentials are resolved per request and never become stale. +::: + +### Calling a Tool Directly + +You can also call an MCP tool directly without converting to LangChain format: + +```python +result = await agw_client.call_mcp_tool( + tool=mcp_tools[0], + user_token=get_user_token, + order_id="4500012345" +) +``` + +### Filtering Tools by ORD ID + +When multiple MCP servers expose tools with overlapping names, use `MCPToolFilter` to scope discovery to a specific system: + +```python +from sap_cloud_sdk.agentgateway import AgentCardFilter + +tools = await agw_client.list_mcp_tools( + filter=MCPToolFilter(ord_ids=["sap.s4:purchaseOrder:v1"]) +) +``` diff --git a/docs-python/features/agent-modules/agent-memory.mdx b/docs-python/features/agent-modules/agent-memory.mdx new file mode 100644 index 00000000000..356263e1364 --- /dev/null +++ b/docs-python/features/agent-modules/agent-memory.mdx @@ -0,0 +1,88 @@ +--- +id: agent-memory +title: Agent Memory Service +hide_title: false +hide_table_of_contents: false +sidebar_label: Agent Memory Service +description: Persist and retrieve conversation history and long-term semantic memories with the Agent Memory Service +keywords: + - sap + - cloud + - sdk + - python + - agent memory + - hana cloud + - conversation history + - semantic search +--- + +The Agent Memory Service provides a persistent, tenant-isolated store backed by SAP HANA Cloud. +It exposes two APIs: + +- **Messages API** — short-term conversation history, scoped to an agent, user, and session +- **Memories API** — long-term semantic storage with similarity search across sessions + +### Configuration + +The service is configured via a Kubernetes-mounted binding at `/etc/secrets/appfnd/hana-agent-memory/default`. +For local development, set the following environment variables: + +```bash +export HC_API_URL=https://.hanacloud.ondemand.com +export HC_CLIENT_ID= +export HC_CLIENT_SECRET= +export HC_AUTH_URL=https:///oauth/token +``` + +### Messages API + +Use the Messages API to store and replay conversation turns within a session: + +```python +from sap_cloud_sdk.agent_memory import create_client, MessageRole + +client = create_client(tenant=tenant_subdomain) + +# Store a conversation turn +client.add_message( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, role=MessageRole.USER, content=query +) +client.add_message( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, role=MessageRole.ASSISTANT, content=response +) + +# Replay history for a returning session +messages = client.list_messages( + agent_id="my-agent", invoker_id=user_id, + message_group=session_id, limit=50 +) +``` + +:::note +Since v0.36.0, the `tenant` argument is required when calling `create_client()`. Omitting it raises `AgentMemoryValidationError`. +::: + +### Memories API + +Use the Memories API to persist facts across sessions and retrieve the most relevant ones using semantic similarity search: + +```python +# Store a long-term fact about the user +client.add_memory( + agent_id="my-agent", invoker_id=user_id, + content="User prefers responses in English." +) + +# Retrieve relevant memories before generating a response +results = client.search_memories( + agent_id="my-agent", invoker_id=user_id, + query="preferred language", threshold=0.6, limit=5 +) +for r in results: + print(f"[{r.similarity:.2f}] {r.content}") +``` + +The `threshold` parameter (0.0–1.0) controls the minimum cosine similarity score for a memory to be returned. +A value of `0.6` is a reasonable starting point for most use cases. diff --git a/docs-python/features/agent-modules/ai-core.mdx b/docs-python/features/agent-modules/ai-core.mdx new file mode 100644 index 00000000000..41ce67f7219 --- /dev/null +++ b/docs-python/features/agent-modules/ai-core.mdx @@ -0,0 +1,39 @@ +--- +id: ai-core +title: SAP AI Core +hide_title: false +hide_table_of_contents: false +sidebar_label: SAP AI Core +description: Manage AI scenarios, deployments, and executions with the SAP AI Core Python client +keywords: + - sap + - cloud + - sdk + - python + - ai core + - deployments + - executions +--- + +The AI Core module provides a Python client for [SAP AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from your application. +The SDK handles credential resolution and authentication automatically via the service binding. + +```python +from sap_cloud_sdk.ai_core import AICoreClient + +client = AICoreClient() +deployments = client.list_deployments(resource_group="default") + +for d in deployments: + print(d.id, d.status, d.model_name) +``` + +### Starting an Execution + +```python +execution = client.create_execution( + resource_group="default", + configuration_id="my-config-id" +) +print(execution.id, execution.status) +``` diff --git a/docs-python/features/agent-modules/tool-decorators.mdx b/docs-python/features/agent-modules/tool-decorators.mdx new file mode 100644 index 00000000000..8cef3466b41 --- /dev/null +++ b/docs-python/features/agent-modules/tool-decorators.mdx @@ -0,0 +1,34 @@ +--- +id: tool-decorators +title: Tool Decorators +hide_title: false +hide_table_of_contents: false +sidebar_label: Tool Decorators +description: Register Python functions as callable agent tools using the @tool decorator +keywords: + - sap + - cloud + - sdk + - python + - agent + - tool decorator +--- + +Annotate any Python function with `@tool` to register it as a callable tool. +The decorator uses the function's type annotations to generate the tool's input schema and forwards the `description` to the LLM. + +```python +from sap_cloud_sdk.agent import tool + +@tool(description="Fetch the current status for a given order ID.") +def get_order_status(order_id: str) -> str: + # your business logic here + return f"Order {order_id} is currently: In Transit" + +@tool(description="List all open purchase orders for a given supplier.") +def list_open_orders(supplier_id: str, max_results: int = 10) -> list[dict]: + # call your backend system here + return [] +``` + +Decorated functions can be passed directly to a LangChain agent or any framework that accepts a list of tools. diff --git a/docs-python/features/btp-services.mdx b/docs-python/features/btp-services.mdx deleted file mode 100644 index e111333ce3f..00000000000 --- a/docs-python/features/btp-services.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -id: btp-services -title: RBS Services -hide_title: false -hide_table_of_contents: false -sidebar_label: RBS Services -description: Use SAP RBS services from Python — DMS, ADMS, Output Management, and Print Service -keywords: - - sap - - cloud - - sdk - - python - - dms - - adms - - document management - - output management - - print service ---- - -## DMS - -The Document Management module provides a client for [SAP Document Management Service](https://help.sap.com/docs/document-management-service), enabling you to manage documents and folders in a repository. - -```python -from sap_cloud_sdk.document_management import DocumentManagementClient - -client = DocumentManagementClient() -folder = client.create_folder(repository_id="my-repo", path="/invoices/2026") -document = client.upload_document( - repository_id="my-repo", - folder_id=folder.id, - file_name="invoice-001.pdf", - content=pdf_bytes -) -``` - ---- - -## ADMS - -The Advanced Document Management Service (ADMS) module provides a typed Python client for the [SAP Advanced Document Management Service](https://help.sap.com/docs/advanced-document-management) OData V4 API. -Credentials are read from the service binding at `/etc/secrets/appfnd/adms/default/` or the `CLOUD_SDK_CFG_ADMS_DEFAULT_*` environment variables. - -### Creating a Client - -```python -from sap_cloud_sdk.adms import create_client - -client = create_client() -``` - -For per-user policy enforcement, pass a user JWT: - -```python -client = create_client(user_jwt=request_token) -# or scope an existing client to a user: -user_client = client.with_user_jwt(request_token) -``` - -### Managing Documents - -```python -# List all document relations -relations = client.relations.get_all() - -# Create a new document relation and generate upload URLs -relation = client.relations.create(input=CreateDocumentRelationInput(...)) -upload_urls = client.relations.generate_upload_urls( - document_relation_id=relation.id, - file_count=1, - file_size_in_bytes=len(pdf_bytes) -) - -# Retrieve a document -document = client.documents.get(document_relation_id=relation.id) -download_url = client.documents.get_download_url( - document_relation_id=relation.id, - doc_content_version_id=document.content_version_id -) -``` - -### Draft Workflow - -```python -from sap_cloud_sdk.adms import DraftInput, DraftActivateInput - -# Create and activate a draft -draft_relations = client.relations.create_draft(draft_input=DraftInput(...)) -client.relations.validate_draft(draft_input=DraftInput(...)) -client.relations.activate_draft(input=DraftActivateInput(...)) - -# Or discard -client.relations.discard_draft(draft_input=DraftInput(...)) -``` - -### Background Jobs - -```python -from sap_cloud_sdk.adms import ZipDownloadJobParameters - -job = client.jobs.start_zip_download(params=ZipDownloadJobParameters( - document_relation_ids=["id-1", "id-2"] -)) -status = client.jobs.get_status(job_id=job.job_id) -``` - -### Async Client - -```python -from sap_cloud_sdk.adms import create_async_client - -async with create_async_client() as client: - relations = await client.relations.get_all() -``` - ---- - -## Output Management Service - -The Output Management module provides a client for creating and sending output requests — including emails and print documents — via the [SAP Output Management Service](https://help.sap.com/docs/output-management). - -```python -from sap_cloud_sdk.outputmanagement import OutputManagementClient - -client = OutputManagementClient() - -# Send an email -client.send_output_request( - template_id="invoice-email-template", - recipient="customer@example.com", - data={"invoice_number": "INV-001", "amount": "1,500.00 EUR"} -) -``` - ---- - -## Print Service - -The Print Service module provides a client for [SAP Print Service](https://help.sap.com/docs/print-service), enabling you to manage print queues, upload documents, and submit print tasks. -Credentials are read from the service binding at `$SERVICE_BINDING_ROOT/print/default/` or the `CLOUD_SDK_CFG_PRINT_DEFAULT_*` environment variables. - -### Creating a Client - -```python -from sap_cloud_sdk.print import create_client - -client = create_client() -``` - -### Uploading and Printing a Document - -```python -from sap_cloud_sdk.print import PrintTask, PrintContent - -# Upload the document to cloud storage -with open("invoice.pdf", "rb") as f: - doc_id = client.upload_document(f, filename="invoice.pdf") - -# Submit a print task -client.create_print_task(PrintTask( - item_id=doc_id, - qname="my-print-queue", - print_contents=[PrintContent(object_key=doc_id, document_name="invoice.pdf")], - number_of_copies=1, -)) -``` - -### Managing Print Queues - -```python -from sap_cloud_sdk.print import PrintQueue - -# List available queues -queues = client.list_queues() - -# Create a new queue -client.create_queue(PrintQueue( - qname="INVOICES", - qdescription="Invoice printing queue", - cleanup_prd=3, -)) - -# Get print profiles for a queue -profiles = client.get_print_profiles(qname="INVOICES") -``` diff --git a/docs-python/features/connectivity.mdx b/docs-python/features/connectivity.mdx deleted file mode 100644 index b8b76065b97..00000000000 --- a/docs-python/features/connectivity.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: connectivity -title: Connectivity and Identity -hide_title: false -hide_table_of_contents: false -sidebar_label: Connectivity & Identity -description: Connect to remote systems, handle authentication, and manage user identity with the SAP Cloud SDK for Python -keywords: - - sap - - cloud - - sdk - - python - - destination - - connectivity - - ias - - identity - - authentication ---- - -## Destination Service - -The Destination Service module provides an abstraction for connecting to remote systems defined in the SAP BTP Cockpit. -It resolves credentials, handles OAuth flows, and supports both cloud and on-premise systems via the SAP Connectivity Service. - -```python -from sap_cloud_sdk.destination import DestinationService - -service = DestinationService() -destination = service.get_destination("my-destination") -``` - -The SDK supports all standard destination authentication types, including Basic Authentication, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Principal Propagation. - -### Using a Destination with an HTTP Client - -Once you have a destination, you can pass it directly to the destination-aware HTTP client: - -```python -from sap_cloud_sdk.destination import DestinationService -from sap_cloud_sdk.http_client import DestinationHttpClient - -service = DestinationService() -destination = service.get_destination("my-s4-system") - -client = DestinationHttpClient(destination) -response = client.get("/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner") -``` - -The client automatically applies the destination's credentials, headers, and proxy configuration to every request. - ---- - -## Identity and Access Service (IAS) - -The IAS module handles authentication and token management for applications secured with [SAP Cloud Identity Services](https://help.sap.com/docs/identity-authentication). -IAS is the primary identity provider for new Python SDK applications — XSUAA is out of scope. - -### Token Verification - -Verify incoming JWTs from SAP Cloud Identity Services: - -```python -from sap_cloud_sdk.ias import IASTokenVerifier - -verifier = IASTokenVerifier() -token_claims = verifier.verify(request_token) -user_id = token_claims.subject -tenant = token_claims.zone_uuid -``` - -### Service-to-Service Authentication - -For service-to-service calls, the SDK handles the client credentials flow automatically when the IAS binding is present: - -```python -from sap_cloud_sdk.ias import IASClient - -ias_client = IASClient() -token = ias_client.get_service_token(target_service="my-backend-service") -``` - ---- - -## Multi-Tenancy - -The SDK applies tenant isolation throughout by default. -The current tenant is resolved from the incoming request token and propagated automatically to destination lookups, memory operations, and other SDK calls. - -You can also provide the tenant subdomain explicitly when needed: - -```python -from sap_cloud_sdk.destination import DestinationService - -service = DestinationService() -destination = service.get_destination("my-destination", tenant_subdomain="acme-corp") -``` - ---- - -## Secret Management - -The Secret Management module provides a unified interface for reading credentials and configuration values. -The SDK resolves secrets from multiple sources in the following priority order: - -1. Kubernetes-mounted secrets via `SERVICE_BINDING_ROOT` (following the [servicebinding.io](https://servicebinding.io/) specification) -2. Environment variables using the pattern `CLOUD_SDK_CFG___` - -This means the same application code runs locally (using env vars) and in Kubernetes (using mounted secrets) without any modification. - -### Example: Reading a Secret - -```python -from sap_cloud_sdk.secret_management import SecretManager - -manager = SecretManager() -api_key = manager.get_secret(module="my-service", instance="default", field="api-key") -``` - -### Local Development with Environment Variables - -Set the environment variable pattern to simulate a Kubernetes binding locally: - -```bash -export CLOUD_SDK_CFG_MY_SERVICE_DEFAULT_API_KEY=my-local-api-key -``` diff --git a/docs-python/features/connectivity/destination-service.mdx b/docs-python/features/connectivity/destination-service.mdx new file mode 100644 index 00000000000..c082f62a277 --- /dev/null +++ b/docs-python/features/connectivity/destination-service.mdx @@ -0,0 +1,46 @@ +--- +id: destination-service +title: Destination Service +hide_title: false +hide_table_of_contents: false +sidebar_label: Destination Service +description: Connect to remote systems and resolve credentials using the SAP BTP Destination Service +keywords: + - sap + - cloud + - sdk + - python + - destination + - connectivity + - oauth + - authentication +--- + +The Destination Service module provides an abstraction for connecting to remote systems defined in the SAP BTP Cockpit. +It resolves credentials, handles OAuth flows, and supports both cloud and on-premise systems via the SAP Connectivity Service. + +```python +from sap_cloud_sdk.destination import DestinationService + +service = DestinationService() +destination = service.get_destination("my-destination") +``` + +The SDK supports all standard destination authentication types, including Basic Authentication, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Principal Propagation. + +### Using a Destination with an HTTP Client + +Once you have a destination, you can pass it directly to the destination-aware HTTP client: + +```python +from sap_cloud_sdk.destination import DestinationService +from sap_cloud_sdk.http_client import DestinationHttpClient + +service = DestinationService() +destination = service.get_destination("my-s4-system") + +client = DestinationHttpClient(destination) +response = client.get("/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner") +``` + +The client automatically applies the destination's credentials, headers, and proxy configuration to every request. diff --git a/docs-python/features/connectivity/identity-ias.mdx b/docs-python/features/connectivity/identity-ias.mdx new file mode 100644 index 00000000000..b67ac520882 --- /dev/null +++ b/docs-python/features/connectivity/identity-ias.mdx @@ -0,0 +1,44 @@ +--- +id: identity-ias +title: Identity and Access Service (IAS) +hide_title: false +hide_table_of_contents: false +sidebar_label: Identity (IAS) +description: Verify JWTs and handle service-to-service authentication with SAP Cloud Identity Services +keywords: + - sap + - cloud + - sdk + - python + - ias + - identity + - jwt + - authentication +--- + +The IAS module handles authentication and token management for applications secured with [SAP Cloud Identity Services](https://help.sap.com/docs/identity-authentication). +IAS is the primary identity provider for new Python SDK applications — XSUAA is out of scope. + +### Token Verification + +Verify incoming JWTs from SAP Cloud Identity Services: + +```python +from sap_cloud_sdk.ias import IASTokenVerifier + +verifier = IASTokenVerifier() +token_claims = verifier.verify(request_token) +user_id = token_claims.subject +tenant = token_claims.zone_uuid +``` + +### Service-to-Service Authentication + +For service-to-service calls, the SDK handles the client credentials flow automatically when the IAS binding is present: + +```python +from sap_cloud_sdk.ias import IASClient + +ias_client = IASClient() +token = ias_client.get_service_token(target_service="my-backend-service") +``` diff --git a/docs-python/features/connectivity/multi-tenancy.mdx b/docs-python/features/connectivity/multi-tenancy.mdx new file mode 100644 index 00000000000..eb9bf93ec6d --- /dev/null +++ b/docs-python/features/connectivity/multi-tenancy.mdx @@ -0,0 +1,27 @@ +--- +id: multi-tenancy +title: Multi-Tenancy +hide_title: false +hide_table_of_contents: false +sidebar_label: Multi-Tenancy +description: Build tenant-aware applications with automatic tenant isolation across SDK calls +keywords: + - sap + - cloud + - sdk + - python + - multi-tenancy + - tenant isolation +--- + +The SDK applies tenant isolation throughout by default. +The current tenant is resolved from the incoming request token and propagated automatically to destination lookups, memory operations, and other SDK calls. + +You can also provide the tenant subdomain explicitly when needed: + +```python +from sap_cloud_sdk.destination import DestinationService + +service = DestinationService() +destination = service.get_destination("my-destination", tenant_subdomain="acme-corp") +``` diff --git a/docs-python/features/connectivity/secret-management.mdx b/docs-python/features/connectivity/secret-management.mdx new file mode 100644 index 00000000000..3b6105103f1 --- /dev/null +++ b/docs-python/features/connectivity/secret-management.mdx @@ -0,0 +1,42 @@ +--- +id: secret-management +title: Secret Management +hide_title: false +hide_table_of_contents: false +sidebar_label: Secret Management +description: Read credentials and configuration from Kubernetes-mounted secrets or environment variables +keywords: + - sap + - cloud + - sdk + - python + - secret management + - kubernetes + - service binding + - environment variables +--- + +The Secret Management module provides a unified interface for reading credentials and configuration values. +The SDK resolves secrets from multiple sources in the following priority order: + +1. Kubernetes-mounted secrets via `SERVICE_BINDING_ROOT` (following the [servicebinding.io](https://servicebinding.io/) specification) +2. Environment variables using the pattern `CLOUD_SDK_CFG___` + +This means the same application code runs locally (using env vars) and in Kubernetes (using mounted secrets) without any modification. + +### Example: Reading a Secret + +```python +from sap_cloud_sdk.secret_management import SecretManager + +manager = SecretManager() +api_key = manager.get_secret(module="my-service", instance="default", field="api-key") +``` + +### Local Development with Environment Variables + +Set the environment variable pattern to simulate a Kubernetes binding locally: + +```bash +export CLOUD_SDK_CFG_MY_SERVICE_DEFAULT_API_KEY=my-local-api-key +``` diff --git a/docs-python/features/core-modules/audit-logging.mdx b/docs-python/features/core-modules/audit-logging.mdx new file mode 100644 index 00000000000..66dd24e0b88 --- /dev/null +++ b/docs-python/features/core-modules/audit-logging.mdx @@ -0,0 +1,41 @@ +--- +id: audit-logging +title: Audit Logging +hide_title: false +hide_table_of_contents: false +sidebar_label: Audit Logging +description: Emit structured audit log events to the SAP Audit Log Service from your Python application +keywords: + - sap + - cloud + - sdk + - python + - audit log + - compliance +--- + +The Audit Logging module provides a structured way to emit audit log events to the [SAP Audit Log Service](https://help.sap.com/docs/audit-log-service). +Both the standard and the next-generation (NG) audit log APIs are supported. + +### Data Access Events + +```python +from sap_cloud_sdk.audit_log import AuditLogger + +logger = AuditLogger() +logger.log_data_access( + object_type="BusinessPartner", + object_id="1000001", + attributes=["Name", "Address"] +) +``` + +### Data Modification Events + +```python +logger.log_data_modification( + object_type="SalesOrder", + object_id="SO-4500012345", + attributes=[{"name": "Status", "old_value": "Open", "new_value": "Closed"}] +) +``` diff --git a/docs-python/features/core-modules/object-storage.mdx b/docs-python/features/core-modules/object-storage.mdx new file mode 100644 index 00000000000..c694e482767 --- /dev/null +++ b/docs-python/features/core-modules/object-storage.mdx @@ -0,0 +1,34 @@ +--- +id: object-storage +title: Object Storage +hide_title: false +hide_table_of_contents: false +sidebar_label: Object Storage +description: Upload, download, list, and delete objects with the SAP BTP Object Store Service +keywords: + - sap + - cloud + - sdk + - python + - object storage + - object store + - files +--- + +The Object Storage module provides a client for SAP BTP Object Store Service, allowing you to upload, download, list, and delete objects. + +```python +from sap_cloud_sdk.object_storage import ObjectStorageClient + +client = ObjectStorageClient() + +# Upload a file +with open("report.pdf", "rb") as f: + client.upload(bucket="my-bucket", key="reports/2026/report.pdf", body=f) + +# Download a file +content = client.download(bucket="my-bucket", key="reports/2026/report.pdf") + +# List objects +objects = client.list(bucket="my-bucket", prefix="reports/") +``` diff --git a/docs-python/features/core-modules.mdx b/docs-python/features/core-modules/runtime-context.mdx similarity index 50% rename from docs-python/features/core-modules.mdx rename to docs-python/features/core-modules/runtime-context.mdx index b83eb42156b..54c6894d89c 100644 --- a/docs-python/features/core-modules.mdx +++ b/docs-python/features/core-modules/runtime-context.mdx @@ -1,108 +1,21 @@ --- -id: core-modules -title: Core Modules +id: runtime-context +title: Runtime Context hide_title: false hide_table_of_contents: false -sidebar_label: Core Modules -description: Cross-cutting SDK modules — Audit Logging, Telemetry & Observability, Object Storage, and Runtime Context +sidebar_label: Runtime Context +description: Propagate tenant, user, and trigger-type context across async tasks without framework coupling keywords: - sap - cloud - sdk - python - - audit log - - telemetry - - opentelemetry - - object storage - runtime context + - tenant + - multi-tenancy + - context propagation --- -## Audit Logging - -The Audit Logging module provides a structured way to emit audit log events to the [SAP Audit Log Service](https://help.sap.com/docs/audit-log-service). -Both the standard and the next-generation (NG) audit log APIs are supported. - -### Data Access Events - -```python -from sap_cloud_sdk.audit_log import AuditLogger - -logger = AuditLogger() -logger.log_data_access( - object_type="BusinessPartner", - object_id="1000001", - attributes=["Name", "Address"] -) -``` - -### Data Modification Events - -```python -logger.log_data_modification( - object_type="SalesOrder", - object_id="SO-4500012345", - attributes=[{"name": "Status", "old_value": "Open", "new_value": "Closed"}] -) -``` - ---- - -## Telemetry & Observability - -The Telemetry module provides observability utilities built on top of [OpenTelemetry](https://opentelemetry.io/). -It auto-instruments SDK HTTP clients and common Python frameworks, exporting traces and metrics to any OpenTelemetry-compatible backend such as SAP Cloud Logging. - -### Setup - -Call `auto_instrument()` once at application startup: - -```python -from sap_cloud_sdk.telemetry import auto_instrument - -auto_instrument() -``` - -This sets up trace propagation and metric collection for all SDK operations and outbound HTTP requests without any further configuration. - -### Custom Spans - -You can also create custom spans to trace your own business logic: - -```python -from opentelemetry import trace - -tracer = trace.get_tracer("my-agent") - -with tracer.start_as_current_span("process-order"): - result = process_order(order_id) -``` - ---- - -## Object Storage - -The Object Storage module provides a client for SAP BTP Object Store Service, allowing you to upload, download, list, and delete objects. - -```python -from sap_cloud_sdk.object_storage import ObjectStorageClient - -client = ObjectStorageClient() - -# Upload a file -with open("report.pdf", "rb") as f: - client.upload(bucket="my-bucket", key="reports/2026/report.pdf", body=f) - -# Download a file -content = client.download(bucket="my-bucket", key="reports/2026/report.pdf") - -# List objects -objects = client.list(bucket="my-bucket", prefix="reports/") -``` - ---- - -## Runtime Context - The Runtime Context module propagates caller-identity information — tenant, user, and trigger type — across any invocation source (HTTP, gRPC, message queue) without coupling to a specific framework. It uses a `ContextVar` so context is scoped per async task or thread. diff --git a/docs-python/features/core-modules/telemetry.mdx b/docs-python/features/core-modules/telemetry.mdx new file mode 100644 index 00000000000..ebae9e5b041 --- /dev/null +++ b/docs-python/features/core-modules/telemetry.mdx @@ -0,0 +1,45 @@ +--- +id: telemetry +title: Telemetry & Observability +hide_title: false +hide_table_of_contents: false +sidebar_label: Telemetry & Observability +description: Auto-instrument your application with OpenTelemetry traces and metrics for SAP Cloud Logging +keywords: + - sap + - cloud + - sdk + - python + - telemetry + - opentelemetry + - tracing + - observability +--- + +The Telemetry module provides observability utilities built on top of [OpenTelemetry](https://opentelemetry.io/). +It auto-instruments SDK HTTP clients and common Python frameworks, exporting traces and metrics to any OpenTelemetry-compatible backend such as SAP Cloud Logging. + +### Setup + +Call `auto_instrument()` once at application startup: + +```python +from sap_cloud_sdk.telemetry import auto_instrument + +auto_instrument() +``` + +This sets up trace propagation and metric collection for all SDK operations and outbound HTTP requests without any further configuration. + +### Custom Spans + +You can also create custom spans to trace your own business logic: + +```python +from opentelemetry import trace + +tracer = trace.get_tracer("my-agent") + +with tracer.start_as_current_span("process-order"): + result = process_order(order_id) +``` diff --git a/docs-python/features/rbs-services/adms.mdx b/docs-python/features/rbs-services/adms.mdx new file mode 100644 index 00000000000..5b60d4e3b58 --- /dev/null +++ b/docs-python/features/rbs-services/adms.mdx @@ -0,0 +1,91 @@ +--- +id: adms +title: ADMS +hide_title: false +hide_table_of_contents: false +sidebar_label: ADMS +description: Interact with the SAP Advanced Document Management Service OData V4 API from Python +keywords: + - sap + - cloud + - sdk + - python + - adms + - advanced document management + - odata +--- + +The Advanced Document Management Service (ADMS) module provides a typed Python client for the [SAP Advanced Document Management Service](https://help.sap.com/docs/advanced-document-management) OData V4 API. +Credentials are read from the service binding at `/etc/secrets/appfnd/adms/default/` or the `CLOUD_SDK_CFG_ADMS_DEFAULT_*` environment variables. + +### Creating a Client + +```python +from sap_cloud_sdk.adms import create_client + +client = create_client() +``` + +For per-user policy enforcement, pass a user JWT: + +```python +client = create_client(user_jwt=request_token) +# or scope an existing client to a user: +user_client = client.with_user_jwt(request_token) +``` + +### Managing Documents + +```python +# List all document relations +relations = client.relations.get_all() + +# Create a new document relation and generate upload URLs +relation = client.relations.create(input=CreateDocumentRelationInput(...)) +upload_urls = client.relations.generate_upload_urls( + document_relation_id=relation.id, + file_count=1, + file_size_in_bytes=len(pdf_bytes) +) + +# Retrieve a document +document = client.documents.get(document_relation_id=relation.id) +download_url = client.documents.get_download_url( + document_relation_id=relation.id, + doc_content_version_id=document.content_version_id +) +``` + +### Draft Workflow + +```python +from sap_cloud_sdk.adms import DraftInput, DraftActivateInput + +# Create and activate a draft +draft_relations = client.relations.create_draft(draft_input=DraftInput(...)) +client.relations.validate_draft(draft_input=DraftInput(...)) +client.relations.activate_draft(input=DraftActivateInput(...)) + +# Or discard +client.relations.discard_draft(draft_input=DraftInput(...)) +``` + +### Background Jobs + +```python +from sap_cloud_sdk.adms import ZipDownloadJobParameters + +job = client.jobs.start_zip_download(params=ZipDownloadJobParameters( + document_relation_ids=["id-1", "id-2"] +)) +status = client.jobs.get_status(job_id=job.job_id) +``` + +### Async Client + +```python +from sap_cloud_sdk.adms import create_async_client + +async with create_async_client() as client: + relations = await client.relations.get_all() +``` diff --git a/docs-python/features/rbs-services/dms.mdx b/docs-python/features/rbs-services/dms.mdx new file mode 100644 index 00000000000..b1f29c5dfd3 --- /dev/null +++ b/docs-python/features/rbs-services/dms.mdx @@ -0,0 +1,30 @@ +--- +id: dms +title: DMS +hide_title: false +hide_table_of_contents: false +sidebar_label: DMS +description: Manage documents and folders in a repository with the SAP Document Management Service +keywords: + - sap + - cloud + - sdk + - python + - dms + - document management +--- + +The Document Management module provides a client for [SAP Document Management Service](https://help.sap.com/docs/document-management-service), enabling you to manage documents and folders in a repository. + +```python +from sap_cloud_sdk.document_management import DocumentManagementClient + +client = DocumentManagementClient() +folder = client.create_folder(repository_id="my-repo", path="/invoices/2026") +document = client.upload_document( + repository_id="my-repo", + folder_id=folder.id, + file_name="invoice-001.pdf", + content=pdf_bytes +) +``` diff --git a/docs-python/features/rbs-services/output-management.mdx b/docs-python/features/rbs-services/output-management.mdx new file mode 100644 index 00000000000..d7f80f8a22f --- /dev/null +++ b/docs-python/features/rbs-services/output-management.mdx @@ -0,0 +1,31 @@ +--- +id: output-management +title: Output Management Service +hide_title: false +hide_table_of_contents: false +sidebar_label: Output Management Service +description: Create and send output requests — emails and print documents — via the SAP Output Management Service +keywords: + - sap + - cloud + - sdk + - python + - output management + - email + - print +--- + +The Output Management module provides a client for creating and sending output requests — including emails and print documents — via the [SAP Output Management Service](https://help.sap.com/docs/output-management). + +```python +from sap_cloud_sdk.outputmanagement import OutputManagementClient + +client = OutputManagementClient() + +# Send an email +client.send_output_request( + template_id="invoice-email-template", + recipient="customer@example.com", + data={"invoice_number": "INV-001", "amount": "1,500.00 EUR"} +) +``` diff --git a/docs-python/features/rbs-services/print-service.mdx b/docs-python/features/rbs-services/print-service.mdx new file mode 100644 index 00000000000..1383ffdeb33 --- /dev/null +++ b/docs-python/features/rbs-services/print-service.mdx @@ -0,0 +1,63 @@ +--- +id: print-service +title: Print Service +hide_title: false +hide_table_of_contents: false +sidebar_label: Print Service +description: Manage print queues, upload documents, and submit print tasks with the SAP Print Service +keywords: + - sap + - cloud + - sdk + - python + - print service + - print queue +--- + +The Print Service module provides a client for [SAP Print Service](https://help.sap.com/docs/print-service), enabling you to manage print queues, upload documents, and submit print tasks. +Credentials are read from the service binding at `$SERVICE_BINDING_ROOT/print/default/` or the `CLOUD_SDK_CFG_PRINT_DEFAULT_*` environment variables. + +### Creating a Client + +```python +from sap_cloud_sdk.print import create_client + +client = create_client() +``` + +### Uploading and Printing a Document + +```python +from sap_cloud_sdk.print import PrintTask, PrintContent + +# Upload the document to cloud storage +with open("invoice.pdf", "rb") as f: + doc_id = client.upload_document(f, filename="invoice.pdf") + +# Submit a print task +client.create_print_task(PrintTask( + item_id=doc_id, + qname="my-print-queue", + print_contents=[PrintContent(object_key=doc_id, document_name="invoice.pdf")], + number_of_copies=1, +)) +``` + +### Managing Print Queues + +```python +from sap_cloud_sdk.print import PrintQueue + +# List available queues +queues = client.list_queues() + +# Create a new queue +client.create_queue(PrintQueue( + qname="INVOICES", + qdescription="Invoice printing queue", + cleanup_prd=3, +)) + +# Get print profiles for a queue +profiles = client.get_print_profiles(qname="INVOICES") +``` diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index 0e3eb35e175..32bfb9302ad 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -57,7 +57,7 @@ This discovers MCP tools from connected SAP LoB systems (S/4HANA, SuccessFactors The Agent Modules are the core differentiator of the Python SDK. It provides building blocks for AI-powered agents running on SAP BTP: a `@tool` decorator to register Python functions as agent tools, the **Agent Gateway Service** for discovering MCP tools from connected LoB systems with tenant-aware principal propagation, the **Agent Memory Service** for storing and retrieving conversation history and long-term semantic memories backed by SAP HANA Cloud, and a client for **SAP AI Core** to manage deployments and executions. -For details and code examples, see the [Agent Modules](features/agent-framework) guide. +For details and code examples, see the [Agent Modules](features/agent-modules/tool-decorators) guide. ### Connectivity and Identity @@ -65,19 +65,19 @@ The SDK abstracts the details of connecting to remote systems defined in the SAP The Destination Service module resolves credentials, handles OAuth flows (including principal propagation and client credentials), and supports both cloud and on-premise systems. The Identity and Access Service (IAS) module handles token verification and user context propagation for applications secured with SAP Cloud Identity Services. -For details and code examples, see the [Connectivity and Identity](features/connectivity) guide. +For details and code examples, see the [Connectivity and Identity](features/connectivity/destination-service) guide. ### Core Modules The SDK includes cross-cutting modules that apply to any application type: **Audit Logging** for emitting structured events to the SAP Audit Log Service, **Telemetry & Observability** for auto-instrumented OpenTelemetry traces and metrics exported to SAP Cloud Logging, **Object Storage** for managing files on SAP BTP Object Store Service, and **Runtime Context** for propagating tenant, user, and trigger-type information across async tasks without coupling to a specific framework. -For details and code examples, see the [Core Modules](features/core-modules) guide. +For details and code examples, see the [Core Modules](features/core-modules/audit-logging) guide. ### RBS Services The SDK provides clients for SAP RBS services: **DMS** for managing documents and folders in a repository, **ADMS** for the Advanced Document Management Service, **Output Management** for creating and sending output requests, and **Print Service** for managing print queues and submitting print tasks. -For details and code examples, see the [RBS Services](features/btp-services) guide. +For details and code examples, see the [RBS Services](features/rbs-services/dms) guide. ## Further Information diff --git a/sidebarsDocsPython.js b/sidebarsDocsPython.js index 7ae4f2d29e3..478c0ee4d9f 100644 --- a/sidebarsDocsPython.js +++ b/sidebarsDocsPython.js @@ -7,10 +7,50 @@ module.exports = { label: 'Features', collapsed: false, items: [ - 'features/agent-framework', - 'features/connectivity', - 'features/core-modules', - 'features/btp-services', + { + type: 'category', + label: 'Agent Modules', + collapsed: false, + items: [ + 'features/agent-modules/tool-decorators', + 'features/agent-modules/agent-gateway', + 'features/agent-modules/agent-memory', + 'features/agent-modules/ai-core', + ] + }, + { + type: 'category', + label: 'Connectivity & Identity', + collapsed: false, + items: [ + 'features/connectivity/destination-service', + 'features/connectivity/identity-ias', + 'features/connectivity/multi-tenancy', + 'features/connectivity/secret-management', + ] + }, + { + type: 'category', + label: 'Core Modules', + collapsed: false, + items: [ + 'features/core-modules/audit-logging', + 'features/core-modules/telemetry', + 'features/core-modules/object-storage', + 'features/core-modules/runtime-context', + ] + }, + { + type: 'category', + label: 'RBS Services', + collapsed: false, + items: [ + 'features/rbs-services/dms', + 'features/rbs-services/adms', + 'features/rbs-services/output-management', + 'features/rbs-services/print-service', + ] + }, ] }, 'release-notes', From 48001a8c20ee4daf88bd4774c9e832a770b0676d Mon Sep 17 00:00:00 2001 From: I769216 Date: Mon, 24 Aug 2026 12:00:50 -0300 Subject: [PATCH 14/20] rename AI Core module --- docs-python/features/agent-modules/ai-core.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs-python/features/agent-modules/ai-core.mdx b/docs-python/features/agent-modules/ai-core.mdx index 41ce67f7219..d51f76eb35f 100644 --- a/docs-python/features/agent-modules/ai-core.mdx +++ b/docs-python/features/agent-modules/ai-core.mdx @@ -1,9 +1,9 @@ --- id: ai-core -title: SAP AI Core +title: AI Core hide_title: false hide_table_of_contents: false -sidebar_label: SAP AI Core +sidebar_label: AI Core description: Manage AI scenarios, deployments, and executions with the SAP AI Core Python client keywords: - sap @@ -15,7 +15,7 @@ keywords: - executions --- -The AI Core module provides a Python client for [SAP AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from your application. +The AI Core module provides a Python client for [AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from your application. The SDK handles credential resolution and authentication automatically via the service binding. ```python From cb3206441528c2c56a5d1662409d36ad4deabc91 Mon Sep 17 00:00:00 2001 From: I769216 Date: Wed, 26 Aug 2026 13:53:40 -0300 Subject: [PATCH 15/20] refactoring modules content --- .../features/agent-modules/agent-gateway.mdx | 49 ++++------ .../features/agent-modules/agent-memory.mdx | 71 +++------------ .../features/agent-modules/ai-core.mdx | 33 +++---- .../agent-modules/tool-decorators.mdx | 63 +++++++++---- .../connectivity/destination-service.mdx | 22 ++--- .../features/connectivity/identity-ias.mdx | 43 +++++---- .../features/connectivity/multi-tenancy.mdx | 27 ------ .../connectivity/secret-management.mdx | 56 +++++++----- .../features/core-modules/audit-logging.mdx | 42 ++++++--- .../features/core-modules/object-storage.mdx | 31 ++++--- .../features/core-modules/runtime-context.mdx | 77 ++++++---------- .../features/core-modules/telemetry.mdx | 30 +++---- docs-python/features/rbs-services/adms.mdx | 90 ++++++------------- docs-python/features/rbs-services/dms.mdx | 41 ++++++--- .../rbs-services/output-management.mdx | 38 ++++++-- .../features/rbs-services/print-service.mdx | 53 ++++------- sidebarsDocsPython.js | 1 - 17 files changed, 358 insertions(+), 409 deletions(-) delete mode 100644 docs-python/features/connectivity/multi-tenancy.mdx diff --git a/docs-python/features/agent-modules/agent-gateway.mdx b/docs-python/features/agent-modules/agent-gateway.mdx index defd8f096b1..05ce64c1e94 100644 --- a/docs-python/features/agent-modules/agent-gateway.mdx +++ b/docs-python/features/agent-modules/agent-gateway.mdx @@ -18,45 +18,30 @@ keywords: The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents. It discovers MCP tools exposed by connected SAP LoB systems — such as SAP S/4HANA and SAP SuccessFactors — and wraps them as LangChain-compatible tools ready for use in an agent loop. -### Discovering Tools +### LangChain Integration + +Convert MCP tools to LangChain ```StructuredTool``` objects for use with LangChain agents: ```python from sap_cloud_sdk.agentgateway import create_client from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain -agw_client = create_client(tenant_subdomain=get_tenant_subdomain) -mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) -tools = [ - mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) - for t in mcp_tools -] -``` - -:::note -`get_tenant_subdomain` and `get_user_token` must be **callables** (for example, functions reading from contextvars), not captured strings. -This ensures that credentials are resolved per request and never become stale. -::: - -### Calling a Tool Directly +agw_client = create_client(tenant_subdomain="my-tenant") +tools = await agw_client.list_mcp_tools(user_token="user-jwt") -You can also call an MCP tool directly without converting to LangChain format: +langchain_tools = [ + mcp_tool_to_langchain( + t, + agw_client.call_mcp_tool, + get_user_token=lambda: request.headers["Authorization"], + ) + for t in tools +] -```python -result = await agw_client.call_mcp_tool( - tool=mcp_tools[0], - user_token=get_user_token, - order_id="4500012345" -) +# Use with LangChain agent +llm_with_tools = llm.bind_tools(langchain_tools) ``` -### Filtering Tools by ORD ID - -When multiple MCP servers expose tools with overlapping names, use `MCPToolFilter` to scope discovery to a specific system: - -```python -from sap_cloud_sdk.agentgateway import AgentCardFilter +--- -tools = await agw_client.list_mcp_tools( - filter=MCPToolFilter(ord_ids=["sap.s4:purchaseOrder:v1"]) -) -``` +For the complete API reference and more examples, see the [Agent Gateway user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/agentgateway/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/agent-modules/agent-memory.mdx b/docs-python/features/agent-modules/agent-memory.mdx index 356263e1364..0d19ab17e87 100644 --- a/docs-python/features/agent-modules/agent-memory.mdx +++ b/docs-python/features/agent-modules/agent-memory.mdx @@ -4,7 +4,7 @@ title: Agent Memory Service hide_title: false hide_table_of_contents: false sidebar_label: Agent Memory Service -description: Persist and retrieve conversation history and long-term semantic memories with the Agent Memory Service +description: Persist and retrieve conversation history and long-term semantic memories keywords: - sap - cloud @@ -13,76 +13,25 @@ keywords: - agent memory - hana cloud - conversation history - - semantic search --- The Agent Memory Service provides a persistent, tenant-isolated store backed by SAP HANA Cloud. -It exposes two APIs: +It exposes two APIs: the **Messages API** for short-term conversation history per session, and the **Memories API** for long-term semantic storage with similarity search across sessions. -- **Messages API** — short-term conversation history, scoped to an agent, user, and session -- **Memories API** — long-term semantic storage with similarity search across sessions +### Basic Setup -### Configuration - -The service is configured via a Kubernetes-mounted binding at `/etc/secrets/appfnd/hana-agent-memory/default`. -For local development, set the following environment variables: - -```bash -export HC_API_URL=https://.hanacloud.ondemand.com -export HC_CLIENT_ID= -export HC_CLIENT_SECRET= -export HC_AUTH_URL=https:///oauth/token -``` - -### Messages API - -Use the Messages API to store and replay conversation turns within a session: +Use ```create_client()``` to get a client with automatic credential detection: ```python -from sap_cloud_sdk.agent_memory import create_client, MessageRole +from sap_cloud_sdk.agent_memory import create_client -client = create_client(tenant=tenant_subdomain) +client = create_client() -# Store a conversation turn -client.add_message( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, role=MessageRole.USER, content=query -) -client.add_message( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, role=MessageRole.ASSISTANT, content=response -) - -# Replay history for a returning session -messages = client.list_messages( - agent_id="my-agent", invoker_id=user_id, - message_group=session_id, limit=50 +memories = client.list_memories(agent_id="my-agent", invoker_id="user-123") +print(f"Found {len(memories)} memories") ) ``` -:::note -Since v0.36.0, the `tenant` argument is required when calling `create_client()`. Omitting it raises `AgentMemoryValidationError`. -::: - -### Memories API - -Use the Memories API to persist facts across sessions and retrieve the most relevant ones using semantic similarity search: - -```python -# Store a long-term fact about the user -client.add_memory( - agent_id="my-agent", invoker_id=user_id, - content="User prefers responses in English." -) - -# Retrieve relevant memories before generating a response -results = client.search_memories( - agent_id="my-agent", invoker_id=user_id, - query="preferred language", threshold=0.6, limit=5 -) -for r in results: - print(f"[{r.similarity:.2f}] {r.content}") -``` +--- -The `threshold` parameter (0.0–1.0) controls the minimum cosine similarity score for a memory to be returned. -A value of `0.6` is a reasonable starting point for most use cases. +For the complete API reference and more examples, see the [Agent Memory user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/agent_memory/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/agent-modules/ai-core.mdx b/docs-python/features/agent-modules/ai-core.mdx index d51f76eb35f..9c96df60be9 100644 --- a/docs-python/features/agent-modules/ai-core.mdx +++ b/docs-python/features/agent-modules/ai-core.mdx @@ -1,9 +1,9 @@ --- id: ai-core -title: AI Core +title: SAP AI Core hide_title: false hide_table_of_contents: false -sidebar_label: AI Core +sidebar_label: SAP AI Core description: Manage AI scenarios, deployments, and executions with the SAP AI Core Python client keywords: - sap @@ -15,25 +15,26 @@ keywords: - executions --- -The AI Core module provides a Python client for [AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from your application. +The AI Core module provides a Python client for [SAP AI Core](https://help.sap.com/docs/sap-ai-core), enabling you to manage AI scenarios, deployments, and executions from your application. The SDK handles credential resolution and authentication automatically via the service binding. -```python -from sap_cloud_sdk.ai_core import AICoreClient +### Basic Setup +Use ```set_aicore_config()``` to automatically load and configure AI Core credentials: -client = AICoreClient() -deployments = client.list_deployments(resource_group="default") +```python +from sap_cloud_sdk.aicore import set_aicore_config -for d in deployments: - print(d.id, d.status, d.model_name) -``` +# Load credentials and configure environment for AI Core +set_aicore_config() -### Starting an Execution +# Now use LiteLLM with AI Core +from litellm import completion -```python -execution = client.create_execution( - resource_group="default", - configuration_id="my-config-id" +response = completion( + model="sap/gpt-4", messages=[{"role": "user", "content": "Hello!"}] ) -print(execution.id, execution.status) ``` + +--- + +For the complete API reference and more examples, see the [AI Core user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/aicore/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/agent-modules/tool-decorators.mdx b/docs-python/features/agent-modules/tool-decorators.mdx index 8cef3466b41..ccb8f6966e3 100644 --- a/docs-python/features/agent-modules/tool-decorators.mdx +++ b/docs-python/features/agent-modules/tool-decorators.mdx @@ -1,34 +1,65 @@ --- id: tool-decorators -title: Tool Decorators +title: Agent Decorators hide_title: false hide_table_of_contents: false -sidebar_label: Tool Decorators -description: Register Python functions as callable agent tools using the @tool decorator +sidebar_label: Agent Decorators +description: Expose agent configuration fields to a low-code UI using Python decorators keywords: - sap - cloud - sdk - python - agent - - tool decorator + - decorator + - configuration --- -Annotate any Python function with `@tool` to register it as a callable tool. -The decorator uses the function's type annotations to generate the tool's input schema and forwards the `description` to the LLM. +The Agent Decorators module provides a configuration-as-code system for SAP AI agents. +Annotate Python functions with decorators to expose configuration fields — prompts, model selections, and settings — to a low-code UI. + +### Quick Start ```python -from sap_cloud_sdk.agent import tool +from sap_cloud_sdk.agent_decorators import prompt_section, agent_model + -@tool(description="Fetch the current status for a given order ID.") -def get_order_status(order_id: str) -> str: - # your business logic here - return f"Order {order_id} is currently: In Transit" +# Define a prompt with a coded default +@prompt_section( + key="prompts.system", + label="System Prompt", + description="Main system prompt for the agent", +) +def system_prompt() -> str: + return "You are a helpful assistant." -@tool(description="List all open purchase orders for a given supplier.") -def list_open_orders(supplier_id: str, max_results: int = 10) -> list[dict]: - # call your backend system here - return [] + +# Define the model selection +@agent_model(key="config.model", label="LLM Model") +def model_name() -> str: + return "gpt-4" ``` -Decorated functions can be passed directly to a LangChain agent or any framework that accepts a list of tools. +### Decorators + +#### @prompt_section + +Expose a prompt section for editing. + +```python +from sap_cloud_sdk.agent_decorators import prompt_section + + +@prompt_section( + key="prompts.identity", + label="Agent Identity", + description="Core identity and role definition", + validation={"format": "text", "max_length": 500}, +) +def identity_prompt() -> str: + return "You are an expert assistant specializing in SAP systems." +``` + +--- + +For the complete API reference and more examples, see the [Agent Decorators user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/agent_decorators/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/connectivity/destination-service.mdx b/docs-python/features/connectivity/destination-service.mdx index c082f62a277..e58d42e28e6 100644 --- a/docs-python/features/connectivity/destination-service.mdx +++ b/docs-python/features/connectivity/destination-service.mdx @@ -13,12 +13,13 @@ keywords: - destination - connectivity - oauth - - authentication --- The Destination Service module provides an abstraction for connecting to remote systems defined in the SAP BTP Cockpit. It resolves credentials, handles OAuth flows, and supports both cloud and on-premise systems via the SAP Connectivity Service. +### Fetching a Destination + ```python from sap_cloud_sdk.destination import DestinationService @@ -26,21 +27,8 @@ service = DestinationService() destination = service.get_destination("my-destination") ``` -The SDK supports all standard destination authentication types, including Basic Authentication, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Principal Propagation. - -### Using a Destination with an HTTP Client - -Once you have a destination, you can pass it directly to the destination-aware HTTP client: - -```python -from sap_cloud_sdk.destination import DestinationService -from sap_cloud_sdk.http_client import DestinationHttpClient - -service = DestinationService() -destination = service.get_destination("my-s4-system") +The SDK supports all standard destination authentication types: Basic, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Principal Propagation. -client = DestinationHttpClient(destination) -response = client.get("/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner") -``` +--- -The client automatically applies the destination's credentials, headers, and proxy configuration to every request. +For the complete API reference and more examples, see the [Destination Service user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/destination/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/connectivity/identity-ias.mdx b/docs-python/features/connectivity/identity-ias.mdx index b67ac520882..cf3e1141f0e 100644 --- a/docs-python/features/connectivity/identity-ias.mdx +++ b/docs-python/features/connectivity/identity-ias.mdx @@ -4,7 +4,7 @@ title: Identity and Access Service (IAS) hide_title: false hide_table_of_contents: false sidebar_label: Identity (IAS) -description: Verify JWTs and handle service-to-service authentication with SAP Cloud Identity Services +description: Parse and inspect IAS JWTs from SAP Cloud Identity Services keywords: - sap - cloud @@ -16,29 +16,42 @@ keywords: - authentication --- -The IAS module handles authentication and token management for applications secured with [SAP Cloud Identity Services](https://help.sap.com/docs/identity-authentication). -IAS is the primary identity provider for new Python SDK applications — XSUAA is out of scope. +The IAS module provides utilities for working with SAP Identity Authentication Service (IAS) tokens. -### Token Verification +### Parsing a Token -Verify incoming JWTs from SAP Cloud Identity Services: +Use `parse_token` to decode an IAS JWT into a typed `IASClaims` dataclass. +It accepts either a raw token string or an `Authorization: Bearer ` header value. ```python -from sap_cloud_sdk.ias import IASTokenVerifier +from sap_cloud_sdk.ias import parse_token -verifier = IASTokenVerifier() -token_claims = verifier.verify(request_token) -user_id = token_claims.subject -tenant = token_claims.zone_uuid +claims = parse_token( + request.headers["Authorization"] +) # accepts "Bearer " or raw token + +print(claims.app_tid) # tenant ID (multitenant scenarios) +print(claims.scim_id) # SCIM-based user ID in SAP Cloud Identity Services +print(claims.sub) # OIDC subject identifier +print(claims.email) # user email (when email scope was requested) ``` -### Service-to-Service Authentication +:::note +`parse_token` does **not** verify the token signature. +Validate the token against the IAS JWKS endpoint in your framework or middleware before using the extracted claims for authorization decisions. +::: -For service-to-service calls, the SDK handles the client credentials flow automatically when the IAS binding is present: +### Combining with Telemetry ```python -from sap_cloud_sdk.ias import IASClient +from sap_cloud_sdk.ias import parse_token +from sap_cloud_sdk.core.telemetry import set_tenant_id, add_span_attribute -ias_client = IASClient() -token = ias_client.get_service_token(target_service="my-backend-service") +claims = parse_token(token) +set_tenant_id(claims.app_tid or "") +add_span_attribute("enduser.id", claims.scim_id or claims.sub or "") ``` + +--- + +For the complete claims reference and more examples, see the [IAS user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/ias/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/connectivity/multi-tenancy.mdx b/docs-python/features/connectivity/multi-tenancy.mdx deleted file mode 100644 index eb9bf93ec6d..00000000000 --- a/docs-python/features/connectivity/multi-tenancy.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: multi-tenancy -title: Multi-Tenancy -hide_title: false -hide_table_of_contents: false -sidebar_label: Multi-Tenancy -description: Build tenant-aware applications with automatic tenant isolation across SDK calls -keywords: - - sap - - cloud - - sdk - - python - - multi-tenancy - - tenant isolation ---- - -The SDK applies tenant isolation throughout by default. -The current tenant is resolved from the incoming request token and propagated automatically to destination lookups, memory operations, and other SDK calls. - -You can also provide the tenant subdomain explicitly when needed: - -```python -from sap_cloud_sdk.destination import DestinationService - -service = DestinationService() -destination = service.get_destination("my-destination", tenant_subdomain="acme-corp") -``` diff --git a/docs-python/features/connectivity/secret-management.mdx b/docs-python/features/connectivity/secret-management.mdx index 3b6105103f1..84c8cf58a29 100644 --- a/docs-python/features/connectivity/secret-management.mdx +++ b/docs-python/features/connectivity/secret-management.mdx @@ -1,42 +1,58 @@ --- id: secret-management -title: Secret Management +title: Secret Resolver hide_title: false hide_table_of_contents: false -sidebar_label: Secret Management -description: Read credentials and configuration from Kubernetes-mounted secrets or environment variables +sidebar_label: Secret Resolver +description: Read service credentials and secrets from SAP BTP service bindings or environment variables keywords: - sap - cloud - sdk - python - - secret management - - kubernetes + - secrets + - credentials - service binding - - environment variables + - vcap --- -The Secret Management module provides a unified interface for reading credentials and configuration values. -The SDK resolves secrets from multiple sources in the following priority order: +This module provides secure credential management by loading secrets from mounted volumes (Kubernetes-style) with fallback to environment variables. It supports type-safe configuration using dataclasses and follows Cloud patterns for secret resolution. -1. Kubernetes-mounted secrets via `SERVICE_BINDING_ROOT` (following the [servicebinding.io](https://servicebinding.io/) specification) -2. Environment variables using the pattern `CLOUD_SDK_CFG___` +The Secret Resolver is designed to work seamlessly in both Kubernetes environments with mounted secrets and with environment variables. -This means the same application code runs locally (using env vars) and in Kubernetes (using mounted secrets) without any modification. +### Getting Started -### Example: Reading a Secret +The Secret Resolver loads configuration into dataclass objects using a hierarchical approach: + +- **First:** Try to read from mounted volume paths (Kubernetes secrets) +- **Fallback:** Use environment variables if mounted secrets are not available ```python -from sap_cloud_sdk.secret_management import SecretManager +from dataclasses import dataclass +from sap_cloud_sdk.secret_resolver import read_from_mount_and_fallback_to_env_var -manager = SecretManager() -api_key = manager.get_secret(module="my-service", instance="default", field="api-key") -``` -### Local Development with Environment Variables +@dataclass +class DatabaseConfig: + host: str = "" + port: str = "" + username: str = "" + password: str = "" + -Set the environment variable pattern to simulate a Kubernetes binding locally: +# Load configuration +config = DatabaseConfig() +read_from_mount_and_fallback_to_env_var( + base_volume_mount="/etc/secrets", # Base mount path + base_var_name="DB", # Environment variable prefix + module="database", # Module/service name + instance="primary", # Instance name + target=config, # Target dataclass instance +) -```bash -export CLOUD_SDK_CFG_MY_SERVICE_DEFAULT_API_KEY=my-local-api-key +print(f"Database: {config.username}@{config.host}:{config.port}") ``` + +--- + +For the complete API reference and more examples, see the [Secret Resolver user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/core/secret_resolver/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/core-modules/audit-logging.mdx b/docs-python/features/core-modules/audit-logging.mdx index 66dd24e0b88..fd601de7e8a 100644 --- a/docs-python/features/core-modules/audit-logging.mdx +++ b/docs-python/features/core-modules/audit-logging.mdx @@ -12,30 +12,44 @@ keywords: - python - audit log - compliance + - gdpr --- -The Audit Logging module provides a structured way to emit audit log events to the [SAP Audit Log Service](https://help.sap.com/docs/audit-log-service). -Both the standard and the next-generation (NG) audit log APIs are supported. +The Audit Logging module provides a unified API for logging audit events that comply with the SAP Audit Log Service OpenAPI specification. +It uses Python dataclasses for type-safe event construction and supports six event types: Security, Data Access, Data Modification, Data Deletion, Configuration Change, and Configuration Deletion. -### Data Access Events +### Basic Setup + +Use ```create_client()``` to get a client with automatic environment detection: ```python -from sap_cloud_sdk.audit_log import AuditLogger +from sap_cloud_sdk.core.auditlog import create_client, SecurityEvent + +client = create_client() -logger = AuditLogger() -logger.log_data_access( - object_type="BusinessPartner", - object_id="1000001", - attributes=["Name", "Address"] +# Create and log a security event +security_event = SecurityEvent( + data="User login attempt", success=True, user="john.doe", tenant=Tenant.PROVIDER ) + +client.log(security_event) ``` -### Data Modification Events +### Custom Configuration ```python -logger.log_data_modification( - object_type="SalesOrder", - object_id="SO-4500012345", - attributes=[{"name": "Status", "old_value": "Open", "new_value": "Closed"}] +from sap_cloud_sdk.core.auditlog import create_client, AuditLogConfig + +config = AuditLogConfig( + service_url="https://api.auditlog.cf.example.com/audit-log/oauth2/v2", + oauth_url="https://example.authentication.com/oauth/token", + client_id="your-client-id", + client_secret="your-client-secret", ) + +client = create_client(config=config) ``` + +--- + +For all event types, batch logging, and configuration details, see the [Audit Logging user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/core/auditlog/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/core-modules/object-storage.mdx b/docs-python/features/core-modules/object-storage.mdx index c694e482767..883185e6e97 100644 --- a/docs-python/features/core-modules/object-storage.mdx +++ b/docs-python/features/core-modules/object-storage.mdx @@ -15,20 +15,31 @@ keywords: - files --- -The Object Storage module provides a client for SAP BTP Object Store Service, allowing you to upload, download, list, and delete objects. +The Object Storage module provides a client for SAP BTP Object Store Service with a simple, unified API for uploading, downloading, listing, and deleting objects. + +### Getting Started + +Use ```create_client()``` to get a client with automatic configuration detection: ```python -from sap_cloud_sdk.object_storage import ObjectStorageClient +from sap_cloud_sdk.objectstore import create_client -client = ObjectStorageClient() +# Automatically detects local vs cloud mode +client = create_client("my-instance") +``` -# Upload a file -with open("report.pdf", "rb") as f: - client.upload(bucket="my-bucket", key="reports/2026/report.pdf", body=f) +You can also specify additional parameters if needed: -# Download a file -content = client.download(bucket="my-bucket", key="reports/2026/report.pdf") +```python +from sap_cloud_sdk.objectstore import create_client -# List objects -objects = client.list(bucket="my-bucket", prefix="reports/") +# Custom configuration with SSL disabled +client = create_client( + "my-instance", + disable_ssl=True, # Disable SSL (default is False) +) ``` + +--- + +For error handling, metadata inspection, and configuration details, see the [Object Storage user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/objectstore/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/core-modules/runtime-context.mdx b/docs-python/features/core-modules/runtime-context.mdx index 54c6894d89c..430b4c3934d 100644 --- a/docs-python/features/core-modules/runtime-context.mdx +++ b/docs-python/features/core-modules/runtime-context.mdx @@ -16,75 +16,52 @@ keywords: - context propagation --- -The Runtime Context module propagates caller-identity information — tenant, user, and trigger type — across any invocation source (HTTP, gRPC, message queue) without coupling to a specific framework. -It uses a `ContextVar` so context is scoped per async task or thread. +### How it works -### Setup +The runtime context lets SDK modules read caller-identity information (tenant, user, trigger type) for the current execution — without knowing where that information came from or what framework is running. + +- **bootstrap(app)** wires the SDK into your framework once at startup. +- **Providers** extract context from the current invocation (HTTP request, gRPC call, Kubernetes event, etc.). +- **get_context()** lets any module read that context via typed keys. -Call `bootstrap()` once at application startup to wire the built-in providers into your framework (Starlette / FastAPI are supported out of the box): -```python -from sap_cloud_sdk import bootstrap +```python bootstrap(app) + └─ registers middleware on your framework + └─ on each invocation: providers extract → RuntimeContext set in ContextVar + └─ anywhere: get_context().get(TENANT_ID) ``` -This automatically registers the `IASContextProvider` (tenant and user from the `Authorization` JWT), `SAPTriggerContextProvider` (trigger type from `x-sap-origin`), and `DWCContextProvider` (Deploy with Confidence headers). - -### Reading Context +### Bootstrap at app startup ```python -from sap_cloud_sdk.core.runtime_context import get_context, APP_TENANT_ID, USER_ID, TRIGGER_TYPE +from starlette.applications import Starlette +from sap_cloud_sdk import bootstrap -ctx = get_context() -tenant = ctx.get(APP_TENANT_ID) # -> "abc-123" or None -user = ctx.get(USER_ID) # -> "user-uuid" or None +app = Starlette(...) +bootstrap(app) ``` -### Custom Context Keys and Providers - -You can extend the context with your own keys and providers: +### Read context anywhere ```python from sap_cloud_sdk.core.runtime_context import ( - ContextKey, ContextProvider, RuntimeContext, RequestEnvelope, - IASContextProvider, SAPTriggerContextProvider, DWCContextProvider, + get_context, + TENANT_ID, + USER_ID, + TRIGGER_TYPE, ) -CORRELATION_ID = ContextKey[str]("correlation_id") - -class CorrelationIdProvider(ContextProvider): - def extract(self, envelope: RequestEnvelope) -> RuntimeContext: - value = envelope.headers.get("x-correlation-id") - return RuntimeContext({CORRELATION_ID: value} if value else {}) - -bootstrap(app, providers=[ - IASContextProvider(), - SAPTriggerContextProvider(), - DWCContextProvider(), - CorrelationIdProvider(), -]) +ctx = get_context() +ctx.get(TENANT_ID) # -> "abc-123" or None +ctx.get(USER_ID) # -> "user-uuid" or None +ctx.get(TRIGGER_TYPE) # -> "ui5" or None ``` -### Manual Context Management - -For non-HTTP use cases such as background workers or tests, set and read context directly: - -```python -from sap_cloud_sdk.core.runtime_context import sdk_context, RuntimeContext, APP_TENANT_ID - -ctx = RuntimeContext({APP_TENANT_ID: "acme-corp"}) +Pass an explicit `tenant_id` parameter on any client that exposes one to override the context-resolved value for administrative or background processing scenarios. -with sdk_context(ctx): - # ctx is active for the duration of this block - process_job() -``` - -Use `async_sdk_context` for async code: -```python -from sap_cloud_sdk.core.runtime_context import async_sdk_context +--- -async with async_sdk_context(ctx): - await process_async_job() -``` +For framework adapters, provider merging semantics, and more, see the [Runtime Context user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/core/runtime_context/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/core-modules/telemetry.mdx b/docs-python/features/core-modules/telemetry.mdx index ebae9e5b041..d802f2540ee 100644 --- a/docs-python/features/core-modules/telemetry.mdx +++ b/docs-python/features/core-modules/telemetry.mdx @@ -16,30 +16,26 @@ keywords: - observability --- -The Telemetry module provides observability utilities built on top of [OpenTelemetry](https://opentelemetry.io/). -It auto-instruments SDK HTTP clients and common Python frameworks, exporting traces and metrics to any OpenTelemetry-compatible backend such as SAP Cloud Logging. +The Telemetry module provides observability utilities built on [OpenTelemetry](https://opentelemetry.io/). +It auto-instruments SDK HTTP clients and common Python frameworks (httpx, requests, starlette, fastapi, django, flask, sqlalchemy, grpcio), exporting traces, metrics, and logs to any OTLP-compatible backend such as SAP Cloud Logging. -### Setup +### Auto-Instrumentation and Agent Spans -Call `auto_instrument()` once at application startup: +Call `auto_instrument()` once **before** importing AI libraries, then wrap LLM calls with a parent span that carries your business context: ```python -from sap_cloud_sdk.telemetry import auto_instrument +from sap_cloud_sdk.core.telemetry import auto_instrument, invoke_agent_span auto_instrument() -``` - -This sets up trace propagation and metric collection for all SDK operations and outbound HTTP requests without any further configuration. -### Custom Spans +from litellm import completion # imported after — now automatically traced -You can also create custom spans to trace your own business logic: - -```python -from opentelemetry import trace +with invoke_agent_span( + provider="openai", agent_name="SupportBot", conversation_id="conv-123" +): + response = completion(model="gpt-4o", messages=[...]) +``` -tracer = trace.get_tracer("my-agent") +--- -with tracer.start_as_current_span("process-order"): - result = process_order(order_id) -``` +For span functions, extension context propagation, middleware, and configuration details, see the [Telemetry user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/core/telemetry/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/rbs-services/adms.mdx b/docs-python/features/rbs-services/adms.mdx index 5b60d4e3b58..f16e648559e 100644 --- a/docs-python/features/rbs-services/adms.mdx +++ b/docs-python/features/rbs-services/adms.mdx @@ -15,77 +15,45 @@ keywords: - odata --- -The Advanced Document Management Service (ADMS) module provides a typed Python client for the [SAP Advanced Document Management Service](https://help.sap.com/docs/advanced-document-management) OData V4 API. +The ADMS module provides a typed Python client for the [SAP Advanced Document Management Service](https://help.sap.com/docs/advanced-document-management) OData V4 API. Credentials are read from the service binding at `/etc/secrets/appfnd/adms/default/` or the `CLOUD_SDK_CFG_ADMS_DEFAULT_*` environment variables. -### Creating a Client +### Quick Start ```python -from sap_cloud_sdk.adms import create_client +from sap_cloud_sdk.adms import ( + create_client, + AdmsConfig, + BaseType, + CreateDocumentInput, + CreateDocumentRelationInput, + ScanStatus, +) +# Reads binding from /etc/secrets/appfnd/adms/default/ or env vars client = create_client() -``` - -For per-user policy enforcement, pass a user JWT: - -```python -client = create_client(user_jwt=request_token) -# or scope an existing client to a user: -user_client = client.with_user_jwt(request_token) -``` -### Managing Documents - -```python -# List all document relations -relations = client.relations.get_all() - -# Create a new document relation and generate upload URLs -relation = client.relations.create(input=CreateDocumentRelationInput(...)) -upload_urls = client.relations.generate_upload_urls( - document_relation_id=relation.id, - file_count=1, - file_size_in_bytes=len(pdf_bytes) +# Link a document to a business object (creates a draft relation + document) +relation = client.relations.create( + CreateDocumentRelationInput( + business_object_node_type_unique_id="PurchaseOrder", + host_business_object_node_id="PO-4500012345", + document=CreateDocumentInput( + document_name="Invoice.pdf", + document_base_type=BaseType.DOCUMENT, + document_type_id="INVOICE", + ), + is_active_entity=False, # start as draft + ) ) -# Retrieve a document -document = client.documents.get(document_relation_id=relation.id) -download_url = client.documents.get_download_url( - document_relation_id=relation.id, - doc_content_version_id=document.content_version_id -) -``` - -### Draft Workflow +# Upload bytes to the presigned URL (outside SDK) +import requests -```python -from sap_cloud_sdk.adms import DraftInput, DraftActivateInput - -# Create and activate a draft -draft_relations = client.relations.create_draft(draft_input=DraftInput(...)) -client.relations.validate_draft(draft_input=DraftInput(...)) -client.relations.activate_draft(input=DraftActivateInput(...)) - -# Or discard -client.relations.discard_draft(draft_input=DraftInput(...)) -``` - -### Background Jobs - -```python -from sap_cloud_sdk.adms import ZipDownloadJobParameters - -job = client.jobs.start_zip_download(params=ZipDownloadJobParameters( - document_relation_ids=["id-1", "id-2"] -)) -status = client.jobs.get_status(job_id=job.job_id) +upload_url = relation.document.document_content_upload_urls[0] +requests.put(upload_url, data=open("Invoice.pdf", "rb")) ``` -### Async Client - -```python -from sap_cloud_sdk.adms import create_async_client +--- -async with create_async_client() as client: - relations = await client.relations.get_all() -``` +For draft workflows, background jobs, the async client, and more, see the [ADMS user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/adms/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/rbs-services/dms.mdx b/docs-python/features/rbs-services/dms.mdx index b1f29c5dfd3..d03b5bbe91b 100644 --- a/docs-python/features/rbs-services/dms.mdx +++ b/docs-python/features/rbs-services/dms.mdx @@ -14,17 +14,38 @@ keywords: - document management --- -The Document Management module provides a client for [SAP Document Management Service](https://help.sap.com/docs/document-management-service), enabling you to manage documents and folders in a repository. +The DMS module provides a Python client for the [SAP Document Management Service](https://help.sap.com/docs/document-management-service), enabling you to manage repositories, documents, folders, versioning, and access control via the CMIS Browser Binding protocol. + +### Creating a Client + +Use ```create_client()``` to get a client with automatic configuration detection: + +```python +from sap_cloud_sdk.dms import create_client + +# Load credentials from mounted secrets or environment variables +client = create_client(instance="my-instance") +``` + +You can also provide credentials directly: ```python -from sap_cloud_sdk.document_management import DocumentManagementClient - -client = DocumentManagementClient() -folder = client.create_folder(repository_id="my-repo", path="/invoices/2026") -document = client.upload_document( - repository_id="my-repo", - folder_id=folder.id, - file_name="invoice-001.pdf", - content=pdf_bytes +from sap_cloud_sdk.dms import create_client +from sap_cloud_sdk.dms.model import DMSCredentials + +creds = DMSCredentials( + instance_name="my-instance", + uri="https://api-sdm-di.cfapps.eu10.hana.ondemand.com", + client_id="your-client-id", + client_secret="your-client-secret", + token_url="https://your-subdomain.authentication.eu10.hana.ondemand.com/oauth/token", + identityzone="your-subdomain", +) + +client = create_client(dms_cred=creds) ) ``` + +--- + +For repository management, versioning, access control, and more, see the [DMS user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/dms/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/rbs-services/output-management.mdx b/docs-python/features/rbs-services/output-management.mdx index d7f80f8a22f..f2ab14f9ad1 100644 --- a/docs-python/features/rbs-services/output-management.mdx +++ b/docs-python/features/rbs-services/output-management.mdx @@ -4,7 +4,7 @@ title: Output Management Service hide_title: false hide_table_of_contents: false sidebar_label: Output Management Service -description: Create and send output requests — emails and print documents — via the SAP Output Management Service +description: Create and send output requests via the SAP Output Management Service keywords: - sap - cloud @@ -17,15 +17,37 @@ keywords: The Output Management module provides a client for creating and sending output requests — including emails and print documents — via the [SAP Output Management Service](https://help.sap.com/docs/output-management). +### Quick Start + +Here's the simplest way to send an email: + ```python -from sap_cloud_sdk.outputmanagement import OutputManagementClient +from sap_cloud_sdk.outputmanagement import create_client -client = OutputManagementClient() +# Create client using the factory function +client = create_client(destination_name="ARIBA_OUTPUT_SERVICE") + +# Send email directly +response = client.send_email( + notification_template_key="PO_APPROVAL_NOTIFICATION", + to=["finance@company.com"], + business_document={ + "PurchaseOrder": { + "orderId": "PO-12345", + "vendor": "ACME Corp", + "total": 1500.00, + } + }, +) -# Send an email -client.send_output_request( - template_id="invoice-email-template", - recipient="customer@example.com", - data={"invoice_number": "INV-001", "amount": "1,500.00 EUR"} +# Check the result +if response.error: + print(f"Failed to send email: {response.error.message}") +else: + print(f"Email sent successfully! Request ID: {response.outputRequestId}") ) ``` + +--- + +For the complete API reference and more examples, see the [Output Management user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/outputmanagement/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/rbs-services/print-service.mdx b/docs-python/features/rbs-services/print-service.mdx index 1383ffdeb33..c4442c2ada3 100644 --- a/docs-python/features/rbs-services/print-service.mdx +++ b/docs-python/features/rbs-services/print-service.mdx @@ -14,50 +14,35 @@ keywords: - print queue --- -The Print Service module provides a client for [SAP Print Service](https://help.sap.com/docs/print-service), enabling you to manage print queues, upload documents, and submit print tasks. -Credentials are read from the service binding at `$SERVICE_BINDING_ROOT/print/default/` or the `CLOUD_SDK_CFG_PRINT_DEFAULT_*` environment variables. +The Print Service module provides a client for the [SAP Print Service](https://help.sap.com/docs/print-service), enabling you to manage print queues, upload documents, and submit print tasks. + +### Getting Started +Use ```create_client()``` to get a client with automatic configuration detection: -### Creating a Client ```python from sap_cloud_sdk.print import create_client -client = create_client() +# Load credentials from mounted secrets or environment variables +client = create_client(instance="my-instance") ``` -### Uploading and Printing a Document +You can also provide credentials directly: ```python -from sap_cloud_sdk.print import PrintTask, PrintContent - -# Upload the document to cloud storage -with open("invoice.pdf", "rb") as f: - doc_id = client.upload_document(f, filename="invoice.pdf") - -# Submit a print task -client.create_print_task(PrintTask( - item_id=doc_id, - qname="my-print-queue", - print_contents=[PrintContent(object_key=doc_id, document_name="invoice.pdf")], - number_of_copies=1, -)) -``` - -### Managing Print Queues +from sap_cloud_sdk.print import create_client +from sap_cloud_sdk.print.config import PrintConfig -```python -from sap_cloud_sdk.print import PrintQueue +config = PrintConfig( + url="https://api.eu10.print.services.sap", + client_id="your-client-id", + client_secret="your-client-secret", + token_url="https://your-subdomain.authentication.eu10.hana.ondemand.com/oauth/token", +) -# List available queues -queues = client.list_queues() +client = create_client(config=config) +``` -# Create a new queue -client.create_queue(PrintQueue( - qname="INVOICES", - qdescription="Invoice printing queue", - cleanup_prd=3, -)) +--- -# Get print profiles for a queue -profiles = client.get_print_profiles(qname="INVOICES") -``` +For print profiles and more examples, see the [Print Service user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/print/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/sidebarsDocsPython.js b/sidebarsDocsPython.js index 478c0ee4d9f..7f6833e5495 100644 --- a/sidebarsDocsPython.js +++ b/sidebarsDocsPython.js @@ -25,7 +25,6 @@ module.exports = { items: [ 'features/connectivity/destination-service', 'features/connectivity/identity-ias', - 'features/connectivity/multi-tenancy', 'features/connectivity/secret-management', ] }, From 0a252a6318cd42a676babb9aacf3fde56d48e6d1 Mon Sep 17 00:00:00 2001 From: I769216 Date: Wed, 26 Aug 2026 14:22:35 -0300 Subject: [PATCH 16/20] refactor overview and content --- docs-python/overview.mdx | 88 +++++++------------------ docs-python/support.mdx | 4 -- static/img/python-sdk-overview.svg | 100 ++++++++++++++--------------- 3 files changed, 72 insertions(+), 120 deletions(-) diff --git a/docs-python/overview.mdx b/docs-python/overview.mdx index 32bfb9302ad..fca7e2db79e 100644 --- a/docs-python/overview.mdx +++ b/docs-python/overview.mdx @@ -4,7 +4,7 @@ title: Overview hide_title: false hide_table_of_contents: false sidebar_label: Overview -description: The SAP Cloud SDK for Python significantly simplifies extending and developing applications with the SAP Business Technology Platform +description: The SAP Cloud SDK for Python provides building blocks for cloud-native AI agents and BTP integrations on SAP BTP keywords: - sap - cloud @@ -20,27 +20,12 @@ import ThemedImage from '@theme/ThemedImage'; ## Quick Start -For a quick start check out the [Getting Started](./getting-started.mdx) page. +For a quick start check out the ["Getting Started"](./getting-started.mdx) page. -## What is the SAP Cloud SDK for Python? +## What is the SAP Cloud SDK for JavaScript? -The SAP Cloud SDK for Python makes it easy to build cloud-native AI agents and BTP integrations on the SAP Business Technology Platform (SAP BTP). -It provides consistent, type-safe interfaces for foundational BTP services — destinations, identity, audit logging, storage, telemetry, and more — so you can focus on business logic instead of boilerplate integration code. - -For example, with the SAP Cloud SDK for Python you can discover MCP tools from connected SAP LoB systems and use them directly in an agent loop: - -```python -from sap_cloud_sdk.agentgateway import create_client -from sap_cloud_sdk.agentgateway.converters import mcp_tool_to_langchain - -agw_client = create_client(tenant_subdomain=get_tenant_subdomain) -mcp_tools = await agw_client.list_mcp_tools(user_token=get_user_token) -tools = [mcp_tool_to_langchain(t, agw_client.call_mcp_tool, get_user_token) for t in mcp_tools] -``` - -This discovers MCP tools from connected SAP LoB systems (S/4HANA, SuccessFactors) and exposes them as LangChain-compatible tools ready to drop into any agent loop. - -## Main Features of the SAP Cloud SDK for Python +The SAP Cloud SDK for Python provides building blocks for cloud-native AI agents and BTP integrations — type-safe clients for destinations, identity, storage, telemetry, audit logging, and more. +Install with `pip install sap-cloud-sdk`. +## Modules + ### Agent Modules -The Agent Modules are the core differentiator of the Python SDK. -It provides building blocks for AI-powered agents running on SAP BTP: a `@tool` decorator to register Python functions as agent tools, the **Agent Gateway Service** for discovering MCP tools from connected LoB systems with tenant-aware principal propagation, the **Agent Memory Service** for storing and retrieving conversation history and long-term semantic memories backed by SAP HANA Cloud, and a client for **SAP AI Core** to manage deployments and executions. +Building blocks for AI-powered agents on SAP BTP: the **Agent Decorators** expose configuration fields (prompts, model, settings) to a low-code UI; the **Agent Gateway** discovers MCP tools from connected LoB systems with tenant-aware principal propagation; the **Agent Memory** service stores conversation history and long-term semantic memories backed by SAP HANA Cloud; and the **AI Core** client manages deployments and executions. -For details and code examples, see the [Agent Modules](features/agent-modules/tool-decorators) guide. +→ [Agent Modules](features/agent-modules/tool-decorators) -### Connectivity and Identity +### Connectivity & Identity -The SDK abstracts the details of connecting to remote systems defined in the SAP BTP Cockpit. -The Destination Service module resolves credentials, handles OAuth flows (including principal propagation and client credentials), and supports both cloud and on-premise systems. -The Identity and Access Service (IAS) module handles token verification and user context propagation for applications secured with SAP Cloud Identity Services. +The **Destination Service** resolves credentials and handles OAuth flows (client credentials, principal propagation) for cloud and on-premise systems. The **IAS** module parses SAP Identity Authentication Service tokens into typed claims. The **Secret Resolver** loads service credentials from mounted volumes (Kubernetes) or environment variables (Cloud Foundry / local). -For details and code examples, see the [Connectivity and Identity](features/connectivity/destination-service) guide. +→ [Connectivity & Identity](features/connectivity/destination-service) ### Core Modules -The SDK includes cross-cutting modules that apply to any application type: **Audit Logging** for emitting structured events to the SAP Audit Log Service, **Telemetry & Observability** for auto-instrumented OpenTelemetry traces and metrics exported to SAP Cloud Logging, **Object Storage** for managing files on SAP BTP Object Store Service, and **Runtime Context** for propagating tenant, user, and trigger-type information across async tasks without coupling to a specific framework. +Cross-cutting utilities for any application type: **Audit Logging** emits structured events to the SAP Audit Log Service; **Telemetry** auto-instruments traces and metrics for SAP Cloud Logging via OpenTelemetry; **Object Storage** manages files on SAP BTP Object Store Service; and the **Runtime Context** propagates tenant, user, and trigger-type across async tasks without framework coupling. -For details and code examples, see the [Core Modules](features/core-modules/audit-logging) guide. +→ [Core Modules](features/core-modules/audit-logging) ### RBS Services -The SDK provides clients for SAP RBS services: **DMS** for managing documents and folders in a repository, **ADMS** for the Advanced Document Management Service, **Output Management** for creating and sending output requests, and **Print Service** for managing print queues and submitting print tasks. - -For details and code examples, see the [RBS Services](features/rbs-services/dms) guide. - -## Further Information - -### Supported Python Versions - -The SAP Cloud SDK for Python requires **Python 3.11 or higher**. - -| Python Version | Supported | -| -------------- | --------- | -| 3.13 | ✅ | -| 3.12 | ✅ | -| 3.11 | ✅ | -| 3.10 | ❌ | - -### Supported Environments - -The SAP Cloud SDK for Python currently targets cloud-native deployments on SAP BTP: - -1. SAP BTP Cloud Foundry -2. Kubernetes / SAP Gardener -3. SAP BTP Kyma -4. Deploy with Confidence (DwC) — via `DWCContextProvider` in `sap_cloud_sdk.core.runtime_context` - -### Licensing - -The SAP Cloud SDK for Python is available on [PyPI](https://pypi.org/project/sap-cloud-sdk/) under the [Apache 2.0 license](https://github.com/SAP/cloud-sdk-python/blob/main/LICENSE). - -### Release Schedule +Clients for SAP RBS services: **DMS** for document and folder management (CMIS), **ADMS** for the Advanced Document Management OData V4 API, **Output Management** for sending output requests, and the **Print Service** for managing queues and submitting print tasks. -We release minor versions on a regular cadence. -For details, see the [release notes](./release-notes.mdx). +→ [RBS Services](features/rbs-services/dms) -### Contributing +## Requirements & Links -For details on contributing, check the [contribution guide](https://github.com/SAP/cloud-sdk/blob/main/CONTRIBUTING.md). +- **Python:** 3.11, 3.12, or 3.13 +- **Environments:** SAP BTP Cloud Foundry, Kubernetes / SAP Gardener, SAP BTP Kyma, Deploy with Confidence (DwC) +- **License:** [Apache 2.0](https://github.com/SAP/cloud-sdk-python/blob/main/LICENSE) +- **PyPI:** [sap-cloud-sdk](https://pypi.org/project/sap-cloud-sdk/) +- **Release notes:** [Changelog](./release-notes.mdx) +- **Contributing:** [Contribution guide](https://github.com/SAP/cloud-sdk/blob/main/CONTRIBUTING.md) diff --git a/docs-python/support.mdx b/docs-python/support.mdx index 71d0d59bb8f..a1a305755e5 100644 --- a/docs-python/support.mdx +++ b/docs-python/support.mdx @@ -25,7 +25,3 @@ Please, create an issue in one of the public repositories of the SAP Cloud SDK. - **Python open source Repository**: ask a question, give feedback or create an issue [here](https://github.com/SAP/cloud-sdk-python/issues/new/choose). - **Documentation**: request documentation or suggest fixes [here](https://github.com/SAP/cloud-sdk/issues/new/choose). - -### Stack Overflow - -Use the `sap-cloud-sdk` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sap-cloud-sdk) to search for solved issues or create yours. diff --git a/static/img/python-sdk-overview.svg b/static/img/python-sdk-overview.svg index a620e339654..158c8f5e6e5 100644 --- a/static/img/python-sdk-overview.svg +++ b/static/img/python-sdk-overview.svg @@ -1,7 +1,7 @@ + viewBox="0 0 760 300" + width="760" height="300"> - - - Agent Modules + + + Connectivity + & Identity - - Tool Decorators + + Destination Service - - Agent Gateway Service + + Identity (IAS) - - Agent Memory Service + + Secret Resolver - - SAP AI Core + + + Core Modules - - - Connectivity & Identity + + Audit Logging - - Destination Service + + Telemetry & Observability - - Identity (IAS) + + Object Storage - - Multi-tenancy + + Runtime Context - - Secret Management + + + Agent Modules - - - Core Modules + + Agent Decorators - - Audit Logging + + Agent Gateway - - Telemetry & Observability + + Agent Memory - - Object Storage + + SAP AI Core - - Runtime Context + + + RBS Services - - - RBS Services + + DMS - - DMS + + ADMS - - ADMS + + Output Management - - Output Management - - - Print Service + + Print Service From d38e83552592f3e0f4fe0b3c561a90b290b1d42d Mon Sep 17 00:00:00 2001 From: I769216 Date: Wed, 26 Aug 2026 14:25:38 -0300 Subject: [PATCH 17/20] adjustments to highlight future improvements to documentation --- docs-python/getting-started.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-python/getting-started.mdx b/docs-python/getting-started.mdx index f34fc0ba0df..8aba34388dd 100644 --- a/docs-python/getting-started.mdx +++ b/docs-python/getting-started.mdx @@ -29,10 +29,10 @@ pip install sap-cloud-sdk ## Sample Projects -- TODO: Sample projects +- In the future we aim to offer project samples to help customers using the Cloud SDK for Python. ## Tutorials Check out the tutorials to get started with the SAP Cloud SDK for Python. -- TODO: Tutorial Link \ No newline at end of file +- In the future we aim to offer tutorials to help customers understand how to use the Cloud SDK for Python. \ No newline at end of file From 917afc321df2a62c1a472093aab6fb0c9435da37 Mon Sep 17 00:00:00 2001 From: "sap-cloud-sdk-bot[bot]" <274190970+sap-cloud-sdk-bot[bot]@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:31:39 +0000 Subject: [PATCH 18/20] fix: Changes from lint --- docs-python/features/agent-modules/agent-gateway.mdx | 2 +- docs-python/features/agent-modules/agent-memory.mdx | 2 +- docs-python/features/agent-modules/ai-core.mdx | 3 ++- docs-python/features/core-modules/audit-logging.mdx | 2 +- docs-python/features/core-modules/object-storage.mdx | 2 +- docs-python/features/core-modules/runtime-context.mdx | 3 --- docs-python/features/rbs-services/dms.mdx | 2 +- docs-python/features/rbs-services/print-service.mdx | 2 +- docs-python/getting-started.mdx | 2 +- sidebarsDocsPython.js | 10 +++++----- src/pages/components/HomepageFeatures.js | 4 +--- 11 files changed, 15 insertions(+), 19 deletions(-) diff --git a/docs-python/features/agent-modules/agent-gateway.mdx b/docs-python/features/agent-modules/agent-gateway.mdx index 05ce64c1e94..8aed1730c01 100644 --- a/docs-python/features/agent-modules/agent-gateway.mdx +++ b/docs-python/features/agent-modules/agent-gateway.mdx @@ -20,7 +20,7 @@ It discovers MCP tools exposed by connected SAP LoB systems — such as SAP S/4H ### LangChain Integration -Convert MCP tools to LangChain ```StructuredTool``` objects for use with LangChain agents: +Convert MCP tools to LangChain `StructuredTool` objects for use with LangChain agents: ```python from sap_cloud_sdk.agentgateway import create_client diff --git a/docs-python/features/agent-modules/agent-memory.mdx b/docs-python/features/agent-modules/agent-memory.mdx index 0d19ab17e87..0d8031b1313 100644 --- a/docs-python/features/agent-modules/agent-memory.mdx +++ b/docs-python/features/agent-modules/agent-memory.mdx @@ -20,7 +20,7 @@ It exposes two APIs: the **Messages API** for short-term conversation history pe ### Basic Setup -Use ```create_client()``` to get a client with automatic credential detection: +Use `create_client()` to get a client with automatic credential detection: ```python from sap_cloud_sdk.agent_memory import create_client diff --git a/docs-python/features/agent-modules/ai-core.mdx b/docs-python/features/agent-modules/ai-core.mdx index 9c96df60be9..e5f0d33c0f5 100644 --- a/docs-python/features/agent-modules/ai-core.mdx +++ b/docs-python/features/agent-modules/ai-core.mdx @@ -19,7 +19,8 @@ The AI Core module provides a Python client for [SAP AI Core](https://help.sap.c The SDK handles credential resolution and authentication automatically via the service binding. ### Basic Setup -Use ```set_aicore_config()``` to automatically load and configure AI Core credentials: + +Use `set_aicore_config()` to automatically load and configure AI Core credentials: ```python from sap_cloud_sdk.aicore import set_aicore_config diff --git a/docs-python/features/core-modules/audit-logging.mdx b/docs-python/features/core-modules/audit-logging.mdx index fd601de7e8a..46cdd51ad6c 100644 --- a/docs-python/features/core-modules/audit-logging.mdx +++ b/docs-python/features/core-modules/audit-logging.mdx @@ -20,7 +20,7 @@ It uses Python dataclasses for type-safe event construction and supports six eve ### Basic Setup -Use ```create_client()``` to get a client with automatic environment detection: +Use `create_client()` to get a client with automatic environment detection: ```python from sap_cloud_sdk.core.auditlog import create_client, SecurityEvent diff --git a/docs-python/features/core-modules/object-storage.mdx b/docs-python/features/core-modules/object-storage.mdx index 883185e6e97..675d663757b 100644 --- a/docs-python/features/core-modules/object-storage.mdx +++ b/docs-python/features/core-modules/object-storage.mdx @@ -19,7 +19,7 @@ The Object Storage module provides a client for SAP BTP Object Store Service wit ### Getting Started -Use ```create_client()``` to get a client with automatic configuration detection: +Use `create_client()` to get a client with automatic configuration detection: ```python from sap_cloud_sdk.objectstore import create_client diff --git a/docs-python/features/core-modules/runtime-context.mdx b/docs-python/features/core-modules/runtime-context.mdx index 430b4c3934d..2372224421f 100644 --- a/docs-python/features/core-modules/runtime-context.mdx +++ b/docs-python/features/core-modules/runtime-context.mdx @@ -24,8 +24,6 @@ The runtime context lets SDK modules read caller-identity information (tenant, u - **Providers** extract context from the current invocation (HTTP request, gRPC call, Kubernetes event, etc.). - **get_context()** lets any module read that context via typed keys. - - ```python bootstrap(app) └─ registers middleware on your framework @@ -61,7 +59,6 @@ ctx.get(TRIGGER_TYPE) # -> "ui5" or None Pass an explicit `tenant_id` parameter on any client that exposes one to override the context-resolved value for administrative or background processing scenarios. - --- For framework adapters, provider merging semantics, and more, see the [Runtime Context user guide](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/core/runtime_context/user-guide.md) in the `cloud-sdk-python` repository. diff --git a/docs-python/features/rbs-services/dms.mdx b/docs-python/features/rbs-services/dms.mdx index d03b5bbe91b..23339a28923 100644 --- a/docs-python/features/rbs-services/dms.mdx +++ b/docs-python/features/rbs-services/dms.mdx @@ -18,7 +18,7 @@ The DMS module provides a Python client for the [SAP Document Management Service ### Creating a Client -Use ```create_client()``` to get a client with automatic configuration detection: +Use `create_client()` to get a client with automatic configuration detection: ```python from sap_cloud_sdk.dms import create_client diff --git a/docs-python/features/rbs-services/print-service.mdx b/docs-python/features/rbs-services/print-service.mdx index c4442c2ada3..65d365a2d58 100644 --- a/docs-python/features/rbs-services/print-service.mdx +++ b/docs-python/features/rbs-services/print-service.mdx @@ -17,8 +17,8 @@ keywords: The Print Service module provides a client for the [SAP Print Service](https://help.sap.com/docs/print-service), enabling you to manage print queues, upload documents, and submit print tasks. ### Getting Started -Use ```create_client()``` to get a client with automatic configuration detection: +Use `create_client()` to get a client with automatic configuration detection: ```python from sap_cloud_sdk.print import create_client diff --git a/docs-python/getting-started.mdx b/docs-python/getting-started.mdx index 8aba34388dd..d142b9644c3 100644 --- a/docs-python/getting-started.mdx +++ b/docs-python/getting-started.mdx @@ -35,4 +35,4 @@ pip install sap-cloud-sdk Check out the tutorials to get started with the SAP Cloud SDK for Python. -- In the future we aim to offer tutorials to help customers understand how to use the Cloud SDK for Python. \ No newline at end of file +- In the future we aim to offer tutorials to help customers understand how to use the Cloud SDK for Python. diff --git a/sidebarsDocsPython.js b/sidebarsDocsPython.js index 7f6833e5495..133c56fad9d 100644 --- a/sidebarsDocsPython.js +++ b/sidebarsDocsPython.js @@ -15,7 +15,7 @@ module.exports = { 'features/agent-modules/tool-decorators', 'features/agent-modules/agent-gateway', 'features/agent-modules/agent-memory', - 'features/agent-modules/ai-core', + 'features/agent-modules/ai-core' ] }, { @@ -25,7 +25,7 @@ module.exports = { items: [ 'features/connectivity/destination-service', 'features/connectivity/identity-ias', - 'features/connectivity/secret-management', + 'features/connectivity/secret-management' ] }, { @@ -36,7 +36,7 @@ module.exports = { 'features/core-modules/audit-logging', 'features/core-modules/telemetry', 'features/core-modules/object-storage', - 'features/core-modules/runtime-context', + 'features/core-modules/runtime-context' ] }, { @@ -47,9 +47,9 @@ module.exports = { 'features/rbs-services/dms', 'features/rbs-services/adms', 'features/rbs-services/output-management', - 'features/rbs-services/print-service', + 'features/rbs-services/print-service' ] - }, + } ] }, 'release-notes', diff --git a/src/pages/components/HomepageFeatures.js b/src/pages/components/HomepageFeatures.js index f54285c9bf6..d2ed1e19737 100644 --- a/src/pages/components/HomepageFeatures.js +++ b/src/pages/components/HomepageFeatures.js @@ -55,9 +55,7 @@ const FeatureList = [ BTP integrations using Python, with built-in support for the Agent Gateway, Agent Memory, and SAP BTP services.
- - Get started with the SDK for Python - + Get started with the SDK for Python ) } From 437ff130e08689ce4571a8931a5e90b3a06e6f98 Mon Sep 17 00:00:00 2001 From: I769216 Date: Tue, 1 Sep 2026 08:47:53 -0300 Subject: [PATCH 19/20] improvements from PR review --- docs-python/features/agent-modules/agent-gateway.mdx | 5 +++-- docs-python/features/agent-modules/agent-memory.mdx | 4 ++++ docs-python/features/core-modules/audit-logging.mdx | 2 +- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs-python/features/agent-modules/agent-gateway.mdx b/docs-python/features/agent-modules/agent-gateway.mdx index 8aed1730c01..d42cfe59ed9 100644 --- a/docs-python/features/agent-modules/agent-gateway.mdx +++ b/docs-python/features/agent-modules/agent-gateway.mdx @@ -4,7 +4,7 @@ title: Agent Gateway Service hide_title: false hide_table_of_contents: false sidebar_label: Agent Gateway Service -description: Discover MCP tools from connected SAP LoB systems and use them in an agent loop +description: Discover MCP tools and A2A agents from connected SAP LoB systems via the Agent Gateway Service keywords: - sap - cloud @@ -12,11 +12,12 @@ keywords: - python - agent gateway - mcp + - a2a - langchain --- The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents. -It discovers MCP tools exposed by connected SAP LoB systems — such as SAP S/4HANA and SAP SuccessFactors — and wraps them as LangChain-compatible tools ready for use in an agent loop. +It supports two integration protocols: **MCP** for discovering and calling tools exposed by connected SAP LoB systems such as SAP S/4HANA and SAP SuccessFactors, and **A2A** (Agent-to-Agent) for discovering remote agents and delegating tasks to them. ### LangChain Integration diff --git a/docs-python/features/agent-modules/agent-memory.mdx b/docs-python/features/agent-modules/agent-memory.mdx index 0d8031b1313..84623d5f9fd 100644 --- a/docs-python/features/agent-modules/agent-memory.mdx +++ b/docs-python/features/agent-modules/agent-memory.mdx @@ -18,6 +18,10 @@ keywords: The Agent Memory Service provides a persistent, tenant-isolated store backed by SAP HANA Cloud. It exposes two APIs: the **Messages API** for short-term conversation history per session, and the **Memories API** for long-term semantic storage with similarity search across sessions. +:::note Version requirement +Agent Memory Service requires **`sap-cloud-sdk >= 0.36.0`**. +::: + ### Basic Setup Use `create_client()` to get a client with automatic credential detection: diff --git a/docs-python/features/core-modules/audit-logging.mdx b/docs-python/features/core-modules/audit-logging.mdx index 46cdd51ad6c..1fb8f323605 100644 --- a/docs-python/features/core-modules/audit-logging.mdx +++ b/docs-python/features/core-modules/audit-logging.mdx @@ -25,7 +25,7 @@ Use `create_client()` to get a client with automatic environment detection: ```python from sap_cloud_sdk.core.auditlog import create_client, SecurityEvent -client = create_client() +client = create_client(tenant="my-tenant-subdomain") # Create and log a security event security_event = SecurityEvent( From c7d9ae3188bb59bd9cbd5518d869d61e6394edf5 Mon Sep 17 00:00:00 2001 From: I769216 Date: Tue, 1 Sep 2026 08:50:16 -0300 Subject: [PATCH 20/20] small adjustment --- docs-python/features/core-modules/audit-logging.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-python/features/core-modules/audit-logging.mdx b/docs-python/features/core-modules/audit-logging.mdx index 1fb8f323605..ecf1e7a0b65 100644 --- a/docs-python/features/core-modules/audit-logging.mdx +++ b/docs-python/features/core-modules/audit-logging.mdx @@ -20,7 +20,7 @@ It uses Python dataclasses for type-safe event construction and supports six eve ### Basic Setup -Use `create_client()` to get a client with automatic environment detection: +Use `create_client(tenant="my-tenant-subdomain")` to get a client with automatic environment detection: ```python from sap_cloud_sdk.core.auditlog import create_client, SecurityEvent