SAP Cloud SDK for AI JavaScript

https://sap.github.io/ai-sdk/docs/js/
Admin
SAP Cloud SDK for AI enables developers to seamlessly integrate AI capabilities like chat completion...
Tokens:33,609
Snippets:430
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Foundation Models Package

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models

Install the package via npm.

```bash
npm install @sap-ai-sdk/foundation-models
```

--------------------------------

### Install Dependencies

Source: https://sap.github.io/ai-sdk/docs/js/tutorials/getting-started-agents

Install the required packages for the SAP AI SDK and LangChain integration.

```bash
npm install @sap-ai-sdk/langchain langchain @langchain/langgraph @langchain/core @langchain/mcp-adapters @modelcontextprotocol/sdk zod
```

--------------------------------

### Install the SAP RPT SDK

Source: https://sap.github.io/ai-sdk/docs/js/rpt

Command to add the experimental RPT package to your project.

```bash
npm install @sap-ai-sdk/rpt
```

--------------------------------

### Install LangChain and SAP AI SDK packages

Source: https://sap.github.io/ai-sdk/docs/js/langchain

Use these commands to install the necessary dependencies for using LangChain with the SAP AI SDK.

```bash
npm install @sap-ai-sdk/langchain

# Install langchain packages

npm install langchain @langchain/core



# Install SAP Cloud SDK for AI langchain package

npm install @sap-ai-sdk/langchain
```

--------------------------------

### Install SAP AI SDK OpenAI

Source: https://sap.github.io/ai-sdk/docs/js/openai

Install the required packages via npm.

```bash
npm install @sap-ai-sdk/openai openai
```

--------------------------------

### Install Orchestration Package

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Command to install the orchestration SDK dependency.

```bash
npm install @sap-ai-sdk/orchestration
```

--------------------------------

### Install Realtime API dependencies

Source: https://sap.github.io/ai-sdk/docs/js/openai/realtime

Install the required SAP AI SDK and peer dependencies.

```bash
npm install @sap-ai-sdk/openai openai ws
```

--------------------------------

### Install Prompt Registry package

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/prompt-registry

Use the tilde version range to manage updates and avoid breaking changes.

```bash
npm install @sap-ai-sdk/prompt-registry
```

--------------------------------

### Install document grounding package

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/document-grounding

Use npm to install the document grounding SDK package.

```bash
npm install @sap-ai-sdk/document-grounding
```

--------------------------------

### Install Batch API dependencies

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/batch

Install the required packages to use the Batch API functionality.

```bash
npm install @sap-ai-sdk/llm-batch @sap-ai-sdk/ai-api @sap-ai-sdk/foundation-models
```

--------------------------------

### Configuring custom deployment settings

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/embedding

Provides examples for specifying a custom resource group or a manual deployment ID when initializing the client.

```typescript
// Using a custom resource group

const embeddingClient = new OrchestrationEmbeddingClient(

  {

    embeddings: { model: { name: 'text-embedding-3-large' } }

  },

  { resourceGroup: 'YOUR_RESOURCE_GROUP' }

);
```

```typescript
const embeddingClient = new OrchestrationEmbeddingClient(orchestrationConfig, {

  deploymentId: 'YOUR_DEPLOYMENT_ID'

});
```

--------------------------------

### Configure AICORE_SERVICE_KEY Environment Variable

Source: https://sap.github.io/ai-sdk/docs/js/connecting-to-ai-core

Example format for defining the AI Core service key within a .env file.

```text
AICORE_SERVICE_KEY='{

    "clientid": "...",

    ...

}'
```

--------------------------------

### Install AI API package

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/ai-api

Use this command to add the AI API package to your project dependencies.

```bash
npm install @sap-ai-sdk/ai-api
```

--------------------------------

### Install Orchestration Dependency

Source: https://sap.github.io/ai-sdk/docs/js/getting-started

Add the required orchestration package to your project using npm.

```bash
npm install @sap-ai-sdk/orchestration
```

--------------------------------

### JSONL Input File Format

Source: https://sap.github.io/ai-sdk/docs/js/tutorials/llm-batch-api

Example of the required JSONL format where each line represents an individual chat completion request.

```json
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5", "messages": [{"role": "user", "content": "What is machine learning?"}], "max_tokens": 150}}

{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5", "messages": [{"role": "user", "content": "Explain neural networks in simple terms"}], "max_tokens": 150}}
```

--------------------------------

### Batch Job output format

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/batch

Example of the JSONL output format retrieved from the object store after job completion.

```json
{"custom_id": "request-1", "response": {"status_code": 200, "body": {"id": "chatcmpl-abc", "choices": [{"message": {"role": "assistant", "content": "Machine learning is a subset of AI..."}}], "usage": {"prompt_tokens": 12, "completion_tokens": 45, "total_tokens": 57}}}, "error": null}

{"custom_id": "request-2", "response": {"status_code": 200, "body": {"id": "chatcmpl-def", "choices": [{"message": {"role": "assistant", "content": "Neural networks are computing systems..."}}], "usage": {"prompt_tokens": 13, "completion_tokens": 42, "total_tokens": 55}}}, "error": null}
```

--------------------------------

### Consuming the SAP ABAP 1 Model

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Example of configuring the Orchestration client to use the sap-abap-1 model with placeholder values for code analysis.

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



const orchestrationClient = new OrchestrationClient({

  promptTemplating: {

    model: {

      name: 'sap-abap-1',

      version: 'latest' // optional

    }

  }

});



const response = await orchestrationClient.chatCompletion({

  messages: [

    {

      role: 'user',

      content:

        'Please explain the following ABAP class definition and its purpose: {{?abapCode}}'

    }

  ],

  placeholderValues: {

    abapCode: `CLASS zcl_customer_manager DEFINITION

  PUBLIC

  FINAL

  CREATE PUBLIC.



  PUBLIC SECTION.

    METHODS: get_customer_data

      IMPORTING iv_customer_id TYPE kunnr

      RETURNING VALUE(rs_customer) TYPE zst_customer_data

      RAISING zcx_customer_not_found.



  PRIVATE SECTION.

    DATA: lo_customer_db TYPE REF TO zcl_customer_database.

ENDCLASS.`

  }

});



console.log(response.getContent());

console.log(response.getFinishReason());

console.log(JSON.stringify(response.getTokenUsage()));
```

--------------------------------

### Batch Output JSONL Format

Source: https://sap.github.io/ai-sdk/docs/js/tutorials/llm-batch-api

Example of the JSONL structure returned in the output file, where each line contains a custom_id and the corresponding response or error.

```json
{"custom_id": "request-1", "response": {"status_code": 200, "body": {"id": "chatcmpl-abc", "object": "chat.completion", "model": "gpt-5-2025-04-14", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Machine learning is a subset of AI..."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 12, "completion_tokens": 45, "total_tokens": 57}}}, "error": null}

{"custom_id": "request-2", "response": {"status_code": 200, "body": {"id": "chatcmpl-def", "object": "chat.completion", "model": "gpt-5-2025-04-14", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Neural networks are computing systems..."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 13, "completion_tokens": 42, "total_tokens": 55}}}, "error": null}
```

--------------------------------

### Initialize Client and Send Request

Source: https://sap.github.io/ai-sdk/docs/js/openai

Create a client instance with a default deployment and execute a chat completion request.

```javascript
const client = await SapOpenAi.createClient({ deployment: 'gpt-5.4' });



const response = await client.chat.completions.create({

  messages: [{ role: 'user', content: 'What is the capital of France?' }]

});
```

--------------------------------

### Create a Configuration

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/ai-api

Shows how to define and create a configuration with parameter bindings and input artifact bindings.

```typescript
async function createConfiguration() {

  const requestBody: AiConfigurationBaseData = {

    name: 'gpt-5',

    executableId: 'azure-openai',

    scenarioId: 'foundation-models',

    parameterBindings: [

      {

        key: 'modelName',

        value: 'gpt-5'

      },

      {

        key: 'modelVersion',

        value: 'latest'

      }

    ],

    inputArtifactBindings: []

  };



  const responseData: AiConfigurationCreationResponse =

    await ConfigurationApi.configurationCreate(requestBody, {

      'AI-Resource-Group': 'default'

    }).execute();

  return responseData;

}
```

--------------------------------

### Initialize Orchestration Client

Source: https://sap.github.io/ai-sdk/docs/js/getting-started

Configure the client with a specific model and prompt template.

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



const orchestrationClient = new OrchestrationClient({

  promptTemplating: {

    model: {

      name: 'gpt-5'

    },

    prompt: {

      template: [

        { role: 'user', content: 'Answer the question: {{?question}}' }

      ]

    }

  }

});
```

--------------------------------

### Get batch job details

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/batch

Fetches the details of a specific batch job by its ID.

```javascript
const details = await BatchesApi.getBatchById(batchId, {

  'AI-Resource-Group': 'MY_RESOURCE_GROUP'

}).execute();
```

--------------------------------

### Basic Agent Usage

Source: https://sap.github.io/ai-sdk/docs/js/langchain/openai

Shows how to initialize an agent using the AzureOpenAiChatClient and the createAgent function.

```typescript
import { createAgent } from 'langchain';

import { AzureOpenAiChatClient } from '@sap-ai-sdk/langchain';



const model = new AzureOpenAiChatClient({ modelName: 'gpt-5' });



const agent = createAgent({

  model,

  tools: []

});



const agentInputs = {

  messages: [{ role: 'user', content: 'What is SAP?' }]

};



const result = await agent.invoke(agentInputs);
```

--------------------------------

### Initialize reasoning models

Source: https://sap.github.io/ai-sdk/docs/js/langchain/openai

Configure max_tokens for reasoning models, which the SDK maps to max_completion_tokens.

```javascript
const client = new AzureOpenAiChatClient({

  modelName: 'gpt-5-mini',

  max_tokens: 1000

});



const response = await client.invoke('What is the capital of France?', {

  requestConfig: {

    params: {

      'api-version': '2024-12-01-preview'

    }

  }

});
```

--------------------------------

### Preprocess, embed, and store documents

Source: https://sap.github.io/ai-sdk/docs/js/langchain/openai

Demonstrates the workflow of splitting documents, initializing the embedding client, and creating a vector store for retrieval.

```typescript
// Create a text splitter and split the document

const textSplitter = new RecursiveCharacterTextSplitter({

  chunkSize: 2000,

  chunkOverlap: 200

});

const splits = await textSplitter.splitDocuments(docs);



// Initialize the embedding client

const embeddingClient = new AzureOpenAiEmbeddingClient({

  modelName: 'text-embedding-3-small'

});



// Create a vector store from the document

const vectorStore = await MemoryVectorStore.fromDocuments(

  splits,

  embeddingClient

);



// Create a retriever for the vector store

const retriever = vectorStore.asRetriever();
```

--------------------------------

### Initialize SapOpenAiRealtimeWs client

Source: https://sap.github.io/ai-sdk/docs/js/openai/realtime

Initialize the client using different deployment configurations including model names, versions, or specific deployment IDs.

```javascript
// By model name (shorthand)

const client = await SapOpenAiRealtimeWs.createClient('gpt-realtime');



// By model name and version

const clientWithNameVersion = await SapOpenAiRealtimeWs.createClient({

  deployment: { modelName: 'gpt-realtime', modelVersion: 'latest' }

});



// By deployment ID

const clientWithDeploymentId = await SapOpenAiRealtimeWs.createClient({

  deployment: { deploymentId: 'DEPLOYMENT_ID' }

});
```

--------------------------------

### Initialize Client with Custom Destination

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models

Provide a custom destination name during client initialization.

```javascript
const client = await new AzureOpenAiChatClient('gpt-5', {

  destinationName: 'my-destination'

});
```

--------------------------------

### Initialize SAP OpenAI Client

Source: https://sap.github.io/ai-sdk/docs/js/openai

Create a pre-configured client using model names, deployment IDs, or custom destinations.

```typescript
import { SapOpenAi } from '@sap-ai-sdk/openai';



// By model name (shorthand)

const clientA = await SapOpenAi.createClient('gpt-5.4');



// By model name and version

const clientB = await SapOpenAi.createClient({

  deployment: { modelName: 'gpt-5.4', modelVersion: '2025-04-14' }

});



// By deployment ID

const clientC = await SapOpenAi.createClient({

  deployment: { deploymentId: 'DEPLOYMENT_ID' }

});
```

```typescript
const client = await SapOpenAi.createClient({

  deployment: { modelName: 'gpt-5.4', resourceGroup: 'my-resource-group' }

});
```

```typescript
const client = await SapOpenAi.createClient({

  deployment: { modelName: 'gpt-5.4' },

  destination: { destinationName: 'DESTINATION_NAME' }

});
```

--------------------------------

### Configure Environment Variables

Source: https://sap.github.io/ai-sdk/docs/js/getting-started

Define the AI Core service key in a .env file for local development.

```text
AICORE_SERVICE_KEY='{

  "clientid": "...",

  ...

}'
```

--------------------------------

### Create a LangChain Agent with OrchestrationClient

Source: https://sap.github.io/ai-sdk/docs/js/langchain/orchestration

Initialize an agent using the OrchestrationClient as the model provider.

```typescript
import { createAgent } from 'langchain';
import { OrchestrationClient } from '@sap-ai-sdk/langchain';

const model = new OrchestrationClient({
  promptTemplating: {
    model: {
      name: 'gpt-5'
    }
  }
});

const agent = createAgent({
  model,
  tools: []
});

const agentInputs = {
  messages: [{ role: 'user', content: 'What is SAP?' }]
};

const result = await agent.invoke(agentInputs);
```

--------------------------------

### SapOpenAi.createClient

Source: https://sap.github.io/ai-sdk/docs/js/openai

Initializes a pre-configured client for interacting with SAP AI Core OpenAI deployments.

```APIDOC
## SapOpenAi.createClient

### Description
Creates a new instance of the SapOpenAi client. You can configure the client using a model name string, a deployment identifier object, or a custom destination.

### Parameters
- **deployment** (string | object) - Required - The model name or an object containing modelName, modelVersion, or deploymentId.
- **resourceGroup** (string) - Optional - The resource group to target (defaults to 'default').
- **destination** (object) - Optional - Custom SAP AI Core destination configuration.
```

--------------------------------

### Initialize with Custom Destination

Source: https://sap.github.io/ai-sdk/docs/js/langchain/orchestration

Advanced initialization allowing specification of LangChain options, deployment configuration, and custom destination settings.

```typescript
const client = new OrchestrationClient(

  orchestrationConfig,

  langchainOptions,

  deploymentConfig,

  { destinationName: 'my-destination' }

);
```

--------------------------------

### Switching Models with Harmonized API

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Demonstrates how to change the model configuration in the prompt templating object to switch between different LLMs.

```javascript
// Original config for using GPT 4o

/*

const promptTemplating = {

  model: {

    name: 'gpt-5'

  }

};

*/



// Switch to Claude 3.5 Sonnet

const promptTemplating = {

  model: {

    name: 'anthropic--claude-3.5-sonnet'

  }

};
```

--------------------------------

### Create a Batch Job

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/batch

Initiate the batch job by referencing the uploaded input file and specifying the output directory.

```typescript
import { BatchesApi } from '@sap-ai-sdk/llm-batch';



const response = await BatchesApi.createBatch(

  {

    type: 'llm-native',

    input: { uri: 'ai://MY_OBJECT_STORE/input-batch.jsonl' },

    output: { uri: 'ai://MY_OBJECT_STORE/output/' },

    spec: { provider: 'azure-openai', model: 'gpt-5' }

  },

  { 'AI-Resource-Group': 'MY_RESOURCE_GROUP' }

).execute();



console.log('Batch job created:', response.id);
```

--------------------------------

### Initialize Agent Tools and Model

Source: https://sap.github.io/ai-sdk/docs/js/tutorials/getting-started-agents

Define tools for the agent and bind them to an Azure OpenAI model instance.

```typescript
// Define the tools for the agent to use

const tools = [...(await mcpClient.getTools()), getRestaurantsTool];

const toolNode = new ToolNode(tools);



// Create a model

const model = new AzureOpenAiChatClient({

  modelName: 'gpt-5-mini',

  maxRetries: 0

});



// create a model with access to the tools

const modelWithTools = model.bindTools(tools);
```

--------------------------------

### Initialize Client and Send Request

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/chat-completion

Initialize the AzureOpenAiChatClient and send an initial request including the defined tool.

```typescript
const client = new AzureOpenAiChatClient('gpt-5');

const messages: AzureOpenAiChatCompletionRequestMessage[] = [

  {

    role: 'user',

    content: 'Convert 20 degrees Celsius to Fahrenheit.'

  }

];



const response = await client.run({

  messages,

  tools: [convertTemperatureTool]

});
```

--------------------------------

### Configure Static Prompt Templates

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Define a static prompt template within the client configuration using promptTemplating.prompt.template, which is included in every chatCompletion call.

```javascript
const orchestrationClient = new OrchestrationClient({

  promptTemplating: {

    model: {

      name: 'gpt-5'

    },

    prompt: {

      template: [

        { role: 'user', content: 'What is the capital of {{?country}}?' }

      ]

    }

  }

});



const response = await orchestrationClient.chatCompletion({

  placeholderValues: { country: 'France' }

});
```

--------------------------------

### client.responses.create

Source: https://sap.github.io/ai-sdk/docs/js/openai

Creates a new response from the model based on provided instructions and input.

```APIDOC
## client.responses.create

### Description
Generates a response from the model. Supports streaming, stateful conversation history via `previous_response_id`, and tool calling.

### Parameters
- **instructions** (string) - Optional - System instructions for the model.
- **input** (string | ResponseInputItem[]) - Required - The user input or conversation context.
- **stream** (boolean) - Optional - If true, returns a stream of events.
- **previous_response_id** (string) - Optional - ID of the previous response to maintain stateful conversation history.
- **tools** (array) - Optional - List of function tools available for the model to call.
```

--------------------------------

### Initialize OrchestrationClient

Source: https://sap.github.io/ai-sdk/docs/js/langchain/orchestration

Basic initialization of the client using a configuration object that defines prompt templating and model settings.

```typescript
import { OrchestrationClient } from '@sap-ai-sdk/langchain';

import type { LangChainOrchestrationModuleConfig } from '@sap-ai-sdk/langchain';



const config: LangChainOrchestrationModuleConfig = {

  promptTemplating: {

    model: {

      name: 'gpt-5'

    }

  }

};

const client = new OrchestrationClient(config);
```

--------------------------------

### Initialize client with custom destination

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/embedding

Specify a destination name during client initialization to target a specific service destination.

```javascript
const client = new OrchestrationEmbeddingClient(

  orchestrationEmbeddingConfig,

  deploymentConfig,

  { destinationName: 'YOUR_DESTINATION_NAME' }

);
```

--------------------------------

### Create an Artifact

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/ai-api

Demonstrates creating a new artifact in SAP AI Core by specifying the name, kind, URL, and scenario ID.

```typescript
async function createArtifact() {

  const requestBody: AiArtifactPostData = {

    name: 'training-test-dataset',

    kind: 'dataset',

    url: 'https://ai.example.com',

    scenarioId: 'foundation-models'

  };



  const responseData: AiArtifactCreationResponse =

    await ArtifactApi.artifactCreate(requestBody, {

      'AI-Resource-Group': 'default'

    }).execute();

  return responseData;

}
```

--------------------------------

### RptClient Constructor

Source: https://sap.github.io/ai-sdk/docs/js/rpt

Initializes a new instance of the RptClient to interact with the SAP-RPT-1 model.

```APIDOC
## RptClient Constructor

### Description
Initializes the client for the SAP-RPT-1 model. By default, it uses 'sap-rpt-1-small', but can be configured to use 'sap-rpt-1-large'.

### Signature
new RptClient(modelName?: string)

### Parameters
- **modelName** (string) - Optional - The name of the model to use (e.g., 'sap-rpt-1-large'). Defaults to 'sap-rpt-1-small'.
```

--------------------------------

### Initialize Azure OpenAI LangChain Clients

Source: https://sap.github.io/ai-sdk/docs/js/langchain/openai

Basic initialization of chat and embedding clients using model names.

```typescript
import {

  AzureOpenAiChatClient,

  AzureOpenAiEmbeddingClient

} from '@sap-ai-sdk/langchain';



const chatClient = new AzureOpenAiChatClient({ modelName: 'gpt-5' });

const embeddingClient = new AzureOpenAiEmbeddingClient({

  modelName: 'text-embedding-3-small'

});
```

--------------------------------

### Initialize the RPT Client

Source: https://sap.github.io/ai-sdk/docs/js/rpt

Initialize the client with default or specific model versions.

```typescript
import { RptClient } from '@sap-ai-sdk/rpt';



const client = new RptClient();
```

```typescript
const client = new RptClient('sap-rpt-1-large');
```

--------------------------------

### Initialize Client with Custom Destination

Source: https://sap.github.io/ai-sdk/docs/js/langchain/openai

Configure a client to use a specific SAP AI Core destination.

```typescript
const chatClient = new AzureOpenAiChatClient(

  {

    modelName: 'gpt-5'

  },

  {

    destinationName: 'my-destination'

  }

);
```

--------------------------------

### Bind AI Core Service for CAP Hybrid Testing

Source: https://sap.github.io/ai-sdk/docs/js/connecting-to-ai-core

Commands to bind an AI Core instance and run a CAP application using the hybrid profile.

```bash
cds bind -2 AICORE_INSTANCE_NAME
```

```bash
cds-tsx watch --profile hybrid
```

--------------------------------

### client.chat.completions.create

Source: https://sap.github.io/ai-sdk/docs/js/openai

Sends a chat completion request to the configured deployment.

```APIDOC
## client.chat.completions.create

### Description
Generates chat completions based on the provided messages.

### Parameters
- **messages** (array) - Required - An array of message objects with role and content.
```

--------------------------------

### Create a Deployment

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/ai-api

Creates a deployment based on a specific configuration ID.

```typescript
async function createDeployment() {

  const requestBody: AiDeploymentCreationRequest = {

    configurationId: '0a1b2c3d-4e5f6g7h'

  };

  const responseData: AiDeploymentCreationResponse =

    await DeploymentApi.deploymentCreate(requestBody, {

      'AI-Resource-Group': 'default'

    }).execute();

  return responseData;

}
```

--------------------------------

### Configure Module Fallback

Source: https://sap.github.io/ai-sdk/docs/js/langchain/orchestration

Initializes the OrchestrationClient with a list of configurations to attempt sequentially if the primary fails.

```typescript
import type { LangChainOrchestrationModuleConfigList } from '@sap-ai-sdk/langchain';



const orchestrationConfigs: LangChainOrchestrationModuleConfigList = [

  {

    // Primary configuration — fails if the model is unavailable

    promptTemplating: {

      model: {

        name: 'gpt-5',

        timeout: 10 // seconds; triggers fallback on timeout (non-streaming only)

      }

    }

  },

  {

    // Fallback configuration

    promptTemplating: {

      model: {

        name: 'anthropic--claude-4.5-haiku'

      }

    }

  }

];



const response = await new OrchestrationClient(orchestrationConfigs).invoke([

  { role: 'user', content: 'Tell me about SAP Cloud SDK.' }

]);
```

--------------------------------

### Advanced Chat Completion with Templating and Parsing

Source: https://sap.github.io/ai-sdk/docs/js/langchain/openai

Demonstrates chaining a prompt template, the AzureOpenAiChatClient, and a string output parser.

```typescript
import { AzureOpenAiChatClient } from '@sap-ai-sdk/langchain';

import { StringOutputParser } from '@langchain/core/output_parsers';

import { ChatPromptTemplate } from '@langchain/core/prompts';



// Initialize the client

const chatClient = new AzureOpenAiChatClient({ modelName: 'gpt-5' });



// Create a prompt template

const promptTemplate = ChatPromptTemplate.fromMessages([

  ['system', 'Answer the following in {language}:'],

  ['user', '{text}']

]);



// Create an output parser

const parser = new StringOutputParser();



// Chain together template, client and parser

const llmChain = promptTemplate.pipe(chatClient).pipe(parser);



// Invoke the chain

const response = await llmChain.invoke({

  language: 'german',

  text: 'What is the capital of France?'

});
```

--------------------------------

### Create an AI Configuration

Source: https://sap.github.io/ai-sdk/docs/js/tutorials/scoped-prompt-registry-templates

Initializes a configuration for the orchestration executable within a specific resource group.

```typescript
const configurationPostData: AiConfigurationBaseData = {

  name: 'CONFIG_EXAMPLE',

  executableId: 'orchestration',

  scenarioId: 'orchestration'

};



const result: AiConfigurationCreationResponse =

  await ConfigurationApi.configurationCreate(configurationPostData, {

    'AI-Resource-Group': 'MY_RESOURCE_GROUP'

  }).execute();
```

--------------------------------

### Update Module Configuration Structure

Source: https://sap.github.io/ai-sdk/docs/js/upgrade-guide

Consolidates llm and templating modules into a single promptTemplating module.

```javascript
const config = {

  llm: {

    model_name: 'gpt-5',

    model_params: {}

  },

  templating: {

    template: [

      { role: 'user', content: 'What is the capital of {{?country}}?' }

    ]

  }

};
```

```javascript
const config = {

  promptTemplating: {

    model: {

      name: 'gpt-5',

      params: {}

    },

    prompt: {

      template: [

        { role: 'user', content: 'What is the capital of {{?country}}?' }

      ]

    }

  }

};
```

--------------------------------

### Instantiate AzureOpenAI with createOpenAiConfig

Source: https://sap.github.io/ai-sdk/docs/js/openai

Use this configuration method when requiring endpoints not natively exposed by the SapOpenAi wrapper.

```typescript
import { AzureOpenAI } from 'openai';

import { createOpenAiConfig } from '@sap-ai-sdk/openai';



const config = await createOpenAiConfig('gpt-5.4');

const client = new AzureOpenAI(config);
```

--------------------------------

### Update Grounding Configuration

Source: https://sap.github.io/ai-sdk/docs/js/upgrade-guide

Replaces input_params and output_param with a unified placeholders object.

```javascript
buildDocumentGroundingConfig({

  input_params: ['groundingInput'],

  output_param: 'groundingOutput',

  filters: [...]

});
```

```javascript
buildDocumentGroundingConfig({

  placeholders: {

    input: ['groundingInput'],

    output: 'groundingOutput'

  },

  filters: [...]

});
```

--------------------------------

### SapOpenAiRealtimeWs.createClient

Source: https://sap.github.io/ai-sdk/docs/js/openai/realtime

Initializes and returns a new WebSocket client instance for the OpenAI Realtime API. It resolves the deployment based on the provided model name, version, or deployment ID.

```APIDOC
## SapOpenAiRealtimeWs.createClient

### Description
Creates a new client instance and establishes a WebSocket connection to the OpenAI Realtime API in SAP AI Core.

### Parameters
- **options** (string | object) - Required - Either a string representing the model name, or an object containing `deployment` (modelName, modelVersion, or deploymentId), `resourceGroup` (optional), and `destination` (optional).
```

--------------------------------

### PromptTemplatesApi.listPromptTemplates

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/prompt-registry

Retrieves a list of prompt templates from the SAP AI Core prompt registry, optionally specifying a scenario and custom destination.

```APIDOC
## listPromptTemplates

### Description
Fetches a list of prompt templates based on the provided scenario. Supports custom destination configuration and cache control.

### Method
SDK Method

### Parameters
#### Request Parameters
- **scenario** (string) - Required - The scenario identifier to filter prompt templates.

#### Execution Options
- **destinationName** (string) - Optional - The name of the custom destination to use for the request.
- **useCache** (boolean) - Optional - Whether to use cached destination information. Defaults to true.
```

--------------------------------

### OrchestrationEmbeddingClient Constructor

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/embedding

Initializes a new instance of the OrchestrationEmbeddingClient with specific destination settings.

```APIDOC
## new OrchestrationEmbeddingClient(config, deploymentConfig, options)

### Description
Initializes the client. You can specify a custom destination name and control caching behavior.

### Parameters
- **config** (object) - Required - Orchestration embedding configuration.
- **deploymentConfig** (object) - Required - Deployment configuration.
- **options** (object) - Optional - Contains `destinationName` (string) and `useCache` (boolean).
```

--------------------------------

### Create a basic response

Source: https://sap.github.io/ai-sdk/docs/js/openai

Generate a simple text response by providing instructions and an input string.

```typescript
const response = await client.responses.create({

  instructions: 'You are a helpful assistant.',

  input: 'What is the capital of France?'

});
```

--------------------------------

### Load Local Prompt Template

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Reads a YAML file from the local filesystem and uses its content as a prompt template for the OrchestrationClient.

```typescript
import { readFileSync } from 'fs';

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



// Read the YAML file containing the prompt template

const yamlTemplate = readFileSync('./path/to/prompt-template.yaml', 'utf-8');



const orchestrationClient = new OrchestrationClient({

  promptTemplating: {

    model: {

      name: 'gpt-5'

    },

    prompt: yamlTemplate

  }

});



const response = await orchestrationClient.chatCompletion({

  placeholderValues: { country: 'France' }

});
```

--------------------------------

### client.run()

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/embedding

Executes an embedding request using the AzureOpenAiEmbeddingClient.

```APIDOC
## client.run(request, options)

### Description
Sends an input string to the Azure OpenAI service to generate an embedding. The method returns a response object containing the embedding and raw HTTP details.

### Parameters
- **request** (object) - Required - The request configuration containing the `input` string.
- **options** (object) - Optional - Configuration for `middleware` (e.g., resilience) or `signal` (AbortSignal) for request cancellation.

### Request Example
```javascript
const response = await client.run({
  input: 'AI is fascinating'
});
```

### Response
- **getEmbedding()** (method) - Returns the generated embedding data.
- **rawResponse** (object) - Provides access to the underlying HTTP status, headers, and raw data.
```

--------------------------------

### Initialize AzureOpenAiChatClient

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models

Initialize the chat client using model names, deployment IDs, or custom resource groups.

```javascript
import { AzureOpenAiChatClient } from '@sap-ai-sdk/foundation-models';



const client = new AzureOpenAiChatClient('gpt-5');
```

```javascript
const client = new AzureOpenAiChatClient({

  modelName: 'gpt-5',

  // modelVersion: '2024-08-06', // optional

  resourceGroup: 'my-resource-group'

});
```

```javascript
const client = new AzureOpenAiChatClient({

  // resourceGroup: 'my-resource-group', // optional

  deploymentId: 'd1234'

});
```

--------------------------------

### Configure LLM model settings

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Defines the model name, version, and optional parameters like max_tokens for prompt templating.

```javascript
const promptTemplating = {

  model: {

    name: 'gpt-5',

    version: '2024-08-06', // optional

    params: {

      // optional

      max_tokens: 50

    }

  }

};
```

--------------------------------

### client.chat.completions.create

Source: https://sap.github.io/ai-sdk/docs/js/openai

Creates a chat completion request with optional model or deployment overrides.

```APIDOC
## client.chat.completions.create

### Description
Sends a chat completion request to the OpenAI service. You can override the client's default model or deployment configuration on a per-request basis.

### Parameters
- **model** (string | object) - Optional - The model configuration to use for this request. Can be a string (model name) or an object containing `modelName` and `modelVersion`, or `deploymentId`.
- **messages** (array) - Required - An array of message objects representing the conversation history.

### Request Example
```javascript
await client.chat.completions.create({
  model: 'gpt-5.4-nano',
  messages: [{ role: 'user', content: 'What is the capital of France?' }]
});
```
```

--------------------------------

### Initialize and Use OrchestrationEmbeddingClient

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/embedding

Initialize the client with model configuration and generate embeddings from input strings.

```typescript
import { OrchestrationEmbeddingClient } from '@sap-ai-sdk/orchestration';



const embeddingClient = new OrchestrationEmbeddingClient({

  embeddings: {

    model: {

      name: 'text-embedding-3-large'

      // version: 'latest',         // optional

      // params: { dimensions: 4 }  // optional, model-specific parameters

    }

  }

});



const response = await embeddingClient.embed({

  input: 'AI is fascinating'

  // type: 'text' // optional, Represents the task for which the embeddings need to be generated. Defaults to 'text'.

});



// Access the embedding vectors and usage

const data = response.getEmbeddings();

const usage = response.getTokenUsage();
```

--------------------------------

### Configure AzureOpenAI with createTokenProvider

Source: https://sap.github.io/ai-sdk/docs/js/openai

Provides an azureADTokenProvider-compatible function for custom AzureOpenAI client configurations.

```typescript
import { AzureOpenAI } from 'openai';

import { createTokenProvider } from '@sap-ai-sdk/openai';



const client = new AzureOpenAI({

  baseURL: 'https://my-deployment-url',

  apiVersion: '2024-10-21',

  azureADTokenProvider: createTokenProvider()

});
```

--------------------------------

### PromptTemplatesApi.listPromptTemplates

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/prompt-registry

Retrieves a list of prompt templates. Supports custom request configuration such as headers and parameters via the execute method.

```APIDOC
## PromptTemplatesApi.listPromptTemplates

### Description
Retrieves a list of prompt templates filtered by scenario. Custom request configurations like headers can be passed during execution.

### Method
SDK Method

### Parameters
- **scenario** (string) - Required - The scenario to filter prompt templates by.
- **requestConfig** (object) - Optional - Custom configuration including headers and parameters for the underlying request.
```

--------------------------------

### Create a Batch Job input

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/batch

Generate the input Blob from chat completion requests and upload it to the object store.

```typescript
import { createBatchInput } from '@sap-ai-sdk/foundation-models';

import { FileApi } from '@sap-ai-sdk/ai-api';



const blob = createBatchInput([

  {

    model: 'gpt-5',

    messages: [{ role: 'user', content: 'What is machine learning?' }],

    max_tokens: 150

  },

  {

    model: 'gpt-5',

    messages: [

      { role: 'user', content: 'Explain neural networks in simple terms' }

    ],

    max_tokens: 150

  }

]);



await FileApi.fileUpload(

  'MY_OBJECT_STORE/input-batch.jsonl',

  blob,

  { overwrite: true },

  { 'AI-Resource-Group': 'MY_RESOURCE_GROUP' }

).execute();
```

--------------------------------

### List Orchestration Configurations

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/prompt-registry

Retrieve a list of existing orchestration configurations filtered by scenario.

```typescript
const configs = await OrchestrationConfigsApi.listOrchestrationConfigs({

  scenario: 'customer-support'

}).execute();
```

--------------------------------

### Structured Output with Zod Schema

Source: https://sap.github.io/ai-sdk/docs/js/langchain/openai

Demonstrates how to enforce a specific output schema using Zod and the withStructuredOutput method.

```typescript
import * as z from 'zod';

import { AzureOpenAiChatClient } from '@sap-ai-sdk/langchain';



const llm = new AzureOpenAiChatClient({ modelName: 'gpt-5' });



const joke = z.object({

  setup: z.string().meta({ description: 'The setup of the joke' }),

  punchline: z.string().meta({ description: 'The punchline to the joke' }),

  rating: z

    .number()

    .meta({ description: 'How funny the joke is, from 1 to 10' })

});



const structuredLlm = llm.withStructuredOutput(joke, {

  name: 'joke',

  strict: true

});



const finalResponse = await structuredLlm.invoke('Tell me a joke about cats');
```

--------------------------------

### AzureOpenAiChatClient.run()

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models

Executes a request to the Azure OpenAI chat model with optional custom headers and request parameters.

```APIDOC
## SDK Method: AzureOpenAiChatClient.run()

### Description
Executes a chat completion request using the initialized Azure OpenAI client. Supports custom headers and request parameters for advanced configuration.

### Parameters
- **messages** (Array) - Required - An array of message objects (e.g., { role: 'user', content: '...' }).
- **requestConfig** (Object) - Optional - Configuration object containing headers and params.

### Request Example
```javascript
const response = await client.run(
  { messages: [{ role: 'user', content: 'What is the time in Tokyo?' }] },
  {
    headers: { 'premium-billing': 'premium-plan' },
    params: { 'api-version': '2024-08-06' }
  }
);
```

### Response
- **response** (Object) - The response object containing the model output, accessible via .getContent().
```

--------------------------------

### Apply Custom Headers for Metering

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models

Attach internal metering headers like premium-billing and user-context to requests.

```javascript
const response = await client.run(

  {

    messages: [{ role: 'user', content: 'What is the time in Tokyo?' }]

  },

  {

    headers: {

      'premium-billing': 'premium-plan',

      'user-context': 'userId=12345;role=developer'

    }

  }

);

console.log(response.getContent());
```

--------------------------------

### Update LangChain Orchestration Configuration

Source: https://sap.github.io/ai-sdk/docs/js/upgrade-guide

Migrate the configuration structure from v1 to v2, moving model and template definitions into a nested promptTemplating object.

```typescript
const config: LangChainOrchestrationModuleConfig = {

  llm: {

    model_name: 'gpt-5',

    model_params: {}

  },

  templating: {

    template: messages

  }

};
```

```typescript
const config: LangChainOrchestrationModuleConfig = {

  promptTemplating: {

    model: {

      name: 'gpt-5',

      params: {}

    },

    prompt: {

      template: messages

    }

  }

};
```

--------------------------------

### Creating Nested ErrorWithCause Instances

Source: https://sap.github.io/ai-sdk/docs/js/error-handling

Demonstrates how to chain multiple ErrorWithCause instances to represent a hierarchy of errors.

```javascript
const rootCause = new Error('The root cause is a bug!');

const lowerLevelErrorWithCause = new ErrorWithCause(

  'Failed to call function foo().',

  rootCause

);

const upperLevelErrorWithCause = new ErrorWithCause(

  'Process crashed.',

  lowerLevelErrorWithCause

);

throw upperLevelErrorWithCause;
```

--------------------------------

### createOpenAiConfig(modelName)

Source: https://sap.github.io/ai-sdk/docs/js/openai

Generates an AzureClientOptions object for direct instantiation of the AzureOpenAI client.

```APIDOC
## createOpenAiConfig(modelName)

### Description
Creates an `AzureClientOptions` object used for direct instantiation of `AzureOpenAI`. This is intended for scenarios requiring endpoints not exposed by the standard `SapOpenAi` interface.

### Parameters
- **modelName** (string) - Required - The name of the model to configure (e.g., 'gpt-5.4').

### Example
```typescript
import { AzureOpenAI } from 'openai';
import { createOpenAiConfig } from '@sap-ai-sdk/openai';

const config = await createOpenAiConfig('gpt-5.4');
const client = new AzureOpenAI(config);
```
```

--------------------------------

### Configure Scoped Prompt Registry Templates

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Specify the scope property in template_ref and provide the resourceGroup parameter in the client deployment configuration for isolated templates.

```javascript
const orchestrationClient = new OrchestrationClient(

  {

    promptTemplating: {

      model: {

        name: 'gpt-5'

      },

      prompt: {

        template_ref: {

          name: 'my-scoped-template',

          scenario: 'my-scenario',

          version: '0.0.1',

          scope: 'resource_group' // or 'tenant'

        }

      }

    }

  },

  {

    resourceGroup: 'my-resource-group'

  }

);
```

--------------------------------

### Load AzureOpenAiChatClient in CommonJS

Source: https://sap.github.io/ai-sdk/docs/js/overview

Use this syntax to import the client in projects still utilizing CommonJS, leveraging Node.js 22.12.0+ support for synchronous require of ESM modules.

```javascript
const { AzureOpenAiChatClient } = require('@sap-ai-sdk/foundation-models');
```

--------------------------------

### Reference Prompt Registry Templates

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Use template_ref to reference a template stored in the Prompt Registry by name, scenario, and version.

```javascript
const orchestrationClient = new OrchestrationClient({

  promptTemplating: {

    model: {

      name: 'gpt-5'

    },

    prompt: {

      template_ref: {

        name: 'my-get-capital-template',

        scenario: 'my-scenario',

        version: '0.0.1'

      }

    }

  }

});



const response = await orchestrationClient.chatCompletion({

  placeholderValues: { country: 'France' }

});
```

--------------------------------

### Manage Pipelines with PipelinesApi

Source: https://sap.github.io/ai-sdk/docs/js/ai-core/document-grounding

Demonstrates listing, creating, and checking the status of pipelines in a specified resource group.

```typescript
const getAllPipelinesResponse = await PipelinesApi.getAllPipelines(

  {

    $top: 10

  },

  {

    'AI-Resource-Group': 'default'

  }

).execute();



const createPipelineResponse = await PipelinesApi.createPipeline(

  {

    configuration: {

      destination: 'my-destination',

      sharePoint: {

        site: {

          name: 'sharepoint-site-name'

        }

      }

    },

    type: 'MSSharePoint'

  },

  {

    'AI-Resource-Group': 'default'

  }

).execute();



const getPipelineStatusResponse = await PipelinesApi.getPipelineStatus(

  'pipeline-id',

  {

    'AI-Resource-Group': 'default'

  }

).execute();
```

--------------------------------

### Create an Orchestration Deployment

Source: https://sap.github.io/ai-sdk/docs/js/tutorials/scoped-prompt-registry-templates

Deploys the orchestration service for a target resource group.

```typescript
const deploymentPostData: AiDeploymentCreationRequest = {

  configurationId: '3d2c1b0a'

};



const deploymentResponse = await DeploymentApi.deploymentCreate(

  deploymentPostData,

  { 'AI-Resource-Group': 'MY_RESOURCE_GROUP' }

).execute();
```

--------------------------------

### Perform Chat Completions

Source: https://sap.github.io/ai-sdk/docs/js/openai

Execute chat completion requests using the initialized client.

```typescript
const response = await client.chat.completions.create({

  messages: [{ role: 'user', content: 'What is the capital of France?' }]

});
```

```typescript
import { zodResponseFormat } from 'openai/helpers/zod';

import { z } from 'zod';



const CapitalResponse = z.object({ capital: z.string() });



const response = await client.chat.completions.parse({

  messages: [{ role: 'user', content: 'What is the capital of France?' }],

  response_format: zodResponseFormat(CapitalResponse, 'capital_response')

});
```

--------------------------------

### Agent Graph State Transition

Source: https://sap.github.io/ai-sdk/docs/js/tutorials/getting-started-agents

Indicates the next node in the agent graph execution flow.

```text
next:  [ 'askHuman' ]
```

--------------------------------

### Configure Custom Request Parameters

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models

Pass custom headers and parameters to the run method to override default request configurations.

```javascript
const response = await client.run(

  // ...

  {

    headers: {

      'x-custom-header': 'custom-value'

      // Add more headers here

    },

    params: {

      // Add more parameters here

    }

    // Add more request configuration here

  }

);
```

```javascript
const response = await client.run(

  // ...

  {

    params: {

      'api-version': 'AZURE_OPENAI_API_VERSION'

    }

  }

);
```

--------------------------------

### Define JSON Schema using Zod

Source: https://sap.github.io/ai-sdk/docs/js/foundation-models/openai/chat-completion

Demonstrates how to generate a JSON schema for the response_format parameter using Zod and the @langchain/core utility.

```typescript
import * as z from 'zod';

import { toJsonSchema } from '@langchain/core/utils/json_schema';

import { AzureOpenAiResponseFormatJsonSchema } from '@sap-ai-sdk/foundation-models';



const countryCapitalSchema = z.strictObject({

  population: z.number(),

  capital: z.string()

});



const response_format: AzureOpenAiResponseFormatJsonSchema = {

  type: 'json_schema',

  json_schema: {

    name: 'capital_response',

    strict: true,

    schema: toJsonSchema(countryCapitalSchema)

  }

};
```

--------------------------------

### client.on

Source: https://sap.github.io/ai-sdk/docs/js/openai/realtime

Registers event listeners for incoming messages from the WebSocket connection.

```APIDOC
## client.on

### Description
Registers a callback function for a specific event type emitted by the WebSocket connection.

### Parameters
- **event** (string) - Required - The name of the event (e.g., 'session.created', 'response.output_audio.delta', 'error').
- **callback** (function) - Required - The function to execute when the event is received.
```

--------------------------------

### Configure resource group for client

Source: https://sap.github.io/ai-sdk/docs/js/openai/realtime

Target a specific resource group if the default is not desired.

```javascript
const client = await SapOpenAiRealtimeWs.createClient({

  deployment: { modelName: 'gpt-realtime', resourceGroup: 'my-resource-group' }

});
```

--------------------------------

### Configure Dynamic Prompt Messages

Source: https://sap.github.io/ai-sdk/docs/js/orchestration/chat-completion

Use the messages property in chatCompletion to vary the message list per request without re-initializing the client.

```javascript
const orchestrationClient = new OrchestrationClient({

  promptTemplating: {

    model: {

      name: 'gpt-5'

    }

  }

});



const response = await orchestrationClient.chatCompletion({

  messages: [{ role: 'user', content: 'What is the capital of {{?country}}?' }],

  placeholderValues: { country: 'France' }

});
```

--------------------------------

### createTokenProvider()

Source: https://sap.github.io/ai-sdk/docs/js/openai

Creates an azureADTokenProvider-compatible function for custom AzureOpenAI configurations.

```APIDOC
## createTokenProvider()

### Description
Returns a function compatible with `azureADTokenProvider` for use in custom `AzureOpenAI` client configurations.

### Example
```typescript
import { AzureOpenAI } from 'openai';
import { createTokenProvider } from '@sap-ai-sdk/openai';

const client = new AzureOpenAI({
  baseURL: 'https://my-deployment-url',
  apiVersion: '2024-10-21',
  azureADTokenProvider: createTokenProvider()
});
```
```
Tokens:
Raw