OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add secondsky/sap-skills --skill sap-cloud-sdk-ai
Integrates SAP Cloud SDK for AI into JavaScript/TypeScript and Java applications. Use when building applications with SAP AI Core, Generative AI Hub, or Orchestration Service. Covers chat completion, embedding, streaming, function calling, content filtering, data masking, document grounding, prompt registry, and LangChain/Spring AI integration. Supports OpenAI GPT-4o, Llama, Gemini, Amazon Nova, and other foundation models via SAP BTP.
npx skills add secondsky/sap-skills --skill sap-cloud-sdk-ai
The official SDK for SAP AI Core, SAP Generative AI Hub, and Orchestration Service. Package versions are verified against public registries; AI Core tenant execution and exact model availability still require target-tenant validation.
Use this skill when:
Note: This skill uses SAP Cloud SDK for AI JavaScript v2.11.0+ and Java v1.19.0+ based on public package registry evidence from 2026-06-15. If you're migrating from v1.x, see V1 to V2 Migration Guide for breaking changes.
Bind AI Core service instance to your application. SDK auto-detects via VCAP_SERVICES or mounted secrets.
Set environment variable:
Or use CAP hybrid mode:
For detailed connection options, see references/connecting-to-ai-core.md
| Package | Purpose |
|---|---|
@sap-ai-sdk/orchestration | Chat completion, filtering, grounding |
@sap-ai-sdk/foundation-models | Direct model access (OpenAI) |
@sap-ai-sdk/langchain | LangChain integration |
@sap-ai-sdk/ai-api | Deployments, artifacts, configurations |
@sap-ai-sdk/document-grounding | Pipeline, Vector, Retrieval APIs |
@sap-ai-sdk/prompt-registry | Prompt template management |
| Artifact | Purpose |
|---|---|
orchestration | Chat completion, filtering, grounding |
openai (foundationmodels) | Direct OpenAI model access |
core | Base connectivity |
document-grounding | Pipeline, Vector, Retrieval APIs |
prompt-registry | Prompt template management |
Model IDs and versions are tenant-specific. Before copying an example into application code, list the target catalog through SAP AI Launchpad Model Library or the AI Core model-list API.
| Deprecated | Use Instead |
|---|---|
| text-embedding-ada-002 | text-embedding-3-small/large |
| gpt-35-turbo (all variants) | gpt-4o-mini |
| gpt-4-32k | gpt-4o |
| gpt-4 (base) | gpt-4o or gpt-4.1 |
| gemini-1.0-pro | gemini-2.0-flash |
| gemini-1.5-pro/flash | gemini-2.5-flash |
| mistralai--mixtral-8x7b | mistralai--mistral-small-instruct |
The SDK integrates natively with CAP event handlers. Use OrchestrationClient inside CAP service classes to add AI capabilities to your CAP services.
Service binding in MTA:
CAP event handler with AI:
Critical: Use async processing for production LLM calls. LLM responses can take 30-60 seconds, exceeding BTP load balancer timeouts. Return 202 Accepted and process in the background:
For the complete CAP + AI integration guide including HANA Vector types for RAG and prompt externalization, see the sap-cap-capire skill.
JavaScript SDK provides helper methods:
Streaming response methods:
For detailed guidance:
references/orchestration-guide.mdreferences/foundation-models-guide.mdreferences/langchain-guide.mdreferences/spring-ai-guide.mdreferences/ai-core-api-guide.mdreferences/foundation-models-guide.md - Foundation models and pricingreferences/ai-core-api-guide.md - AI Core service API referencereferences/orchestration-guide.md - Orchestration service guidereferences/langchain-guide.md - LangChain.js integrationreferences/spring-ai-guide.md - Spring AI integrationreferences/agentic-workflows.md - Agentic workflow patternsreferences/connecting-to-ai-core.md - Connection setup guidereferences/error-handling.md - Error handling patternsreferences/v1-to-v2-migration.md - V1 to V2 migration guide| SDK | Current Version | Node/Java Requirement |
|---|---|---|
| JavaScript | 2.11.0+ | Node.js 20+ |
| Java | 1.19.0+ | Java 17+ (21 LTS recommended) |
Version evidence: docs/project/package-evidence/2026-06-15.json. This is package-registry evidence only, not live AI Core runtime evidence.
Note: Generated model classes (in ...model packages) may change in minor releases but are safe to use.
| Error | Cause | Solution |
|---|---|---|
| "Could not find service bindings for 'aicore'" | Missing AI Core binding | Bind AI Core service or set AICORE_SERVICE_KEY |
| "Orchestration deployment not found" | No deployment in resource group | Deploy orchestration in AI Core or use different resource group |
| Content filter violation | Input/output blocked | Adjust filter thresholds or modify content |
| Token limit exceeded | Response too long | Set max_tokens parameter |
Keep this skill updated using these sources:
<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());export AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}'# JavaScript
cds bind -2 <AICORE_INSTANCE> && cds-tsx watch --profile hybrid
# Java
cds bind --to aicore --exec mvn spring-boot:run// 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()));// 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();// 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' })
}
});// 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' }]
}]
}
});// 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' }]
}
});resources:
- name: my-ai-core
type: org.cloudfoundry.managed-service
parameters:
service: aicore
service-plan: extendedimport { OrchestrationClient } from '@sap-ai-sdk/orchestration';
import cds from '@sap/cds';
export default class AnalysisService extends cds.ApplicationService {
async init() {
const client = new OrchestrationClient({
promptTemplating: {
model: { name: 'gpt-4o' },
prompt: [
{ role: 'system', content: 'Analyze and categorize as JSON.' },
{ role: 'user', content: '{{?input}}' }
]
}
});
this.on('analyzeText', async (req) => {
const response = await client.chatCompletion({
placeholderValues: { input: req.data.text }
});
return response.getContent();
});
return super.init();
}
}this.on('analyzeText', async (req) => {
const entry = await INSERT.into('Results').entries({
text: req.data.text, status: 'processing'
});
cds.spawn(() => processLLM(entry.id, req.data.text, client));
return req.reply(202, { id: entry.id, status: 'processing' });
});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 blockedconst stream = client.stream({ placeholderValues });
for await (const chunk of stream.toContentStream()) {
process.stdout.write(chunk);
}
// After stream ends:
stream.getFinishReason();
stream.getTokenUsage();