SAP Cloud SDK for AI

The official SDK for SAP AI Core, SAP Generative AI Hub, and Orchestration Service.

When to Use This Skill

Use this skill when:

• Integrating AI/LLM capabilities into SAP BTP applications
• Building chat completion or embedding features
• Using GPT-4o, Claude, Gemini, or other models via SAP AI Core
• Implementing content filtering, data masking, or document grounding
• Creating agentic workflows with LangChain or Spring AI
• Managing prompts via Prompt Registry
• Deploying AI models on SAP AI Core

Table of Contents

• Quick Start
• Prerequisites
• Connection Setup
• Available Packages
• Supported Models
• Core Features
• Bundled Resources

Quick Start

Note: This skill uses SAP Cloud SDK for AI v2.2.0+. If you're migrating from v1.x, see V1 to V2 Migration Guide for breaking changes.

JavaScript/TypeScript

npm install @sap-ai-sdk/orchestration@^2

import { OrchestrationClient } from '@sap-ai-sdk/orchestration';

const client = new OrchestrationClient({
  promptTemplating: {
    model: { name: 'gpt-4o' },
    prompt: [{ role: 'user', content: '{{?question}}' }]
  }
});

const response = await client.chatCompletion({
  placeholderValues: { question: 'What is SAP?' }
});
console.log(response.getContent());

Java

<dependency>
  <groupId>com.sap.ai.sdk</groupId>
  <artifactId>orchestration</artifactId>
  <version>${ai-sdk.version}</version>
</dependency>

var client = new OrchestrationClient();
var config = new OrchestrationModuleConfig()
    .withLlmConfig(OrchestrationAiModel.GPT_4O);
var prompt = new OrchestrationPrompt("What is SAP?");
var result = client.chatCompletion(prompt, config);
System.out.println(result.getContent());

Prerequisites

• Node.js 20+ (JavaScript) or Java 17+ (Java)
• SAP AI Core service instance (extended or sap-internal plan)
• Orchestration deployment in AI Core (default resource group has this)

Connection Setup

BTP Runtime (Cloud Foundry/Kyma)

Bind AI Core service instance to your application. SDK auto-detects via VCAP_SERVICES or mounted secrets.

Local Development

Set environment variable:

export AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}'

Or use CAP hybrid mode:

# JavaScript
cds bind -2 <AICORE_INSTANCE> && cds-tsx watch --profile hybrid

# Java
cds bind --to aicore --exec mvn spring-boot:run

For detailed connection options, see references/connecting-to-ai-core.md

Available Packages

JavaScript/TypeScript

Java

Supported Models

Recommended

• OpenAI: gpt-4o, gpt-4o-mini, o1, o3-mini
• Anthropic (AWS): Claude 3.5 Sonnet, Claude 4
• Amazon: Nova Pro, Nova Lite, Nova Micro
• Google: Gemini 2.5 Flash, Gemini 2.0 Flash
• Mistral: Medium, Large

Deprecated Models (Use Replacements)

Core Features

Chat Completion with Streaming

// JavaScript
const stream = client.stream({
  placeholderValues: { question: 'Explain SAP CAP' }
});

for await (const chunk of stream.toContentStream()) {
  process.stdout.write(chunk);
}

// Java
client.streamChatCompletion(prompt, config)
    .forEach(chunk -> System.out.print(chunk.getDeltaContent()));

Function/Tool Calling

// JavaScript
const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    parameters: { type: 'object', properties: { city: { type: 'string' } } }
  }
}];

const response = await client.chatCompletion({
  placeholderValues: { question: 'Weather in Berlin?' }
}, { tools });

const toolCalls = response.getToolCalls();

Content Filtering

// JavaScript
import { buildAzureContentSafetyFilter } from '@sap-ai-sdk/orchestration';

const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  filtering: {
    input: buildAzureContentSafetyFilter({ Hate: 'ALLOW_SAFE' }),
    output: buildAzureContentSafetyFilter({ Violence: 'ALLOW_SAFE' })
  }
});

Data Masking

// JavaScript
const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  masking: {
    masking_providers: [{
      type: 'sap_data_privacy_integration',
      method: 'anonymization',
      entities: [{ type: 'profile-email' }, { type: 'profile-person' }]
    }]
  }
});

Document Grounding

// JavaScript
const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  grounding: {
    grounding_input: ['{{?question}}'],
    grounding_output: ['{{?context}}'],
    data_repositories: [{ type: 'vector', id: 'my-repo-id' }]
  }
});

Response Helpers

JavaScript SDK provides helper methods:

const response = await client.chatCompletion({ placeholderValues });

response.getContent();          // Model output string
response.getTokenUsage();       // { prompt_tokens, completion_tokens, total_tokens }
response.getFinishReason();     // 'stop', 'length', 'tool_calls', etc.
response.getToolCalls();        // Array of function calls
response.getDeltaToolCalls();   // Partial tool calls (streaming)
response.getAllMessages();      // Full message history
response.getAssistantMessage(); // Assistant response only
response.getRefusal();          // Refusal message if blocked

Streaming response methods:

const stream = client.stream({ placeholderValues });
for await (const chunk of stream.toContentStream()) {
  process.stdout.write(chunk);
}
// After stream ends:
stream.getFinishReason();
stream.getTokenUsage();

Advanced Topics

For detailed guidance:

• Orchestration features: references/orchestration-guide.md
• Foundation models (direct OpenAI): references/foundation-models-guide.md
• LangChain integration: references/langchain-guide.md
• Spring AI integration: references/spring-ai-guide.md
• AI Core management: references/ai-core-api-guide.md

Bundled Resources

Reference Documentation

• references/foundation-models-guide.md - Foundation models and pricing
• references/ai-core-api-guide.md - AI Core service API reference
• references/orchestration-guide.md - Orchestration service guide
• references/langchain-guide.md - LangChain.js integration
• references/spring-ai-guide.md - Spring AI integration
• references/agentic-workflows.md - Agentic workflow patterns
• references/connecting-to-ai-core.md - Connection setup guide
• references/error-handling.md - Error handling patterns
• references/v1-to-v2-migration.md - V1 to V2 migration guide

Version Information

Note: Generated model classes (in ...model packages) may change in minor releases but are safe to use.

Common Errors

Documentation Sources

Keep this skill updated using these sources:

• JS Docs: https://github.com/SAP/ai-sdk/tree/main/docs-js
• Java Docs: https://github.com/SAP/ai-sdk/tree/main/docs-java
• JS SDK: https://github.com/SAP/ai-sdk-js
• Java SDK: https://github.com/SAP/ai-sdk-java
• Release Notes: Check docs-js/release-notes.mdx and docs-java/release-notes.mdx