Docs(python): add Python SDK documentation section

docs-python/features/agent-modules/agent-gateway.mdx

@@ -0,0 +1,48 @@
+---
+id: agent-gateway
+title: Agent Gateway Service
+hide_title: false
+hide_table_of_contents: false
+sidebar_label: Agent Gateway Service
+description: Discover MCP tools and A2A agents from connected SAP LoB systems via the Agent Gateway Service
+keywords:
+  - sap
+  - cloud
+  - sdk
+  - python
+  - agent gateway
+  - mcp
+  - a2a
+  - langchain
+---
+
+The Agent Gateway Service (AGW) is the central communication hub for SAP BTP agents.
+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
+
+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="my-tenant")
+tools = await agw_client.list_mcp_tools(user_token="user-jwt")
+
+langchain_tools = [
+    mcp_tool_to_langchain(
+        t,
+        agw_client.call_mcp_tool,
+        get_user_token=lambda: request.headers["Authorization"],
+    )
+    for t in tools
+]
+
+# Use with LangChain agent
+llm_with_tools = llm.bind_tools(langchain_tools)
+```
+
+---
+
+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.

docs-python/features/agent-modules/agent-memory.mdx

@@ -0,0 +1,41 @@
+---
+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
+keywords:
+  - sap
+  - cloud
+  - sdk
+  - python
+  - agent memory
+  - hana cloud
+  - conversation history
+---
+
+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:
+
+```python
+from sap_cloud_sdk.agent_memory import create_client
+
+client = create_client()
+
+memories = client.list_memories(agent_id="my-agent", invoker_id="user-123")
+print(f"Found {len(memories)} memories")
+)
+```
+
+---
+
+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.

docs-python/features/agent-modules/ai-core.mdx

@@ -0,0 +1,41 @@
+---
+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.
+
+### Basic Setup
+
+Use `set_aicore_config()` to automatically load and configure AI Core credentials:
+
+```python
+from sap_cloud_sdk.aicore import set_aicore_config
+
+# Load credentials and configure environment for AI Core
+set_aicore_config()
+
+# Now use LiteLLM with AI Core
+from litellm import completion
+
+response = completion(
+    model="sap/gpt-4", messages=[{"role": "user", "content": "Hello!"}]
+)
+```
+
+---
+
+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.

docs-python/features/agent-modules/tool-decorators.mdx

@@ -0,0 +1,65 @@
+---
+id: tool-decorators
+title: Agent Decorators
+hide_title: false
+hide_table_of_contents: false
+sidebar_label: Agent Decorators
+description: Expose agent configuration fields to a low-code UI using Python decorators
+keywords:
+  - sap
+  - cloud
+  - sdk
+  - python
+  - agent
+  - decorator
+  - configuration
+---
+
+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_decorators import prompt_section, agent_model
+
+
+# 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."
+
+
+# Define the model selection
+@agent_model(key="config.model", label="LLM Model")
+def model_name() -> str:
+    return "gpt-4"
+```
+
+### 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.

docs-python/features/connectivity/destination-service.mdx

@@ -0,0 +1,34 @@
+---
+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
+---
+
+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
+
+service = DestinationService()
+destination = service.get_destination("my-destination")
+```
+
+The SDK supports all standard destination authentication types: Basic, OAuth 2.0 Client Credentials, OAuth 2.0 Authorization Code, and Principal Propagation.
+
+---
+
+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.

docs-python/features/connectivity/identity-ias.mdx

@@ -0,0 +1,57 @@
+---
+id: identity-ias
+title: Identity and Access Service (IAS)
+hide_title: false
+hide_table_of_contents: false
+sidebar_label: Identity (IAS)
+description: Parse and inspect IAS JWTs from SAP Cloud Identity Services
+keywords:
+  - sap
+  - cloud
+  - sdk
+  - python
+  - ias
+  - identity
+  - jwt
+  - authentication
+---
+
+The IAS module provides utilities for working with SAP Identity Authentication Service (IAS) tokens.
+
+### Parsing a Token
+
+Use `parse_token` to decode an IAS JWT into a typed `IASClaims` dataclass.
+It accepts either a raw token string or an `Authorization: Bearer <token>` header value.
+
+```python
+from sap_cloud_sdk.ias import parse_token
+
+claims = parse_token(
+    request.headers["Authorization"]
+)  # accepts "Bearer <token>" 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)
+```
+
+:::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.
+:::
+
+### Combining with Telemetry
+
+```python
+from sap_cloud_sdk.ias import parse_token
+from sap_cloud_sdk.core.telemetry import set_tenant_id, add_span_attribute
+
+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.

docs-python/features/connectivity/secret-management.mdx

@@ -0,0 +1,58 @@
+---
+id: secret-management
+title: Secret Resolver
+hide_title: false
+hide_table_of_contents: false
+sidebar_label: Secret Resolver
+description: Read service credentials and secrets from SAP BTP service bindings or environment variables
+keywords:
+  - sap
+  - cloud
+  - sdk
+  - python
+  - secrets
+  - credentials
+  - service binding
+  - vcap
+---
+
+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.
+
+The Secret Resolver is designed to work seamlessly in both Kubernetes environments with mounted secrets and with environment variables.
+
+### Getting Started
+
+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 dataclasses import dataclass
+from sap_cloud_sdk.secret_resolver import read_from_mount_and_fallback_to_env_var
+
+
+@dataclass
+class DatabaseConfig:
+    host: str = ""
+    port: str = ""
+    username: str = ""
+    password: str = ""
+
+
+# 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
+)
+
+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.