The SAP Cloud SDK for AI (Java) is the official Software Development Kit for integrating AI capabilities into Java applications via SAP AI Core, SAP Generative AI Hub, and the Orchestration Service. The SDK provides type-safe, fluent APIs for chat completion, embeddings, content filtering, data masking, prompt templating, and retrieval-augmented generation (RAG).
This page introduces the SDK's purpose, module structure, and core concepts. For installation and configuration instructions, see Getting Started. For detailed module documentation, see Core Module, Orchestration Service, Foundation Models - OpenAI, and Core Services.
The SDK simplifies integration with SAP AI Core by providing:
The SDK targets enterprise Java developers building applications on SAP Business Technology Platform (BTP) who need to integrate generative AI capabilities.
Sources: pom.xml1-10 README.md7-13
The SDK follows a multi-module Maven project structure with clearly separated concerns. Each module is published as an independent artifact to Maven Central.
Module Descriptions:
| Maven Artifact | Primary Classes | Purpose |
|---|---|---|
com.sap.ai.sdk:core | AiCoreService, DeploymentApi, DeploymentResolver | Foundation for AI Core connectivity, deployment management, and API client generation |
com.sap.ai.sdk:orchestration | OrchestrationClient, OrchestrationModuleConfig | Orchestration Service with templating, filtering, masking, grounding |
com.sap.ai.sdk.foundationmodels:openai | OpenAiClient, OpenAiChatCompletionRequest | Direct Azure OpenAI model access without orchestration |
com.sap.ai.sdk.foundationmodels:sap-rpt | RptClient | SAP RPT tabular prediction models |
com.sap.ai.sdk:document-grounding | GroundingClient | Direct document grounding API access |
com.sap.ai.sdk:prompt-registry | PromptRegistryClient | Prompt template lifecycle management |
Sources: pom.xml31-38 pom.xml229-263 orchestration/pom.xml9-11 core/pom.xml9-11 foundation-models/openai/pom.xml10-13
SAP AI Core is a cloud service that hosts AI model deployments. A deployment is a running instance of a model (e.g., gpt-4o, claude-3.5-sonnet) with a unique deployment ID. Deployments are organized into resource groups (default: "default").
The SDK's AiCoreService class manages connectivity to AI Core and resolves deployments:
Key Classes:
AiCoreService: Entry point for AI Core connectivity (core/pom.xml10-11)DeploymentApi: Generated OpenAPI client for deployment operationsDeploymentResolver: Resolves deployment IDs from model names or scenariosSources: README.md41-43 core/pom.xml9-11 docs/adrs/004-core-class-for-service-integration.md70-112
The SDK provides two primary patterns for model access:
Pattern 1: Orchestration Service - Use OrchestrationClient for enterprise AI features:
Pattern 2: Foundation Models - Use OpenAiClient for direct model access:
Decision Factors:
| Use Orchestration When... | Use Foundation Models When... |
|---|---|
| Content filtering required | Low latency is critical |
| DPI masking needed | Simple chat completion only |
| Prompt templating desired | Orchestration overhead not justified |
| Document grounding (RAG) needed | Direct model API compatibility required |
| Multi-language translation required | Tool calling is sufficient |
Sources: orchestration/pom.xml10-11 foundation-models/openai/pom.xml12-13 README.md64-109
Add the SDK BOM for version management:
Then add specific modules:
Sources: pom.xml51-60 pom.xml99-114 README.md34-39 README.md76-83
The SDK includes optional Spring AI adapters:
Spring AI dependencies are marked <optional>true</optional> and not required for core functionality (orchestration/pom.xml63-76).
Sources: pom.xml68 orchestration/pom.xml63-76 foundation-models/openai/pom.xml106-119
The SDK uses OpenAPI code generation to create type-safe client classes from API specifications. Generated code is located in *.model and *.client packages and marked @Beta.
| Module | OpenAPI Spec | Generated Package | API Package |
|---|---|---|---|
| Core | core/src/main/resources/spec/aicore.yaml | com.sap.ai.sdk.core.model | com.sap.ai.sdk.core.client |
| Orchestration | orchestration/src/main/resources/spec/orchestration.yaml | com.sap.ai.sdk.orchestration.model | (API not generated) |
| OpenAI | foundation-models/openai/src/main/resources/spec/openapi-2024-10-21.yaml | com.sap.ai.sdk.foundationmodels.openai.generated.model | (API not generated) |
| Document Grounding | core-services/document-grounding/src/main/resources/spec/grounding.yaml | com.sap.ai.sdk.grounding.model | com.sap.ai.sdk.grounding.client |
| Prompt Registry | core-services/prompt-registry/src/main/resources/spec/prompt-registry.yaml | com.sap.ai.sdk.prompt.registry.model | com.sap.ai.sdk.prompt.registry.client |
Code generation is triggered via the generate Maven profile:
Sources: core/pom.xml159-209 orchestration/pom.xml171-220 foundation-models/openai/pom.xml165-223 README.md56-58
All SDK clients follow a consistent initialization pattern with lazy destination resolution:
Client Classes:
| Client Class | Module | Initialization Method |
|---|---|---|
OrchestrationClient | orchestration | new OrchestrationClient() |
OpenAiClient | openai | OpenAiClient.forModel(OpenAiModel.GPT_4O) |
RptClient | sap-rpt | RptClient.forModel(RptModel.SAP_RPT) |
GroundingClient | document-grounding | new GroundingClient() |
Alternative initialization via AiCoreService:
Sources: README.md86-91 README.md94-106 docs/adrs/004-core-class-for-service-integration.md70-80
The SDK includes a reference Spring Boot application demonstrating all modules:
Location: sample-code/spring-app
Key Features:
Running the sample:
Access endpoints at http://localhost:8080
Sources: sample-code/spring-app/README.md1-52 sample-code/spring-app/pom.xml10-13 README.md199-202
The SDK enforces strict quality standards:
Coverage thresholds are defined per module (pom.xml90-96):
| Metric | Threshold |
|---|---|
| Line Coverage | 100% (configurable per module) |
| Branch Coverage | 100% (configurable per module) |
| Instruction Coverage | 100% (configurable per module) |
| Complexity Coverage | 100% (configurable per module) |
Example module-specific thresholds (orchestration/pom.xml39-44):
Sources: pom.xml90-96 pom.xml465-801 orchestration/pom.xml38-45
Sources: README.md15-31 README.md134-146
Refresh this wiki