Datasphere and SAP Analytics Cloud for AI builders: Joule, Just Ask and analytic models as agent tools
Which AI features SAP Datasphere and SAP Analytics Cloud offer, which are base or premium, and how an agent reads an analytic model safely as the user.
Many companies already keep their cleaned, combined business numbers in SAP Datasphere and show them in SAP Analytics Cloud (SAC). Datasphere is where data teams model the numbers: which tables, which joins, what "margin" means, who may see which rows. SAC is where people read and plan on those numbers in dashboards called stories.
Both products now carry AI. Some of it helps the people who build the models: Joule answers how-to questions in Datasphere, and generated semantics label tables. Some helps the people who read the numbers: Just Ask answers a question typed in plain language, and Joule passes analytical questions to it from other SAP applications.
For AI builders, the bigger point is the reverse direction. A Datasphere analytic model is a governed, named set of measures and dimensions with access rules already attached. An agent that reads it through its API, as the person asking, gets the same numbers the finance team signed off. An agent that reads raw tables gets its own version of the truth.
One definition of each number. At Calder Pumpworks, our fictional pump maker, the controller and the sales team argued for a quarter about whether "margin" includes freight. The answer now lives in one analytic model. When an assistant answers "What was our ES-200 margin in September?", it should read that model, not recompute margin from billing documents.
Access rules you already paid for. Datasphere applies data access controls, so the inside sales rep for the US sees only the US sales organization. An agent that reads as the user inherits that rule. An agent with a broad technical login quietly breaks it.
Cost you can predict. SAP sorts its AI features into base AI, included in the product subscription, and premium AI, which consumes AI Units, a prepaid credit (SAP KBA 3741620). The same "ask a question" idea can be free in one place and metered in another, so a pilot that works may surprise the budget owner at scale.
The risk. A plain-language answer looks finished. If the model behind it is wrong, the access rules are loose, or two currencies get added together, the error reaches a decision with no warning. The guardrails matter more than the chat box.
Two notes on wording. First, SAP's own pages disagree on Joule in Datasphere: the release highlights call it generally available, while the product page still asks for AI Units and offers early adopter registration. Ask SAP which applies to your contract. Second, the SAP pages read for this topic describe generating story script logic and prompt insight widgets, not generating a whole story from one prompt. Treat any claim of full story generation as a question for SAP.
"Just Ask understands our data." It understands the models an administrator indexed and their names. A badly named or unapproved model gives confident wrong answers.
"All Joule features are free." The analytical insights scenario is in the Joule base entitlement. Joule in Datasphere and several SAC assistants consume AI Units, according to SAP's own pages.
"An agent can read the warehouse tables directly; it's faster." It skips the measure definitions and the access rules. You then have to rebuild both, and they drift.
"Zero rows means zero sales." It can also mean the user may not see that data. A good assistant says which.
"If it works in the demo, it scales." Premium features are metered per use, and the API has request limits.
Pick one answer for each question. The explanation appears after you choose.
1Why should a custom agent read a Datasphere analytic model instead of raw tables?
Answer: C. The analytic model is where "margin" and the other measures are defined once, with data access controls attached. Reading raw tables means rebuilding both, and the copies drift from what finance signed off.
2A budget owner asks whether "asking questions in plain language" costs extra. What is the accurate answer as of November 2026?
Answer: A. SAP's feature page puts Joule analytical insights in the Joule base entitlement, while its KBA lists SAC assistants such as AI-assisted calculations as premium AI that consumes AI Units. You check per feature.
3SAP's release highlights call Joule in Datasphere generally available, but the product page asks for AI Units and offers early adopter registration. What should a project lead do?
Answer: D. The topic shows the two SAP pages disagree. The safe move is to confirm the terms that apply to your own contract and keep that answer with the plan, rather than guessing which page is current.
4The US inside sales rep asks an assistant for German sales and gets no rows back. What should the assistant say?
Answer: C. A data access control hides rows the user may not see, so an empty result is not the same as zero. Reporting it as zero would be a confident wrong answer.
5What should a functional consultant add to their test plan when Just Ask goes live on a sales model?
Answer: C. Plain-language answers look finished, so the test is whether they match figures the business already trusts. That needs questions with known results, rerun when the model changes.
6Which claim about SAC story generation can you make from the SAP pages read for this topic?
Answer: A. The Q3 2026 release highlights describe script generation and explanation and prompt insight widgets. They don't describe generating a whole story from one prompt, so that claim needs confirming with SAP.
An analytic model is a contract; the consumption API is its front door; the user's token is the key.
The contract says which measures exist, how each aggregates, which dimensions you may slice by, and which rows each person may see. SAC stories, Just Ask and your own agent should all come through the same door with the asker's own key. Then three readers get the same number for the same question, and none of them sees more than its user may.
Everything else in this topic follows from that. The agent's language model only proposes which measures, dimensions and filters to ask for. Deterministic code checks the proposal against the model's published metadata, keeps currencies apart, caps the result, and tells the difference between "nothing" and "nothing you may see".
SAP's training describes an analytic model as sitting on a fact source (a fact view or another analytic model), with dimensions added from the underlying model and pruned by the modeler (SAP Learning). Its measures come in three kinds that matter to an agent:
Plain measures such as revenue or quantity, which aggregate (usually sum) along the dimensions you don't select.
Restricted measures, which apply a filter (for example, revenue for one product line) and can stack on other measures.
Calculated measures, which apply a formula after aggregation. Margin percent is the classic case: the right figure is total margin over total revenue, never the sum or average of row percentages.
Filters apply before aggregation, and variables (standard, filter, restriction and reference date) let the caller supply values at query time. Models can be shared to other spaces and reused.
Data access controls sit on the data, not in the front end. When a user reads through SAC or the API, Datasphere returns only the rows that user may see.
Datasphere exposes models over OData. An SAP employee's overview gives two URL patterns (SAP Community):
<host>/api/v1/dwc/consumption/relational/<space>/<view>/<view> rows, no aggregation
<host>/api/v1/dwc/consumption/analytical/<space>/<model>/<model> aggregated by $select
Each service also publishes a $metadata document that lists the fields. The analytical service behaves differently from a database view in three ways an agent builder must know:
Aggregation follows $select. Ask for Product,NetRevenue and you get one row per product. There is no $apply; SAP's KBA says analytic model APIs don't currently support it and points customers to an enhancement request (SAP KBA 3746273). A view exposed for consumption does support $apply group-by.
The caller is a named user. The same overview describes consumption through an OAuth client with the purpose Interactive Usage and the authorization code flow: a person signs in, and their data access applies. The REST administration API, by contrast, uses client credentials. SAP's KBA 3718383 adds that a Technical Usage client purpose has been supported since late 2025 for OAuth clients used by SAP Analytics Cloud, with a technical user holding scoped roles. Check your tenant's current documentation before you design a technical-user flow for data reads, and remember that a technical user sees what its roles allow, not what the asker may see.
There are limits. The overview gives 300 OData requests per user per minute and pages of 50,000 records by default; these figures come from that community post, so confirm them for your tenant. Very wide $select lists can fail with HTTP 400 because the result grows too large; SAP's guidance is to select fewer fields or filter harder (SAP KBA 3712253).
#How Just Ask answers, and where your agent differs
SAP's reference architecture for Joule analytical insights (last updated 12 May 2026; SAP now marks the page as archived, so check the flow against current documentation) describes this path (SAP Architecture Center):
sequenceDiagram
participant U as User in an SAP app
participant J as Joule
participant D as BTP destination
participant A as Just Ask (SAC)
participant M as Model (Datasphere or SAC)
U->>J: "ES-200 margin in September?"
J->>D: forward, user signed in via Cloud Identity Services
D->>A: SAML bearer assertion, swapped for a user token
A->>A: semantic search over model metadata
A->>M: LLM-generated OData or SQL query, as the user
M-->>A: rows the user may see
A-->>J: table, chart or narrative
Your own agent follows the same shape with different parts: your identity provider and BTP destination carry the user, your code picks the model (often there is only one per tool), and your code, not a language model, builds the final query string.
You will build two small programs. calder_analytic_api.py is a course mock of a Datasphere analytical consumption API: it publishes a catalog, a $metadata document and a data endpoint that aggregates by $select under each user's data access. analytic_model_tool.py is the agent tool: the part a language model would call. You will see the same question answered differently for three users, and watch the tool refuse unsafe requests. The mock is not SAP software and real Datasphere responses carry more detail; the shape and the rules are what you take away.
flowchart LR
Q[agent's proposal:<br/>dims, measures, filters] --> T[analytic_model_tool.py<br/>checks and builds the query]
T -->|Bearer token of the user| API[calder_analytic_api.py<br/>course mock on 127.0.0.1:8772]
API --> M[(AM_SALES_MARGIN<br/>data access by sales org)]
T --> R[rows + notes + source]
The data is fictional Calder Pumpworks course data for September 2026, not from an SAP system:
Sales org
Company code
Customer
Product
Qty
Revenue
Cost of sales
CPUS
CP10
10000001 Brennock Water Utility
ES-200
8
33,600.00 USD
13,984.00 USD
CPUS
CP10
10000002 Hallam Fluid Systems
ES-200
4
14,220.00 USD
6,992.00 USD
CPUS
CP10
10000001 Brennock Water Utility
ES-300
2
12,300.00 USD
4,376.00 USD
CPUS
CP10
10000002 Hallam Fluid Systems
CP-SK200
120
11,400.00 USD
5,760.00 USD
CPUS
CP10
10000021 Ostervale Municipal Water
ES-200
2
8,800.00 USD
3,496.00 USD
CPDE
CP20
10000004 Brenzhof Pumpentechnik GmbH
CP-IMP200
10
4,100.00 EUR
3,100.00 EUR
CPDE
CP20
10000008 Ostmark Filtertechnik GmbH
CP-CAST300
3
1,770.00 EUR
1,440.00 EUR
The users, as in the lakehouse topic: 00100266 inside sales rep may read CPUS; 00100280 group controller may read CPUS and CPDE; 00100153 maintenance planner has no sales access. The space CALDER_SALES, the model AM_SALES_MARGIN and its field names are course labels.
Create a file unit07/calder_analytic_api.py in your editor and paste this code:
"""A local stand-in for SAP Datasphere's analytical consumption API.
Course mock, not SAP software. It copies the shape that matters for an
agent: a catalog, a $metadata document, and a data endpoint that
aggregates by the dimensions in $select, under the caller's own data
access. Space, model, field names and values are course labels.
Run: python unit07/calder_analytic_api.py
"""
import json
import secrets
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, urlparse
HOST, PORT = "127.0.0.1", 8772
SPACE, MODEL = "CALDER_SALES", "AM_SALES_MARGIN"
BASE = f"/api/v1/dwc/consumption/analytical/{SPACE}/{MODEL}"
DIMENSIONS = ["SalesOrganization", "CompanyCode", "Customer", "CustomerName",
"Product", "CalendarMonth", "Currency"]
MEASURES = ["Quantity", "NetRevenue", "CostOfSales", "Margin", "MarginPct"]
# Course sample: September 2026 billed sales lines (fictional, Calder Pumpworks).
# (SalesOrg, CompanyCode, Customer, Name, Product, Month, Currency, Qty, Revenue, Cost)
FACTS = [
("CPUS", "CP10", "10000001", "Brennock Water Utility", "ES-200", "2026-09", "USD", 8, 33600.00, 13984.00),
("CPUS", "CP10", "10000002", "Hallam Fluid Systems", "ES-200", "2026-09", "USD", 4, 14220.00, 6992.00),
("CPUS", "CP10", "10000001", "Brennock Water Utility", "ES-300", "2026-09", "USD", 2, 12300.00, 4376.00),
("CPUS", "CP10", "10000002", "Hallam Fluid Systems", "CP-SK200", "2026-09", "USD", 120, 11400.00, 5760.00),
("CPUS", "CP10", "10000021", "Ostervale Municipal Water", "ES-200", "2026-09", "USD", 2, 8800.00, 3496.00),
("CPDE", "CP20", "10000004", "Brenzhof Pumpentechnik GmbH", "CP-IMP200", "2026-09", "EUR", 10, 4100.00, 3100.00),
("CPDE", "CP20", "10000008", "Ostmark Filtertechnik GmbH", "CP-CAST300", "2026-09", "EUR", 3, 1770.00, 1440.00),
]
# Data access control: which sales organizations each user may see.
ACCESS = {
"00100266": {"CPUS"}, # inside sales rep
"00100280": {"CPUS", "CPDE"}, # group controller
"00100153": set(), # planner, no sales access
}
RATE_LIMIT = 300 # requests per user per rolling minute
_codes, _tokens, _calls = {}, {}, {}
_lock = threading.Lock()
def metadata_xml():
props = []
for d in DIMENSIONS:
props.append(f'<Property Name="{d}" Type="Edm.String"><Annotation Term="Course.Role" String="dimension"/></Property>')
for m in MEASURES:
props.append(f'<Property Name="{m}" Type="Edm.Decimal"><Annotation Term="Course.Role" String="measure"/></Property>')
return ('<?xml version="1.0" encoding="utf-8"?>'
'<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">'
'<edmx:DataServices><Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Course">'
f'<EntityType Name="{MODEL}Type">' + "".join(props) + '</EntityType>'
'</Schema></edmx:DataServices></edmx:Edmx>')
def parse_filter(text):
"""Accepts only: Field eq 'value' [and Field eq 'value' ...]."""
conditions = []
if not text:
return conditions
for part in text.split(" and "):
bits = part.strip().split(" eq ", 1)
if len(bits) != 2 or bits[0] not in DIMENSIONS:
raise ValueError(f"unsupported filter: {part.strip()}")
value = bits[1].strip()
if not (value.startswith("'") and value.endswith("'")):
raise ValueError(f"filter value must be quoted: {part.strip()}")
conditions.append((bits[0], value[1:-1]))
return conditions
def aggregate(user, select, conditions):
dims = [f for f in select if f in DIMENSIONS]
meas = [f for f in select if f in MEASURES]
groups = {}
for row in FACTS:
rec = dict(zip(DIMENSIONS, row[:7]))
if rec["SalesOrganization"] not in ACCESS.get(user, set()):
continue # data access control: rows outside the user's scope don't exist for them
if any(rec[f] != v for f, v in conditions):
continue # filters apply before aggregation
key = tuple(rec[d] for d in dims)
g = groups.setdefault(key, {"Quantity": 0, "NetRevenue": 0.0, "CostOfSales": 0.0})
g["Quantity"] += row[7]
g["NetRevenue"] += row[8]
g["CostOfSales"] += row[9]
out = []
for key in sorted(groups):
g = groups[key]
g["Margin"] = g["NetRevenue"] - g["CostOfSales"]
# A calculated measure is computed after aggregation, never summed.
g["MarginPct"] = round(100 * g["Margin"] / g["NetRevenue"], 2) if g["NetRevenue"] else None
rec = dict(zip(dims, key))
for m in meas:
rec[m] = round(g[m], 2) if isinstance(g[m], float) else g[m]
out.append(rec)
return out
class Handler(BaseHTTPRequestHandler):
def log_message(self, *args):
pass
def send(self, status, body, ctype="application/json"):
data = body.encode() if isinstance(body, str) else json.dumps(body).encode()
self.send_response(status)
self.send_header("Content-Type", ctype)
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def error(self, status, message):
self.send(status, {"error": {"code": str(status), "message": message}})
def user(self):
auth = self.headers.get("Authorization", "")
if not auth.startswith("Bearer "):
return None
with _lock:
entry = _tokens.get(auth[7:])
if not entry or entry[1] < time.time():
return None
return entry[0]
def do_GET(self):
url = urlparse(self.path)
query = parse_qs(url.query)
if url.path == "/oauth/authorize":
# Stands in for the browser login at the identity provider.
user = query.get("login_hint", [""])[0]
if user not in ACCESS:
return self.error(401, "unknown user")
code = secrets.token_hex(8)
with _lock:
_codes[code] = user
return self.send(200, {"code": code})
user = self.user()
if user is None:
return self.error(401, "missing or expired token")
with _lock:
now = time.time()
recent = [t for t in _calls.get(user, []) if now - t < 60]
recent.append(now)
_calls[user] = recent
if len(recent) > RATE_LIMIT:
return self.error(429, "too many requests")
if url.path == f"/api/v1/dwc/catalog/spaces('{SPACE}')/assets":
return self.send(200, {"value": [{
"name": MODEL, "label": "Sales margin by customer and product (course model)",
"analyticalUrl": f"{BASE}/{MODEL}", "metadataUrl": f"{BASE}/$metadata"}]})
if url.path == f"{BASE}/$metadata":
return self.send(200, metadata_xml(), "application/xml")
if url.path == f"{BASE}/{MODEL}":
if "$apply" in query:
return self.error(400, "$apply is not supported on analytic models; aggregation follows $select")
select = [f.strip() for f in query.get("$select", [""])[0].split(",") if f.strip()]
unknown = [f for f in select if f not in DIMENSIONS + MEASURES]
if not select or unknown:
return self.error(400, f"invalid $select: {unknown or 'empty'}")
try:
conditions = parse_filter(query.get("$filter", [""])[0])
top = int(query.get("$top", ["50000"])[0])
skip = int(query.get("$skip", ["0"])[0])
except ValueError as exc:
return self.error(400, str(exc))
rows = aggregate(user, select, conditions)
return self.send(200, {"value": rows[skip:skip + top]})
return self.error(404, "not found")
def do_POST(self):
if urlparse(self.path).path != "/oauth/token":
return self.error(404, "not found")
length = int(self.headers.get("Content-Length", 0))
form = parse_qs(self.rfile.read(length).decode())
if form.get("grant_type", [""])[0] != "authorization_code":
return self.error(400, "only authorization_code is accepted: the API reads data as a named user")
with _lock:
user = _codes.pop(form.get("code", [""])[0], None)
if user is None:
return self.error(400, "invalid code")
token = secrets.token_hex(16)
with _lock:
_tokens[token] = (user, time.time() + 900)
return self.send(200, {"access_token": token, "token_type": "bearer", "expires_in": 900})
def start(background=False):
server = ThreadingHTTPServer((HOST, PORT), Handler)
if background:
threading.Thread(target=server.serve_forever, daemon=True).start()
return server
print(f"Course analytic API on http://{HOST}:{PORT} (Ctrl+C to stop)")
try:
server.serve_forever()
except KeyboardInterrupt:
pass
if __name__ == "__main__":
start()
Create unit07/analytic_model_tool.py and paste this code:
"""An agent tool that reads a Datasphere-style analytic model as the user.
The model (LLM) only proposes dimensions, measures and filters. This code
decides: names must exist in $metadata, filter values must be plain codes,
money is never totalled across currencies, results are capped, and an
empty answer is reported as "nothing visible", never as zero.
Run: python unit07/analytic_model_tool.py demo
python unit07/analytic_model_tool.py ask --user 00100280 --dims Product --measures NetRevenue,Margin
"""
import argparse
import json
import re
import sys
import xml.etree.ElementTree as ET
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
import calder_analytic_api as api
BASE_URL = f"http://{api.HOST}:{api.PORT}"
EDM = "{http://docs.oasis-open.org/odata/ns/edm}"
MONEY = {"NetRevenue", "CostOfSales", "Margin"}
CODE = re.compile(r"^[A-Za-z0-9-]{1,20}$")
class ToolRefused(Exception):
"""The request was refused by the tool before reaching the API."""
def http(method, url, token=None, data=None):
headers = {"Accept": "application/json"}
if token:
headers["Authorization"] = f"Bearer {token}"
body = urlencode(data).encode() if data else None
try:
with urlopen(Request(url, data=body, headers=headers, method=method), timeout=5) as resp:
return resp.status, resp.read().decode()
except HTTPError as err:
return err.code, err.read().decode()
def login(user):
"""Course stand-in for the browser login (OAuth 2.0 authorization code)."""
status, body = http("GET", f"{BASE_URL}/oauth/authorize?login_hint={user}")
if status != 200:
raise SystemExit(f"Login failed for {user}: {body}")
code = json.loads(body)["code"]
status, body = http("POST", f"{BASE_URL}/oauth/token",
data={"grant_type": "authorization_code", "code": code})
return json.loads(body)["access_token"]
class AnalyticModelTool:
def __init__(self, token, user_label, space=api.SPACE, model=api.MODEL):
self.token, self.user = token, user_label
self.path = f"/api/v1/dwc/consumption/analytical/{space}/{model}"
self.model = model
self.schema = self.describe()
def describe(self):
status, body = http("GET", f"{BASE_URL}{self.path}/$metadata", self.token)
if status != 200:
raise SystemExit(f"Could not read $metadata ({status}): {body}")
dims, meas = [], []
for prop in ET.fromstring(body).iter(f"{EDM}Property"):
role = prop.find(f"{EDM}Annotation").get("String")
(dims if role == "dimension" else meas).append(prop.get("Name"))
return {"dimensions": dims, "measures": meas}
def query(self, dimensions, measures, filters=None, max_rows=20):
filters = filters or {}
notes = []
bad = [d for d in dimensions if d not in self.schema["dimensions"]]
bad += [m for m in measures if m not in self.schema["measures"]]
bad += [f for f in filters if f not in self.schema["dimensions"]]
if bad:
raise ToolRefused(f"not in the model: {', '.join(bad)}")
if not measures:
raise ToolRefused("ask for at least one measure")
for field, value in filters.items():
if not CODE.match(value):
raise ToolRefused(f"filter value for {field} is not a plain code")
dimensions = list(dimensions)
if MONEY & set(measures) and "Currency" not in dimensions:
dimensions.append("Currency")
notes.append("Currency added so amounts in different currencies are never added up")
params = {"$select": ",".join(dimensions + list(measures)), "$top": str(max_rows + 1)}
if filters:
params["$filter"] = " and ".join(f"{f} eq '{v}'" for f, v in filters.items())
url = f"{self.path}/{self.model}?{urlencode(params)}"
status, body = http("GET", BASE_URL + url, self.token)
if status != 200:
return {"status": "error", "http": status, "detail": body, "request": url}
rows = json.loads(body)["value"]
truncated = len(rows) > max_rows
result = {"status": "ok", "rows": rows[:max_rows], "truncated": truncated,
"notes": notes, "source": {"model": self.model, "request": url, "as_user": self.user}}
if not rows:
result["status"] = "no_rows_visible"
result["notes"].append("No rows are visible to this user for this request. Do not report this as zero.")
if truncated:
result["notes"].append(f"More than {max_rows} rows: narrow the question before answering.")
return result
DEMO = [
("D1 Margin by product, inside sales rep", "00100266", ["Product"], ["NetRevenue", "Margin", "MarginPct"], {}),
("D2 Same question, group controller", "00100280", ["Product"], ["NetRevenue", "Margin", "MarginPct"], {}),
("D3 Same question, planner", "00100153", ["Product"], ["NetRevenue", "Margin"], {}),
("D4 Margin % for ES-200 by customer", "00100266", ["CustomerName"], ["MarginPct"], {"Product": "ES-200"}),
("D5 Field the model doesn't have", "00100280", ["Employee"], ["Salary"], {}),
("D6 Filter value carrying an injection", "00100266", ["Customer"], ["Margin"], {"Product": "ES-200' or 'x' eq 'x"}),
]
def show(title, call):
print(f"\n== {title}")
try:
result = call()
except ToolRefused as exc:
print(f"status: refused ({exc})")
return
print(f"status: {result['status']}")
for row in result.get("rows", []):
print(" " + json.dumps(row))
for note in result.get("notes", []):
print(f" note: {note}")
if result["status"] == "error":
print(f" http {result['http']}: {result['detail']}")
if "source" in result:
print(f" source: {result['source']['model']} as {result['source']['as_user']}")
def main():
parser = argparse.ArgumentParser(description="Read a course analytic model as a named user")
sub = parser.add_subparsers(dest="cmd", required=True)
sub.add_parser("demo", help="run the six demo requests")
sub.add_parser("test", help="check the tool's guarantees")
ask = sub.add_parser("ask", help="run one request")
ask.add_argument("--user", required=True)
ask.add_argument("--dims", default="")
ask.add_argument("--measures", required=True)
ask.add_argument("--filter", action="append", default=[], help="Field=Value, repeatable")
ask.add_argument("--max-rows", type=int, default=20)
args = parser.parse_args()
server = api.start(background=True)
tools = {}
def tool_for(user):
if user not in tools:
tools[user] = AnalyticModelTool(login(user), user)
return tools[user]
if args.cmd == "demo":
print("Model fields:", json.dumps(tool_for("00100280").schema))
for title, user, dims, meas, flt in DEMO:
show(f"{title} ({user})", lambda: tool_for(user).query(dims, meas, flt))
elif args.cmd == "test":
rep, ctl, plan = tool_for("00100266"), tool_for("00100280"), tool_for("00100153")
checks = []
r = rep.query(["Product"], ["NetRevenue"])
checks.append(("rep sees USD only", {x["Currency"] for x in r["rows"]} == {"USD"}))
r = ctl.query(["Product"], ["NetRevenue"])
checks.append(("controller sees USD and EUR apart", {x["Currency"] for x in r["rows"]} == {"USD", "EUR"}))
checks.append(("planner gets no rows, not zero", plan.query(["Product"], ["Margin"])["status"] == "no_rows_visible"))
def refused(dims, meas, flt):
try:
rep.query(dims, meas, flt)
return False
except ToolRefused:
return True
checks.append(("refuses a field the model doesn't have", refused(["Employee"], ["Salary"], {})))
checks.append(("refuses a quoted filter value", refused(["Product"], ["Margin"], {"Product": "x' or 'a' eq 'a"})))
status, _ = http("GET", f"{BASE_URL}{rep.path}/{rep.model}?$apply=groupby((Product))", rep.token)
checks.append(("API rejects $apply", status == 400))
for name, ok in checks:
print(f"{'OK ' if ok else 'FAIL'} {name}")
server.shutdown()
return 0 if all(ok for _, ok in checks) else 1
else:
dims = [d for d in args.dims.split(",") if d]
meas = [m for m in args.measures.split(",") if m]
flt = dict(f.split("=", 1) for f in args.filter)
show(f"ask ({args.user})", lambda: tool_for(args.user).query(dims, meas, flt, args.max_rows))
server.shutdown()
if __name__ == "__main__":
sys.exit(main())
Save the file. Both files must sit in the same unit07 folder, because the tool imports the mock.
The tool starts the mock in the background, signs in each user, and runs six requests. You should see:
Model fields: {"dimensions": ["SalesOrganization", "CompanyCode", "Customer", "CustomerName", "Product", "CalendarMonth", "Currency"], "measures": ["Quantity", "NetRevenue", "CostOfSales", "Margin", "MarginPct"]}
== D1 Margin by product, inside sales rep (00100266)
status: ok
{"Product": "CP-SK200", "Currency": "USD", "NetRevenue": 11400.0, "Margin": 5640.0, "MarginPct": 49.47}
{"Product": "ES-200", "Currency": "USD", "NetRevenue": 56620.0, "Margin": 32148.0, "MarginPct": 56.78}
{"Product": "ES-300", "Currency": "USD", "NetRevenue": 12300.0, "Margin": 7924.0, "MarginPct": 64.42}
note: Currency added so amounts in different currencies are never added up
source: AM_SALES_MARGIN as 00100266
== D2 Same question, group controller (00100280)
status: ok
{"Product": "CP-CAST300", "Currency": "EUR", "NetRevenue": 1770.0, "Margin": 330.0, "MarginPct": 18.64}
{"Product": "CP-IMP200", "Currency": "EUR", "NetRevenue": 4100.0, "Margin": 1000.0, "MarginPct": 24.39}
{"Product": "CP-SK200", "Currency": "USD", "NetRevenue": 11400.0, "Margin": 5640.0, "MarginPct": 49.47}
{"Product": "ES-200", "Currency": "USD", "NetRevenue": 56620.0, "Margin": 32148.0, "MarginPct": 56.78}
{"Product": "ES-300", "Currency": "USD", "NetRevenue": 12300.0, "Margin": 7924.0, "MarginPct": 64.42}
note: Currency added so amounts in different currencies are never added up
source: AM_SALES_MARGIN as 00100280
== D3 Same question, planner (00100153)
status: no_rows_visible
note: Currency added so amounts in different currencies are never added up
note: No rows are visible to this user for this request. Do not report this as zero.
source: AM_SALES_MARGIN as 00100153
== D4 Margin % for ES-200 by customer (00100266)
status: ok
{"CustomerName": "Brennock Water Utility", "MarginPct": 58.38}
{"CustomerName": "Hallam Fluid Systems", "MarginPct": 50.83}
{"CustomerName": "Ostervale Municipal Water", "MarginPct": 60.27}
source: AM_SALES_MARGIN as 00100266
== D5 Field the model doesn't have (00100280)
status: refused (not in the model: Employee, Salary)
== D6 Filter value carrying an injection (00100266)
status: refused (filter value for Product is not a plain code)
Read the results against the mental model:
D1 and D2 asked the same thing. The controller sees two more rows, in EUR, kept apart from the USD rows. Nobody added 4,100 EUR to 56,620 USD.
D3 is not "zero sales". The planner may not see sales data, and the tool says so.
D4 shows margin percent for ES-200 computed after aggregation for each customer. The ES-200 total is 56.78%, which is not the average of the three customer figures (56.49%).
D5 and D6 never reached the API. The tool refused them.
== ask (00100266)
status: ok
{"CalendarMonth": "2026-09", "Currency": "USD", "Margin": 7228.0}
note: Currency added so amounts in different currencies are never added up
source: AM_SALES_MARGIN as 00100266
OK rep sees USD only
OK controller sees USD and EUR apart
OK planner gets no rows, not zero
OK refuses a field the model doesn't have
OK refuses a quoted filter value
OK API rejects $apply
Save your work with Git:
git add unit07/calder_analytic_api.py unit07/analytic_model_tool.py
git commit -m "Unit 7: agent tool over a Datasphere-style analytic model"
The course sales lines and which sales organizations each user may read
/oauth/authorize, /oauth/token (mock)
Stand in for a browser sign-in; only the authorization code grant returns a token, valid 15 minutes
metadata_xml() (mock)
Publishes the field list as a small OData $metadata document; a course annotation marks each field as dimension or measure
aggregate() (mock)
Drops rows outside the user's access, applies filters, groups by the selected dimensions, then computes Margin and MarginPct after aggregation
$apply check and RATE_LIMIT (mock)
Refuse $apply and more than 300 calls a minute per user, as the How it works section describes
login() (tool)
Gets a code for a user and swaps it for a token; in real life the user signs in at your identity provider
describe() (tool)
Reads $metadata once and keeps the allowed dimension and measure names
query() (tool)
Checks names and filter values, adds Currency to money questions, builds $select, $filter and $top, calls the API and returns rows, notes and the source
ToolRefused (tool)
Stops a bad request before it reaches the API, with a reason the model can act on
demo, ask, test (tool)
The six demo requests, one request from the command line, and the self-test
On a real tenant the same tool needs three changes, all sketches until you have access:
An OAuth client in Datasphere. SAP's overview creates it under System, Administration, App Integration with the purpose Interactive Usage and a redirect URI (SAP Community). Your agent's front end signs the user in; the tool receives that user's token. Keep the client secret in your secret store, never in code.
The real host and names. Replace BASE_URL, the space and the model with your tenant's. Read $metadata and map the real annotations to dimension and measure, instead of the course annotation.
Variables and wide models. If your model uses variables, check how your release passes them over OData; an older SAP post listed analytic models with variables as not yet supported, so test it. Keep $select narrow to stay under result-size limits.
For the tool interface itself, wrap query() as a tool in your agent framework or behind an MCP server, as in the Model Context Protocol topic, and route the agent's model and tool traffic through a gateway as in the AI gateways topic.
For business users, the SAP path is Just Ask, reached from Joule in other SAP applications. SAP's feature page states that an administrator controls which models and data Joule can use, that any user with an SAC account can use it once enabled, and that it is part of the Joule base entitlement on top of an SAC or Business Data Cloud subscription (SAP). SAP's release highlights describe questions over SAC acquired models or Datasphere models, with responses under SAP's access controls (SAP). The natural-language query topic covers the administrator's side (indexing, synonyms and rules) and why plain-language answers go silently wrong.
Joule in Datasphere helps modelers: how-to answers with documentation references, details about the tenant and tasks run from the conversation (SAP). SAP's Q1 2026 highlights call it generally available; the product page says AI Units are required.
Semantic generation proposes semantics for non-SAP tables and views, which is exactly what an analytic model needs before an agent can trust it (SAP). Review its suggestions like any other model change.
SAP's KBA lists AI-assisted calculations, chart summary, commenting and data actions as premium AI. Activation needs AI Units, a data center that supports SAP Business AI and a support case on component LOD-ANA-GAI (SAP KBA 3741620). The same KBA lists AI-assisted story code generation and AI-assisted prompt insights as base AI from Q3 2026: no AI Units, but you accept SAP's base AI terms and request activation through a support case.
SAP's tiers, as of November 2026: base AI is included in the subscription; premium AI consumes AI Units (SAP KBA 3741620). The consumption API itself is part of Datasphere; your agent's own model calls are a separate cost, covered in the pricing custom agents page. Confirm every feature's tier and rate in your contract.
Where it sits. Calder's reporting architecture puts group reporting on Datasphere in Business Data Cloud, with CP10 data arriving by CDS extraction and CP20 by SLT until the July 2027 rollout. The analytic model sits on that layer; SAC and agents read it.
flowchart LR
S4[S/4HANA CP10] -->|CDS extraction| DS
ECC[ECC CP20] -->|SLT| DS
subgraph BDC[Business Data Cloud]
DS[Datasphere space<br/>analytic model + data access control]
end
DS --> SAC[SAC stories and Just Ask]
SAC --> J[Joule in SAP apps]
IDP[Identity provider] -.user token.-> AG
AG[Agent on BTP<br/>analytic model tool] -->|consumption API as user| DS
Non-functional requirements.
Requirement
Typical target
What breaks if missed
Identity
Every data read carries the asking user
Agents show rows the user may not see
Freshness
Stated per model (for example, extraction every hour)
Agent quotes yesterday's figure as today's
Latency
Under 2 to 3 seconds per tool call
Chat feels broken; users retry and burn requests
Request volume
Below the per-user limit (300 a minute in SAP's overview)
HTTP 429s in busy periods
Result size
Tens of rows per tool call
Token cost, truncation, HTTP 400 on wide selections
Cost
Known AI Unit rate per premium feature
Pilot works, rollout surprises the budget
Integration and identity. Data flows by extraction into Datasphere, then out only through SAC or the consumption API. Identity flows from the identity provider: Just Ask uses principal propagation with a SAML bearer assertion, per SAP's archived reference architecture; a custom agent uses the authorization code flow with the Interactive Usage OAuth client. The grounding topic covers principal propagation in depth.
The decision to record. In the short ADR form from the design-doc topic:
Context: Calder's order exception agent must quote customer margin. Margin is defined in AM_SALES_MARGIN; access is by sales organization.
Options: A, read the analytic model through the consumption API as the user; B, a Datasphere database user reading views with SQL; C, call Just Ask from the agent; D, compute margin from S/4HANA billing APIs.
Decision: A. It reuses the agreed definition and the data access controls with the user's identity.
Consequences: The agent needs a signed-in user (no unattended night runs without a separate design); variables and request limits need testing; definition changes in the model change the agent's answers, so its test questions rerun with every model transport.
What a design review will ask.
Show a request where the user may not see the data. What does the agent say?
Who owns the measure definitions, and how does a change reach the agent's tests?
What happens when the agent runs without a user, for example on a schedule?
How are currencies and company codes kept apart in every answer?
Which features in this design consume AI Units, and at what volume?
Authorizations. Read as the user. If a process must run unattended, design a separate, narrow model and identity for it and record the decision; don't reuse a broad technical login for interactive questions.
Data access controls first. Test them with the same users the agent will serve, including someone with no access.
Evaluation. Keep a set of questions with known answers per model (Calder's September ES-200 margin, 32,148.00 USD in the course data). Rerun on every model transport and every prompt change.
Cost. Count tool calls per question and premium AI features per user. Log AI Unit consumption where SAP shows it.
Operations. Log each tool call with user, model, request and row count, not the data itself. Alert on 401, 429 and 400 rates.
Clean core. The model lives in Datasphere, not in S/4HANA; the agent reads released interfaces only. Nothing here modifies the ERP.
Extend the lab for Calder's Augsburg team. The output feeds Unit 9, where agents call tools like this one.
In calder_analytic_api.py, add user 00200045 (Augsburg sales clerk) to ACCESS with {"CPDE"}.
In analytic_model_tool.py, add a check to test that 00200045 sees only EUR rows and exactly two products.
Add a guard to query() that refuses a SalesOrganization filter whose value isn't CPUS or CPDE, with a reason the model can act on.
Run python unit07/analytic_model_tool.py test and the ask command for 00200045 with --dims Product --measures NetRevenue,MarginPct.
Write three test questions with known answers from the course data in a file unit07/analytic_questions.md: question, user, expected rows.
Commit your changes.
Done whentest prints OK for every line including the new 00200045 check, the ask command shows CP-CAST300 and CP-IMP200 in EUR for 00200045, and analytic_questions.md holds three questions with expected results.
Pick one answer for each question. The explanation appears after you choose.
1In the lab, why does the tool, not the language model, build the OData query string?
Answer: D. The model only proposes dimensions, measures and filters. The tool checks each name against $metadata and each value against a plain-code pattern, then builds $filter itself, so invented fields and quoted injections never reach the API.
2You request Product,MarginPct from an analytic model. How is the margin percent for ES-200 produced?
Answer: C. Calculated measures are computed after aggregation. In the lab the ES-200 figure is 56.78%, not the 56.49% average of the three customer percentages.
3A developer adds $apply=groupby((Product)) to an analytic model request and gets HTTP 400. What is the right fix?
Answer: B. Analytic model APIs aggregate by the dimensions and measures in $select and don't support $apply; SAP's KBA offers no date for it. A view exposed for consumption is the option when you need $apply.
4Why does the tool always add Currency when money measures are requested?
Answer: B. Aggregation follows $select, so leaving Currency out would add CP20's EUR rows to CP10's USD rows. Selecting it keeps one row per currency, as D2 in the lab shows.
5The planner asks the agent for September revenue by product and the tool returns no_rows_visible. What should the agent reply?
Answer: A. Data access controls hide rows the user may not see, so an empty result is not zero. The tool's note tells the agent to say exactly that rather than invent a figure or route data around the rule.
6Your agent must also run a margin check every night with no user signed in. What do you do?
Answer: B. SAP's overview describes data consumption as a signed-in user with an Interactive Usage client. An unattended run needs its own narrow design and an explicit, recorded decision, not a borrowed token or broad access.
7Which SAC AI features does SAP's KBA 3741620 list as premium AI that consumes AI Units?
Answer: A. The KBA names those four AI-assisted features as premium. SAP's feature page places Joule analytical insights in the Joule base entitlement, and lists prompt insights and story code generation as base AI that needs activation.
8An architecture board asks how the agent's answers stay right after the finance team changes the margin definition. What is the best answer?
Answer: D. Reading $metadata catches renamed fields but not a changed formula. Questions with known answers, rerun whenever the model is transported, show when an answer moves, as the ADR's consequences say.
Joule with SAP Datasphere (sap.com product page, read 2026-11-12)— answers how-to questions with documentation references, gives instance details, points to functions and performs tasks from the conversation; "AI Units are currently required"; offers Early Adopter Care registration; no release date
Joule, Analytical Insights (sap.com AI feature page, read 2026-11-12)— natural-language business questions answered from SAP applications; integrates with Just Ask in SAP Analytics Cloud in SAP Business Data Cloud; administrator controls models and data; "part of Joule base entitlement"; requires Joule Base plus an SAC or BDC subscription
Analytical Insights in Joule for SAP Analytics Cloud (SAP Architecture Center, last updated 12 May 2026, archived)— flow from Joule through a BTP destination to Just Ask; semantic search over model metadata; LLM generates an OData or SQL query; OAuth2SAMLBearerAssertion principal propagation; honors SAC role assignments; sources are live models from BDC, Datasphere or SAC and acquired SAC models; SAP marks the page as describing a retired or obsolete approach
3741620 - Understanding activation and cost of AI features in SAP Analytics Cloud (SAP KBA, re-read 2026-11-13)— Base AI included in the SAC subscription (Just Ask among them); AI-assisted story code generation and prompt insights listed as base AI from Q3 2026, activated by a support case; Premium AI consumes AI Units; premium list AI-assisted calculations, chart summary, commenting and data actions; activation by AI Units licence and a support case on component LOD-ANA-GAI; data center must be supported
Working with Analytic Models (SAP Learning, Exploring SAP Datasphere)— analytic model on a fact source; dimensions, restricted and calculated measures (calculated after aggregation); filters before aggregation; standard, filter, restriction and reference date variables; analytical preview; sharing across spaces