Tutorial · 2026

Extending SAP Joule: Custom Actions with Joule Studio (2026)

How to build custom Joule skills and agents in 2026: action steps on BTP destinations, the jl CLI, MCP tools, grounding, and what SAP has not documented yet.

advanced 12 min read Updated Nov 8, 2026

30-second summary

  • In 2026 there are two supported Joule-extension generations: the Classic Joule Studio skill canvas inside SAP Build, and the next-generation agent runtime driven by the `jl` CLI and npm package @sap/joule-studio-cli.
  • A 'custom action' in Joule is really a chain: a skill or agent asset, an action step wrapping an OData/REST API, a BTP destination for connectivity, and prompt/context wiring — SAP never shipped a single public 'action SDK'.
  • Everything SAP ships today is MCP-first: agents, MCP servers, and workflows are typed assets you validate, build, and deploy; governance (AI Agent Hub, audit under distinct agent identity) is built into the platform.
  • The managed runtime is free through December 2026, so the economics of piloting an extension right now are unusually good — but several integration seams remain 'not publicly documented as of 2026-11'.
Contents

Why “Joule Extensions” Became a Developer Search in 2026

For most of Joule’s life, “extending SAP’s copilot” meant waiting for SAP’s own roadmap. That changed. SAP Joule now has an official builder story, and people are searching for exactly what we were asked here: Joule extensions, custom actions, a Joule SDK. SAP’s October 2026 TechEd press release describes Joule Studio as “SAP’s AI-first development environment that is accessible through Joule Work for building and extending enterprise agents,” positioned inside the broader SAP Business AI Platform announcement — one platform to build, contextualize, and govern AI across SAP and third-party systems, with more than 70 models behind it.

We already covered the brand-level picture — how Joule and Microsoft 365 Copilot talk to each other on Azure in our SAP Joule + M365 Copilot integration guide. This article is the developer companion: what a custom action physically is, how the two generations of the tooling differ, where the public programmable surface actually lives (it is smaller than the marketing suggests), and where we had to write “not publicly documented as of 2026-11” because SAP simply hasn’t published it.

The Vocabulary Map: Skills, Actions, Tools, Agents — and the Missing “Plugin”

SAP’s public terminology across the Joule Studio product page, the Joule Studio help portal, and the AI Golden Path page on Joule Skills settles into five load-bearing concepts:

  • Joule skill (a.k.a. “Joule Scenario”) — the reusable unit that fulfills one user intent. Built from steps on a visual canvas: parameter definitions, action calls, conditions, response templates.
  • Action — the step that actually touches a system. In the classic path, actions come from SAP Build Action Projects wrapping OData or REST endpoints, executed through a destination (a named connection in the BTP cockpit).
  • Tool — anything an agent may invoke. SAP names four tool kinds on the custom AI agents page: skills, MCP servers, documents, and workflows, plus A2A connections for talking to external agents.
  • Agent — the orchestration layer above tools. SAP’s TechEd 2025 lab material frames it around four cognitive abilities: planning, reflection, tool usage, and collaboration, configured with Expertise, Instructions, and Additional Context prompt fields.
  • Context — grounding. Document Grounding is retrieval over your own files; platform-level grounding runs through the SAP Knowledge Graph and SAP Business Data Cloud per the TechEd release.

A word you will not find as a first-class object in any of these docs: plugin. SERP queries for “Joule plugin” are really asking for the MCP server or the Action Project. That naming gap matters when you search for answers — SAP’s vocabulary shifted twice in twelve months.

Two Generations of Joule Studio Are Shipping at Once

This is the fact that makes most older tutorials confusing. There are two generations of extension tooling, and they are not the same product wearing the same name:

  1. Joule Studio, Classic Edition — the low-code canvas that lives in SAP Build. Its Agent Builder went generally available with the Q4 2025 SAP Build release, announced as GA in SAP’s Q4 2025 release-highlights post (German-language; the Classic Edition documentation is English). Here you build Joule Scenarios and deploy them to a standalone test assistant or to the shared environment, where they appear inside the unified Joule across S/4HANA Cloud, SuccessFactors, and SAP Build Work Zone.
  2. The next-generation Joule Studio — the CLI-and-assets model. Everything is a solution containing typed assets (agents, MCP servers, workflows), validated, built, and deployed with the jl command; the TechEd 2026 pro-code lab states plainly that production agents “run in SAP AI Core, accessible via SAP Joule.”

The clearest proof both lines are live simultaneously sits in one npm package. registry.npmjs.org/@sap/joule-studio-cli (latest 2.0.4, first published 2026-02-03) installs two CLIs: joule, the legacy CLI to compile design-time artifacts, deploy digital assistants, and run YAML test scenarios; and jl, the new Joule Work CLI for solutions, agents, and MCP servers. Node 24 and libsecret on Linux are requirements in the README, which also carries a prominent security notice about credential handling — worth reading before you script this in CI. SAP has not published a migration path between the two generations — the tooling for moving Classic skills into the new asset model is not publicly documented as of 2026-11.

One commercial fact is worth pinning: design-time tooling is free under fair-use limits, and deploying/running custom agents on the SAP-managed runtime is free through December 2026, after which it becomes consumption-based. That makes an extension pilot essentially zero-cost if you start now.

The Skill Path: What a Custom Action Actually Contains

Strip the branding and a classic Joule skill is a small pipeline: recognize intent → map inputs → call an action → transform the response → answer. The developer tutorial group “Build Your First Joule Skill” and the Discovery Center mission on custom Joule skills both walk the same flow we reproduced with a transportation-management OData service in SAP’s TechEd 2025 lab material (SAP-samples/teched2025-AI163):

  1. Create a Joule Skill project in SAP Build; the canvas opens with one input parameter by default.
  2. Add a Call Action step and pick an action from a SAP Build Action Project — that project is where your OData/REST endpoints, authentication, and request/response shapes actually live.
  3. Attach a destination as an environment variable (Type: Destination). This is the same BTP destination you would use in any integration scenario — same trust config, same Cloud Connector path for on-premise backends.
  4. Derive inputs with the Formula Editor and map outputs down the response tree. Real expressions from the lab:
ConcatenateStrings(["delayStatus eq ", true, ""], "")
getReadquery > result > d > results        # output mapping path
  1. Define skill Input/Output parameters (json, Any, List types) and a response template — or let Joule generate the reply with Gen-AI Response Generation.
  2. Release, deploy to the standalone environment, test phrasings, then deploy to the shared environment for production Joule.

Three advanced rules from SAP’s Joule Development Guide deserve more attention than they get. Confirmations are mandatory for writes: any create/update/delete must use an Action Group confirmation step showing exactly what will change before it executes — SAP frames this as an AI-ethics prerequisite, not a nicety. Long calls must be async, per the Asynchronous API Requests doc, or the conversation times out. And when one skill isn’t enough, Scenario Dependencies chain skills — but SAP explicitly steers complex reasoning, state, and multi-tool orchestration toward agents instead. Skill types cluster into navigation, list/search, transaction, decision, and data-access — a useful checklist when you decompose a business process.

The Pro-Code Path: jl, Intent-Based Development, and MCP Servers

For engineers, the headline of 2026 is the CLI reference and its companion docs (pro-code setup, Create an agent with the CLI). The workflow from the package README:

npm install -g @sap/joule-studio-cli
jl login <joule-studio-url>
jl solution create --name my-solution
jl asset create agent --name my-agent
jl solution validate && jl solution build && jl solution deploy

The TechEd 2026 lab SAP-samples/teched2026-AD263 builds a supplier-disruption agent on S/4HANA and shows what “pro-code” means here: you pair jl with an AI coding agent (Claude Code or opencode in the lab; the product page also names VS Code, Cursor, and Cline) and drive Intent-Based Development: a plain-language intent becomes a PRD, then a technical specification, then implementation, then deploy. The tool layer is MCP-first — the lab’s IBD flow discovers the S/4HANA API from the SAP Knowledge Graph, downloads the EDMX spec, and generates a translation.json mapping OData endpoints to named MCP tools (e.g., a purchase-order MCP server over CE_PURCHASEORDER_0001). You don’t hand-write a plugin; you generate a typed MCP-server asset and let governance wrap it. The legacy half still ships too — joule compile, joule deploy, joule test for classic digital assistants:

joule --help   # legacy CLI: compile, deploy, test digital assistants
jl --help      # Joule Work CLI: solutions, agents, MCP servers

SAP’s claim that low-code and pro-code “both paths produce the same deployable artifact” is the one to verify in your own pilot, because it determines whether your business analysts and your engineers can work on one asset.

Where BTP Still Does the Heavy Lifting

Joule Studio does not retire the Business Technology Platform; it moves the plumbing behind a prettier facade. You still need: a BTP/global account with the right entitlements (the Golden Path page spells it out — an enterprise agreement such as CPEA or BTPEA, SAP Build entitlement plus developer license, and a Joule entitlement to deploy to production); destinations configured in the cockpit for every backend (we walked through the full plumbing, including Cloud Connector and the truststore traps, in our BTP destinations + Cloud Connector guide); and API substance to point actions at — OData services, CAP services, or ABAP CDS view exposure via ADS. Model inference and retrieval still land on AI-Core-family services if you use Document Grounding: the classic agent builder wires a destination variable to SAP AI Core with a resource-group and collection ID for your RAG corpus — the model catalog behind it is what we mapped in our SAP AI Core and Azure OpenAI model catalog tutorial, and the broader BTP-to-Azure wiring lives in our SAP BTP + Azure OpenAI integration guide. n8n workflow authoring inside Joule Studio is still an early-adopter program per the TechEd release, so treat workflow automation for now as a classic SAP Build Process Automation asset the agent triggers.

What Tripped Us Up

Two weeks of reading, and the thing that cost us the most time was toponym confusion, not technical difficulty. “Joule Studio” now labels the Classic Edition inside SAP Build, the next-generation environment at help.sap.com/docs/joule-studio, and an older assistant-orchestration service that used to live under the same name on BTP — and SAP’s documentation URLs split accordingly (Joule_Studio vs joule-studio vs the joule development guide). A 2024-2025 answer you find in a forum may describe a system that no longer exists, and community.sap.com threads return HTTP 403 to anonymous fetchers, so you often cannot even read the answer you found. Our rule that worked: identify the artifact, not the noun — is it a skill canvas (classic), a solution asset (jl), or an MCP server? Then find its specific help.sap.com slug. The moving-target problem is real enough that SAP’s own glossary churn is why we maintain the SAP Business AI and Joule terminology guide separately; re-verify naming every quarter.

The Public SDK Question: What Actually Exists

There is no single published “Joule SDK” that you pip install and call private APIs with. The public programmable surface, as of this writing, is exactly: the @sap/joule-studio-cli npm package (jl and joule binaries), the CLI reference and asset model docs, SAP Build Action Projects + destinations as the integration contract, MCP servers as the tool contract, and A2A plus the governed agent gateway for agent-to-agent interop announced at TechEd 2026, alongside the SAP–Nvidia co-defined agent execution layer. Governance is genuinely public: every deploy registers in SAP AI Agent Hub (included up to 500 agents), agent actions are logged under a distinct agent identity separate from user actions, scheduled post-deployment evaluations detect drift, and access control plus policy enforcement happen at the MCP layer. What is not publicly documented as of 2026-11: the REST endpoints the Joule runtime itself calls; any ABAP-side hook to inject custom actions into standard S/4HANA Joule without going through the shared-environment skill deployment; the classic-to-next-gen migration tooling; the AI-unit metering formula for custom agents once the free runtime window ends; and the internal solution-asset schema beyond what CLI flags and docs expose. If your architecture assumes one of those, plan a fallback.

What This Guide Does Not Cover

We do not go inside the Joule runtime for S/4HANA (the ABAP-managed plumbing SAP keeps internal), SuccessFactors-specific extension paths, or the EU AI Act paperwork the AI Governance Assistant automates. Model-provider selection strategy and Azure-side OpenAI provisioning belong to our other tutorials rather than being re-derived here. We also deliberately do not quote the “classic migration timeline” rumor circulating on community blogs — SAP has not published one, and repeating dates we cannot fetch from a primary source would be worse than silence. Roadmap claims are limited to what SAP has put on press releases, product pages, or public documentation as of 2026-11-08.

FAQ

Is there a public SDK for building custom Joule actions?

Not in the classic sense. What SAP publicly ships is the Joule Studio CLI (@sap/joule-studio-cli on npm, providing jl and the legacy joule), help.sap.com documentation for the asset model, SAP Build Action Projects as the API-wrapping contract, and MCP servers as the tool contract. A dedicated single-language SDK for embedding custom actions into the standard S/4HANA Joule surface is not publicly documented as of 2026-11 — the supported route is deploying skills/agents and letting the unified Joule discover them.

What is the difference between a skill, an agent, and an MCP server?

A skill (Joule Scenario) fulfills one recognizable intent through a fixed step flow and is usually the fastest to ship. An agent is the reasoning layer — it plans, reflects, and picks among tools. An MCP server is a tool package: named endpoints, schema-described, callable under policy at the MCP layer. SAP’s own guidance: use scenario dependencies for simple chaining, agents for complex reasoning or state, MCP servers to expose system capabilities to any of them.

Can third-party (non-SAP) systems be extended into Joule?

Yes, that is a first-class use case. The Golden Path page lists S/4HANA, SuccessFactors, Ariba and third-party systems reached via OData/REST through configured destinations; classic skills trigger SAP Build Process Automation flows; and with the governed agent gateway announced at TechEd 2026, external agents can securely invoke Joule agents over A2A with enforced access control. The connection contract is still a BTP destination — Cloud Connector included for on-premise.

Should we start on the classic edition or the next-generation flow?

For new builds, SAP’s product pages point to the next-generation flow: intent-based development, typed assets, jl CLI, SAP-managed runtime, free through December 2026. If your team already maintains classic skills, they remain GA and supported, and both paths produce deployables Joule Work can route to. The honest caveat: no public migration tooling exists yet, so if you expect to move hundreds of classic skills, pilot one conversion by hand first and document the gaps.

References

  1. SAP TechEd 2026 press release — AI for developers, autonomous execution — https://news.sap.com/2026/10/sap-teched-ai-developers-build-what-matters-autonomous-execution/ (accessed 2026-11-08)
  2. Joule Studio product page — https://www.sap.com/products/artificial-intelligence/joule-studio.html (accessed 2026-11-08)
  3. Build custom AI agents with Joule Studio — https://www.sap.com/products/artificial-intelligence/joule-studio/custom-ai-agents.html (accessed 2026-11-08)
  4. Joule Studio help portal — https://help.sap.com/docs/joule-studio (accessed 2026-11-08)
  5. Joule Studio CLI reference for pro-code development — https://help.sap.com/docs/joule-studio/joule-studio/joule-studio-for-cli-pro-code-development-in-joule-studio (accessed 2026-11-08)
  6. Pro-code setup guide — https://help.sap.com/docs/joule-studio/joule-studio/pro-code-setup?locale=en-US (accessed 2026-11-08)
  7. Create an agent with the CLI — https://help.sap.com/docs/joule-studio/joule-studio/create-agent-with-cli?locale=en-US (accessed 2026-11-08)
  8. Joule Studio, Classic Edition — Create AI Capabilities — https://help.sap.com/docs/joule-studio-classic/joule-studio-classic-edition/create-ai-capabilities?locale=en-US (accessed 2026-11-08)
  9. SAP Architecture Center, AI Golden Path: Joule Skills — https://architecture.learning.sap.com/docs/golden-path/ai-golden-path/build-and-deliver/joule-skills (accessed 2026-11-08)
  10. Developer tutorial group: Build Your First Joule Skill — https://developers.sap.com/group.joule-studio-first-skill.html (accessed 2026-11-08)
  11. Joule Development Guide: Action Group confirmations — https://help.sap.com/docs/joule/joule-development-guide-4b327297dce247fcb88a5f5bfeea97a1/action-group (accessed 2026-11-08)
  12. Joule Development Guide: Scenario Dependencies — https://help.sap.com/docs/joule/joule-development-guide-4b327297dce247fcb88a5f5bfeea97a1/scenario-dependencies (accessed 2026-11-08)
  13. Joule Development Guide: Asynchronous API Requests — https://help.sap.com/docs/joule/joule-development-guide-4b327297dce247fcb88a5f5bfeea97a1/asynchronous-api-requests (accessed 2026-11-08)
  14. Joule Development Guide: Gen-AI Response Generation — https://help.sap.com/docs/joule/joule-development-guide-4b327297dce247fcb88a5f5bfeea97a1/gen-ai-response-generation (accessed 2026-11-08)
  15. npm registry metadata for @sap/joule-studio-cli — https://registry.npmjs.org/@sap/joule-studio-cli (accessed 2026-11-08)
  16. SAP-samples/teched2026-AD263 pro-code agent lab — https://github.com/SAP-samples/teched2026-AD263 (accessed 2026-11-08)
  17. SAP-samples/teched2025-AI163 extend Joule and build AI agents — https://github.com/SAP-samples/teched2025-AI163 (accessed 2026-11-08)
  18. Q4 2025 release highlights, Joule Studio Agent Builder GA — https://news.sap.com/germany/2026/02/highlights-q4-2025-release-sap-business-ai-it-und-entwickler/ (accessed 2026-11-08)
  19. SAP and Nvidia agent execution layer — https://news.sap.com/2026/05/secure-ai-agents-how-sap-and-nvidia-co-define-enterprise-grade-agent-execution/ (accessed 2026-11-08)
  20. Joule Studio technical setup guide — https://help.sap.com/docs/Joule_Studio/45f9d2b8914b4f0ba731570ff9a85313/04b323352fa645238211ce017f634d34.html (accessed 2026-11-08)
  21. What is Joule Studio? (SAP Learning) — https://learning.sap.com/courses/sap-enterprise-architects/what-is-joule-studio_ee5e701c-2345-44d4-bb3d-60ccdc1bc4a7 (accessed 2026-11-08)
  22. Joule Studio certification, free exam voucher offer — https://learning.sap.com/joule-studio-certification (accessed 2026-11-08)
  23. Discovery Center mission: Build Custom Joule Skills — https://discovery-center.cloud.sap/missiondetail/4643/?tab=overview (accessed 2026-11-08)
  24. ABAP CDS exposure via ADS in Business Application Studio — https://help.sap.com/docs/business-application-studio/e7da250f86be4b88907c67f535abfbdf/1ad1fd31a03744039771dc4a29383994.html (accessed 2026-11-08)

Next steps

Start with the guided first skill, then reproduce the TechEd 2026 pro-code lab side by side to feel where the two generations meet — and browse the rest of our SAP AI category for the grounding, model-catalog, and identity pieces this article leans on.

All external links above returned HTTP 200 from our checker on 2026-11-08; community.sap.com threads were excluded because they return HTTP 403 to anonymous fetchers.