Learn SAP Business AI, Joule and AI agents for free, from first steps to production

You don't need a data science background. If these ideas are clear, everything else in this portal builds on them.

SAP uses "SAP Business AI" as the umbrella name for everything below. At Sapphire 2026 SAP presented the technology underneath as one "Business AI Platform" that joins SAP BTP, SAP Business Data Cloud and Business AI. The layers still map to separate services you provision and pay for.

People

Business user

Developer

→chat
code

SAP Business Technology Platform

Joule Studio

SAP Build

CAP app (@mcp, @agent)

SAP AI Core · Gen AI Hub

SAP AI Launchpad

Document grounding

SAP HANA Cloud (vectors)

SAP Business Data Cloud

→API

Model providers

Partner LLMs

SAP-hosted / open models

Highlighted: what you build with. Service icons from SAP's BTP solution diagram guideline.

At three to four hours a week, the developer path takes about four weeks. Do the lab at the end, because it uses everything before it.

What you need

• Nothing paid to start. Node.js 20+, VS Code and @sap/cds-dk are free. The lab runs locally on SQLite.
• An LLM for local agent runs: kind: "mock" costs nothing. kind: "auto" reuses Claude Code or OpenCode if you already use one.
• An SAP BTP trial for the cloud steps. Check the SAP Discovery Center for which AI services the trial or free tier includes in your region.

SAP Business AI covers three kinds of offering:

• Embedded AI scenarios inside SAP applications, such as invoice matching, forecasting and text generation in HR.
• Joule and Joule agents, prebuilt agents for domains like finance, procurement and customer service.
• The AI foundation on BTP, which you use to build your own (Tracks 2 and 3).

At Sapphire 2026 SAP announced an Autonomous Suite, with Joule as the main way people run business processes and more than 50 domain-specific Joule assistants planned across finance, supply chain, procurement, HR and CX. SAP also announced an AI Agent Hub for SAP and third-party agents, and agent-to-agent integration between Microsoft 365 Copilot and Joule.

Joule is SAP's conversational assistant, built into SAP cloud apps and SAP Start. What it does falls into four types:

Joule works under the signed-in user's identity and authorizations, so it can only see and do what that user can. Capire's Joule integration page describes SAP Joule Work as the client that can consume CAP MCP services. That page is still marked "under construction" (see 3.8).

Joule Studio is where you extend Joule. It has two builders:

1. Create a Joule Studio project in SAP Build and pick Joule Agent.
2. Write the agent's instructions in plain language: its goal, its limits, its tone.
3. Add tools: existing skills, actions on BTP destinations, or an MCP server such as your CAP app's /mcp/<service>.
4. Add grounding documents if the agent must answer from policies or manuals.
5. Test in the built-in chat, then deploy to the Joule environment and assign it to users.

Most AI projects that fail had the wrong scope, not the wrong model. Use these questions in a workshop with the business owner.

Quick scoring

Score each candidate from 1 to 5 on value, data readiness and low risk. Start with the one that has the highest total, not the most exciting one. A good first project is high value, uses data that already exists in one system, and keeps a human approving the result.

SAP AI Core is the BTP service that runs AI workloads: your own trained models, and access to foundation models. SAP AI Launchpad is its UI for browsing models, creating deployments, trying prompts and watching usage.

• Resource group: an isolation boundary, often one per tenant or team.
• Scenario / configuration / deployment: a deployment gives you a URL. Foundation models are deployed this way too, under the foundation-models scenario.
• Service plan: Generative AI Hub features need the extended plan. You pay for usage, not a fixed fee.

The Generative AI Hub gives you models from several vendors (SAP-hosted, open-weight and partner models such as Anthropic, Google, Mistral and OpenAI) behind one API. The orchestration service chains modules into a pipeline that runs in a single call. The output of each module is the input to the next.

flowchart LR
  IN[Request] --> T[Templating - required]
  T --> G[Grounding]
  G --> M[Data masking]
  M --> F1[Input filter]
  F1 --> LLM[Model]
  LLM --> F2[Output filter]
  F2 --> OUT[Response]
  

The SDK lives at github.com/SAP/ai-sdk-js. The packages you will use most:

• @sap-ai-sdk/orchestration: orchestration client (templating, filtering, grounding).
• @sap-ai-sdk/foundation-models: direct model clients.
• @sap-ai-sdk/langchain: LangChain chat models built on the SAP clients, for LangChain or LangGraph agents.

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

const client = new OrchestrationClient({
  promptTemplating: {
    model: { name: 'gpt-4o' },   // use a name from your AI Launchpad
    prompt: {
      template: [
        { role: 'system', content: 'You summarize customer disputes for collectors.' },
        { role: 'user',   content: 'Summarize in 3 bullets: {{?text}}' }
      ]
    }
  }
});

const res = await client.chatCompletion({ placeholderValues: { text } });
console.log(res.getContent());

Retrieval-augmented generation (RAG) means finding the most relevant records or text chunks first and putting them in the prompt, so the model answers from your data instead of guessing. SAP gives you two routes:

• Managed: the orchestration service's grounding module, fed from uploaded documents or a HANA Cloud vector store.
• In your app: store embeddings in CDS entities with Vector (module 3.2) and run similarity queries in CQL before calling the model.

The in-app route keeps permissions simple. Retrieval runs through your CAP service, so the user only gets back rows they can already read.

When neither Joule Studio nor CAP's @agent fits, SAP's AI Golden Path supports building the agent yourself. It names these frameworks: LangGraph, CrewAI, AG2 (AutoGen), Google ADK, Pydantic AI and Smolagents. The SAP Cloud SDK for AI gives them model access through the Generative AI Hub, in JavaScript, Java and Python.

import { OrchestrationClient } from '@sap-ai-sdk/langchain';
import { createReactAgent } from '@langchain/langgraph/prebuilt';
import { tool } from '@langchain/core/tools';
import { z } from 'zod';

// a tool that calls your own CAP service, so CAP's auth still applies
const similarDisputes = tool(
  async ({ text }) => fetchFromCap(`/odata/v4/dispute/similar(text='${encodeURIComponent(text)}')`),
  { name: 'similar_disputes', description: 'Past disputes with a similar reason',
    schema: z.object({ text: z.string() }) }
);

const llm = new OrchestrationClient({ promptTemplating: { model: { name: 'gpt-4o' } } });
const agent = createReactAgent({ llm, tools: [similarDisputes] });
const out = await agent.invoke({ messages: [{ role: 'user', content: 'Invoice 9001 was double charged' }] });

Bring your own agent into Joule

1. Deploy the agent to SAP BTP (Cloud Foundry or Kyma) behind XSUAA.
2. Expose it as an A2A endpoint. CAP agents already are one.
3. Create a Joule scenario that calls that endpoint, so Joule can hand tasks to it. This is pattern 3 in RA0029.

Joule Studio agents run on SAP AI Core as a managed runtime, so you don't host them yourself. Pro-code agents you host and operate yourself. The Agent Gateway, which will let Joule agents call out to external systems, is not GA yet and supports only outbound calls.

An agent needs three things from an application: what data exists, how to read it, and which actions it may take. A CDS model already holds all three.

• Entities and doc comments (/** … */, @title, @description) become the schema the describe tool returns.
• CQL is a compact query language that LLMs write well. The MCP query tool takes CQL directly.
• Actions and functions become callable tools, with your handlers and authorization checks still in charge.
• Projections let you build a narrow, use-case-specific service for each agent.

npm add -g @sap/cds-dk
cds init dispute-desk --add sample
cd dispute-desk && npm i
cds watch          # http://localhost:4004

Add a Vector element. If you leave out the dimension, switching embedding models is easier. Make it a stored calculated element and CAP recalculates the embedding whenever its source fields change:

extend Incidents with {
  embedding : Vector = vector_embedding(
    'Title: ' || title || ', Summary: ' || summary,
    'DOCUMENT', 'SAP_GXY.20250407'
  ) stored;
}

Search with cosine_similarity. Embed the question as 'QUERY' and the stored text as 'DOCUMENT':

const question = 'Fetch incidents with solar inverters. How were they resolved?'
const incidents = await SELECT.from`Incidents`
  .where`cosine_similarity (embedding,
    vector_embedding (${question}, 'QUERY', 'SAP_GXY.20250407')
  ) > 0.75`

Local development: on SQLite, vector_embedding is emulated with lexical hashes, which match on spelling, not meaning. For real semantic results locally, add the experimental @cap-js/ai plugin, which runs an ONNX model. It needs @sap/cds ^10.1 and @cap-js/sqlite ^3.1:

npm add -D @cap-js/ai @cap-js/sqlite @huggingface/hub \
  @huggingface/tokenizers onnxruntime-node

The Model Context Protocol (MCP) is the open standard that AI clients such as Claude, OpenCode and Joule Studio use to discover and call tools. The CAP adapter serves each @mcp service as its own MCP server at /mcp/<service>.

npm add @cap-js/mcp

// srv/cat-service.cds
annotate CatalogService with @mcp;                // → /mcp/browse
annotate CatalogService.Books with @mcp.instructions:
  'Prefer filtering by genre before listing all books.';

The three generic tools

Agents can't write to entities directly. Every change goes through an action you wrote, so your validation and authorization always run.

Connecting a client

• Autowiring: cds watch registers the endpoints with Claude Code (~/.claude.json) and OpenCode, using mock user alice.
• MCP Inspector: npx @modelcontextprotocol/inspector, choose streamable-http, URL http://localhost:4004/mcp/browse.
• Server card: cds compile srv/cat-service.cds --to mcp.

Annotate a service with @agent and the plugin builds an agent that uses the service's entities and actions as its tools, through the same describe, query and call tools as MCP. It's served over the Agent-to-Agent (A2A) protocol at /a2a/<service>.

using { CatalogService } from './cat-service';
annotate CatalogService with @agent;                // → /a2a/browse
annotate CatalogService.submitOrder with @agent.hitl;  // needs human approval

With @agent.hitl, the A2A task moves to input-required and waits for a person to approve before the action runs. This is Node.js only.

Give it a persona with AGENTS.md, and skills with SKILL.md

srv/travel-agent/
 ├── AGENTS.md          # frontmatter → agent card; body → system prompt
 ├── skills/
 │   ├── flight-booking/SKILL.md
 │   ├── itinerary/SKILL.md
 │   └── planning/SKILL.md
 ├── service.cds
 └── service.js

---
name: travel-agent
version: 1.0.0
description: Plans business trips and books flights, hotels and events.
---
You help employees plan trips within the travel policy.
Always confirm dates and budget before booking anything.

Each skill has frontmatter (name, description, metadata.tags, metadata.examples) and sections such as "When to Use" and "Instructions". Skills keep the context window focused on the current subtask.

Pick the model

"cds": {
  "requires": {
    "llm": { "kind": "aicore", "model": "anthropic--claude-4.6-sonnet" }
  }
}

Run and chat

npm add @cap-js/agents
DEBUG=agents cds watch
# chat preview (experimental):
# http://localhost:4004/a2a/browse/preview/

Subagents: other @agent services, including ones imported from other CAP projects, can act as subagents. The main agent coordinates them over A2A.

Don't put @mcp or @agent on your big general-purpose service. Write a small projection service for each use case. It controls what the model sees (fewer tokens, fewer mistakes) and what it can change.

using { sap.capire.bookshop as my } from '../db/schema';

/** Lets customers browse books and place orders. */
@mcp @agent
service ShopAgent @(path:'/shop') {
  @readonly @cds.query.limit: 50
  entity Books as projection on my.Books { ID, title, genre, price, stock };

  /** Orders a quantity of one book. Fails if stock is too low. */
  @requires: 'authenticated-user'
  action submitOrder(book : Books:ID, quantity : Integer) returns { stock : Integer };
}
annotate ShopAgent.submitOrder with @agent.hitl;

• Read-only by default: @readonly projections, with writes only through actions.
• Leave out sensitive fields in the projection, rather than trusting the prompt to ignore them.
• Authorization: @requires and @restrict apply to agent calls exactly as they do to UI calls.
• Doc comments are prompts. Write them for an LLM reader: units, allowed values, side effects.

XTravels is a travel-planning app from Capire's Native AI section. One travel agent coordinates four CAP services, each exposed over MCP:

flowchart LR
  A[Travel agent - @agent] --> T[Travels: approve or reject requests]
  A --> E[Events: browse and book tickets]
  A --> H[Hotels: browse and book rooms]
  A --> F[Flights: airports, flights, seats]
  

Study it for three patterns: services in subfolders (cds.folders.srvs: srv/*), skills split by subtask, and approval steps for anything that books or spends money.

Capire describes these directions, but doesn't give steps yet:

• Joule Work acts as an AI client for CAP MCP services.
• Joule Studio agents call MCP services exposed by CAP apps.
• CAP agents join Joule as agents that delegate to CAP subagents.
• Deploying to the Joule Studio runtime makes CAP agents and MCP services available inside Joule.
• SAP MCP Gateway governs all of it: policy, security, monitoring.

What works today: deploy your CAP app to BTP, register /mcp/<service> as an MCP server tool in Joule Studio's agent builder (through a BTP destination), and test it from the Joule Studio chat.

This is a separate topic from building agents. Here the AI helps you write the app.

• @cap-js/mcp-server gives coding agents (Claude Code, Copilot, Cursor) tools to search your CDS model and the CAP docs. Don't confuse it with @cap-js/mcp.
• Every Capire page is available as Markdown: add .md to the URL, or start from /sitemap.md. Point your coding agent there.
• Put an AGENTS.md at the project root with your conventions, such as "use cds.ql, not raw SQL" or "every new action needs a test".

Most real agent use cases need S/4HANA data, such as the open items behind a dispute. In CAP you consume a released S/4HANA API as a remote service:

# download the API's EDMX from api.sap.com (SAP Business Accelerator Hub), then:
cds import API_BUSINESS_PARTNER.edmx      # → srv/external/, adds cds.requires entry

"cds": { "requires": {
  "API_BUSINESS_PARTNER": {
    "kind": "odata-v2",
    "model": "srv/external/API_BUSINESS_PARTNER",
    "credentials": { "destination": "S4HANA", "path": "/sap/opu/odata/sap/API_BUSINESS_PARTNER" }
  }
}}

const bupa = await cds.connect.to('API_BUSINESS_PARTNER')
const partner = await bupa.run(
  SELECT.one.from('A_BusinessPartner').columns('BusinessPartner', 'BusinessPartnerFullName')
    .where({ BusinessPartner: dispute.customer }))

• Destinations hold the URL and authentication. Since the September 2026 release, CAP Node.js can resolve BTP destinations without the SAP Cloud SDK (beta).
• Principal propagation (for example OAuth2SAMLBearerAssertion, or the Cloud Connector for on-premise) makes S/4HANA see the real user, not a technical user. That way S/4 authorizations still apply when an agent works for that user.
• Clean core: use released APIs only, never modify the S/4 core, and keep the extension on BTP.

Where the policy line is

Multitenant apps: if you sell the app to several customers, the tenant comes from the user's token, and every tool call, embedding and log line must stay inside that tenant. See RA0007 in module 4.4.

Agents need two kinds of tests. Unit tests check that your actions, auth and data are correct, and they run in seconds. Evaluations check that the model picks the right tools and stays inside its limits, and they run against a real model.

const cds = require('@sap/cds')

describe('DisputeService', () => {
  const { GET, POST, expect } = cds.test(__dirname + '/..')
  const auth = { username: 'alice' }

  it('rejects anonymous users', async () => {
    await expect(GET('/odata/v4/dispute/Disputes')).to.be.rejected
  })

  it('resolve marks a dispute resolved', async () => {
    const ID = '…an ID from your CSV…'
    const { data } = await POST('/odata/v4/dispute/resolve', { ID, resolution: 'Credit note issued' }, { auth })
    expect(data.status).to.equal('resolved')
  })
})

A simple evaluation set

• Use llm.kind: "mock" in CI so tests don't depend on a model or cost money.
• Run the evaluation set against the real model nightly and after any model or prompt change. Read the tool calls from DEBUG=agents logs or telemetry.
• Snapshot the describe output in a test. If a CDS change alters what the agent sees, the test tells you.
• Capire lists built-in evaluation testing for @cap-js/agents as upcoming.

sequenceDiagram
  participant U as User
  participant J as Joule or chat client
  participant A as CAP agent (A2A)
  participant M as CAP MCP tools
  U->>J: Resolve dispute D-102
  J->>A: A2A task
  A->>M: describe / query
  M-->>A: rows
  A-->>J: input-required (HITL)
  J->>U: Approve credit of 120 EUR?
  U->>J: Approve
  J->>A: continue
  A->>M: call resolve
  A-->>J: completed
  

The standards SAP backs

SAP's "Global Standards for Agentic AI" page in the Architecture Center commits to MCP and A2A for data, transactional and agent-to-agent access. It also names the Agentic AI Foundation (AAIF) as SAP's main joint standards effort, adopts OpenTelemetry for observability, and says SAP is exploring the SKILL.md specification, the same format CAP agents use. For agents that other companies' systems call, SAP's Golden Path prefers A2A over exposing MCP directly, because A2A gives more control over access.

These combine well. A common setup: CAP exposes MCP tools and an agent for its own domain, and a Joule Studio agent uses that agent as one of its tools alongside SAP's own Joule agents.

Architecture anti-patterns

Before you design something new, check whether SAP has already published an architecture for it. Each document explains the services involved, how data flows, and SAP's recommendations, and includes editable draw.io diagrams. These are the ones that matter for this portal:

Sub-patterns inside RA0029

Users

Browser / Joule

→HTTPS

SAP BTP subaccount

Identity Authentication

Authorization & Trust (XSUAA)

CAP backend

Cloud Foundry runtime

or Kyma runtime

HANA Cloud · Vector Engine

AI Core · Gen AI Hub

Destination service

→APIs

Outside BTP

SAP S/4HANA

LLM providers

How a request flows

1. The user signs in through Identity Authentication. XSUAA issues a token with their roles.
2. The CAP backend checks @requires and @restrict, then embeds the question.
3. A CQL similarity query on HANA Cloud finds the closest records or document chunks.
4. CAP sends the prompt plus those results to the Generative AI Hub, through the orchestration service if you want filtering and masking.
5. The answer goes back to the user. The Destination service reaches S/4HANA if the flow needs live business data.

0 of 14 checked

1. Scaffold the project

   terminalCopy

   cds init dispute-desk && cd dispute-desk
   npm add @cap-js/mcp @cap-js/agents
   npm add -D @cap-js/sqlite @cap-js/ai @huggingface/hub @huggingface/tokenizers onnxruntime-node

2. Model the domain, with an embedding

   db/schema.cdsCopy

   namespace dispute;
   using { cuid, managed } from '@sap/cds/common';
   
   /** A customer's objection to an invoice. Amounts are in EUR. */
   entity Disputes : cuid, managed {
     invoice    : String(20);
     customer   : String(80);
     amount     : Decimal(15,2);
     reason     : String(1000);
     status     : String enum { open; inReview; resolved; rejected } default 'open';
     resolution : String(1000);
     embedding  : Vector = vector_embedding(
                    'Reason: ' || reason, 'DOCUMENT', 'SAP_GXY.20250407') stored;
   }

   Add a few rows in db/data/dispute-Disputes.csv (leave out the embedding column).

3. Write a narrow service for the agent

   srv/dispute-service.cdsCopy

   using { dispute } from '../db/schema';
   
   /** Helps collections clerks triage and resolve invoice disputes. */
   @requires: 'authenticated-user'
   service DisputeService {
     @readonly
     entity Disputes as projection on dispute.Disputes excluding { embedding };
   
     /** Returns up to 5 past disputes whose reason is similar to the text. */
     function similar(text : String) returns array of Disputes;
   
     /** Marks a dispute resolved. A clerk must approve. */
     action resolve(ID : UUID, resolution : String) returns Disputes;
   }
   annotate DisputeService with @mcp @agent;
   annotate DisputeService.resolve with @agent.hitl;

4. Implement the handlers

   srv/dispute-service.jsCopy

   const cds = require('@sap/cds')
   
   module.exports = class DisputeService extends cds.ApplicationService { init() {
     const { Disputes } = cds.entities('dispute')
   
     this.on('similar', async req => {
       const { text } = req.data
       return SELECT.from(Disputes)
         .columns('ID', 'invoice', 'customer', 'reason', 'status', 'resolution')
         .where`cosine_similarity(embedding,
           vector_embedding(${text}, 'QUERY', 'SAP_GXY.20250407')) > 0.7`
         .limit(5)
     })
   
     this.on('resolve', async req => {
       const { ID, resolution } = req.data
       const n = await UPDATE(Disputes, ID).with({ status: 'resolved', resolution })
       if (!n) return req.reject(404, `Dispute ${ID} not found`)
       return SELECT.one.from(Disputes, ID)
     })
   
     return super.init()
   }}

5. Give the agent a persona and a skill

   srv/AGENTS.mdCopy

   ---
   name: dispute-desk
   version: 0.1.0
   description: Triages invoice disputes and proposes resolutions for clerks.
   ---
   You support collections clerks. For each dispute, look up similar past
   disputes first and base your proposal on how they were resolved.
   Never resolve a dispute without stating the invoice and amount.

   srv/skills/triage/SKILL.mdCopy

   ---
   name: triage
   description: Rank open disputes by amount and age.
   metadata:
     tags: [disputes, prioritisation]
     examples: ["Which disputes should I work on first?"]
   ---
   ## When to Use
   The user asks what to work on, or for an overview of open disputes.
   ## Instructions
   Query open disputes, sort by amount descending, then by createdAt.
   Return a short table: invoice, customer, amount, days open.

6. Run locally and test both protocols

   terminalCopy

   DEBUG=agents cds watch
   # MCP:  npx @modelcontextprotocol/inspector → http://localhost:4004/mcp/dispute
   # A2A:  http://localhost:4004/a2a/dispute/preview/

   Ask: "Customer Acme says invoice 9001 was double charged. What do we usually do?" The agent should call similar, then propose a resolution and stop at input-required before running resolve.

   Locally, llm.kind defaults to auto, which reuses your Claude Code or OpenCode setup.

7. Deploy to SAP BTP

   terminalCopy

   cds add hana,xsuaa,mta,approuter
   # bind an SAP AI Core instance (extended plan) in mta.yaml
   mbt build && cf deploy mta_archives/dispute-desk_1.0.0.mtar

   Set cds.requires.llm to { "kind": "aicore", "model": "…" } with a model from your AI Launchpad. On HANA, vector_embedding runs natively. Add audit logging and telemetry (3.6), then register the MCP endpoint in Joule Studio (3.8).

   Clients

   Collections clerk

   Joule Studio agent

   →MCP
   A2A

   SAP BTP · Cloud Foundry

   Dispute Desk (@mcp @agent)

   XSUAA

   HANA Cloud + vectors

   SAP AI Core

   Audit Log service

   Cloud Logging (telemetry)

   The finished lab on BTP. Use it as the architecture slide in your portfolio README.

   Editable SAP BTP diagram (L2 detailed view):Download .drawioOpen in diagrams.net

A2A

Agent-to-Agent protocol for handing tasks between agents, with states such as working, input-required and completed.

Agent card

A2A metadata (name, version, description, skills) that clients read to discover an agent. CAP fills it from AGENTS.md.

AI units

SAP's consumption currency for premium Business AI features.

CQL / CQN

CAP's query language (text) and its object form (JSON).

Embedding

A vector of numbers representing a text's meaning; similar meanings sit close together.

Grounding

Adding retrieved facts to the prompt so answers come from your data.

HITL

Human in the loop: a person approves a step before the agent continues.

MCP

Model Context Protocol: an open standard for exposing tools, resources and prompts to AI clients.

ReAct

Reason + Act loop: the model thinks, calls a tool, reads the result, and repeats.

Resource group

An isolation unit in SAP AI Core for deployments and secrets.

SAP Knowledge Graph

SAP-managed business ontology that helps Joule understand processes and relationships.

Skill (CAP)

A SKILL.md file with instructions for one subtask, loaded only when relevant.

Skill (Joule)

A deterministic Joule Studio flow that Joule or an agent can trigger.

Whiteboard in five boxes

Draw, left to right: user → Joule or a chat client → agent (Joule Studio or CAP @agent) → CAP service (MCP tools, auth, HITL) → HANA Cloud + S/4HANA. Draw SAP AI Core under the agent, and identity (IAS and XSUAA) across the top. Then talk through one request end to end.

Certifications to look at

• SAP Certified Associate – SAP Generative AI Developer: AI Core, the Generative AI Hub and the orchestration service.
• SAP Certified Associate – Back-End Developer – SAP Cloud Application Programming Model: the CAP foundation under Track 3.

Exam codes and content change every year or so. Check the current list on learning.sap.com/certifications. Most SAP Learning courses are free; certification exams are paid.