/sap-btp-agents — SAP Integration Patterns for AI Agents

SAP's agent story runs through Joule Studio (low-code, BTP-native) and the SAP Cloud SDK for AI (pro-code). Both paths converge on the same BTP auth stack — and that auth stack is the primary project risk. Plan a full day for auth alone. This skill covers surface identification, the auth chain design, Commerce Cloud MCP, the S/4HANA Cloud SDK path, and production hardening.

IMPORTANT: If any SAP BTP engagement is expected to extend beyond 1 sprint, escalate to Superman to trigger Bridge-agent creation (SPX-030). This skill card covers the integration pattern; sustained SAP work warrants a persistent specialist persona.

STATUS: Verified September 2026 against SAP Help, SAP Architecture Learning, and SAP Community. SAP releases quarterly — verify against current SAP BTP release notes at author time. Commerce Cloud MCP server availability must be confirmed at the start of every engagement.

When to invoke

• Client runs SAP (S/4HANA, ECC, Commerce Cloud, or other BTP-hosted modules) and wants agent integration
• Designing an agent that reads or writes SAP business data (SD, MM, FI, or Commerce product catalogue)
• Evaluating Joule Studio (low-code) vs SAP Cloud SDK for AI (pro-code) for the agent build
• SAP Commerce Cloud MCP server is in scope — verify availability at author time
• Any XSUAA, OAuth2SAMLBearerAssertion, or BTP auth design conversation

Steps

1. Identify SAP surface and version. The integration approach depends on which SAP product the client runs:
   • S/4HANA Cloud: Use SAP Cloud SDK for AI (pro-code path). No published general-purpose S/4HANA MCP server confirmed as of September 2026 — the Cloud SDK is the primary agent integration surface. Verify at author time whether a general MCP server has been released.
   • SAP Commerce Cloud: The Storefront MCP Server (announced NRF 2026, Q2 2026 target) — agents can discover products and execute transactions autonomously. Verify current MCP server availability and supported operations at author time.
   • ECC (on-premise): REST API via BTP Integration Suite or RFC bridge. The same auth chain applies; connectivity requires BTP Cloud Connector for on-premise-to-cloud tunnelling. This adds setup time — factor into sprint planning.
   • Joule / Joule Studio (any surface): Low-code agent builder on BTP. Joule agents can interoperate with Microsoft Copilot agents via A2A (Agent-to-Agent) protocol — this is the integration seam for Microsoft + SAP cross-platform builds.
2. Auth chain design — plan a full day. The SAP BTP auth stack is the most complex in the enterprise integration landscape. Design the complete chain before writing any code:

   Identity Provider (SAP IAS or Entra ID federated to IAS)
     → SAML 2.0 Bearer Assertion (OAuth2SAMLBearerAssertion grant type)
     → XSUAA token endpoint (BTP's authorisation server)
     → OAuth2 bearer token
     → BTP service / SAP API endpoint

   Key decisions:
   • IDP choice: SAP Identity Authentication Service (IAS) native, or Entra ID federated to IAS
   • Trust configuration: The XSUAA service instance must trust the IDP — configure this in the BTP cockpit trust settings before any API calls are attempted
   • Service keys: Each BTP service produces a service key (JSON) containing the XSUAA endpoint, client credentials, and service-specific parameters. Store service keys in Azure Key Vault or SAP BTP Credential Store — never in code, config files, or environment variables committed to Git
   • Permission scopes: SAP module-specific (SD for sales/distribution, MM for materials management, FI for finance) — configure in the BTP subaccount and verify against the service's role templates
3. SAP Commerce Cloud — MCP server path. If the client uses Commerce Cloud:
   • Verify the Storefront MCP Server is available and determine which version and which features are live at author time — targeted Q2 2026, confirm current state
   • Auth: SAP IAS + XSUAA (same chain as Step 2)
   • MCP capabilities: product discovery, transaction execution (if agent has write permissions configured in BTP)
   • Connect to Copilot Studio or any MCP-capable agent host via the published MCP server endpoint; apply ACP (Advanced Connector Policies) governance
4. S/4HANA — SAP Cloud SDK for AI (pro-code path). When no MCP server is available for the required module:
   • Use the SAP Cloud SDK for AI to build a BTP-hosted agent service
   • Deploy to a dedicated BTP subaccount (managed or customer-managed) — not the production subaccount
   • The agent exposes capabilities consumable via A2A by Microsoft Copilot agents or other external agents
   • Verify SDK version and supported S/4HANA API surfaces at author time against the SAP Business Accelerator Hub
5. Test in a dedicated BTP subaccount. All SAP agent integration testing happens in a dedicated test subaccount — not production. Test:
   • Auth chain end-to-end: obtain a valid XSUAA token, call the API, verify the response and permission scopes
   • Data read operations for the agreed modules (SD, MM, FI as applicable)
   • Write operations (only if scoped and explicitly approved by client — SAP write operations carry significant business risk)
   • A2A interoperability (if bridging to Microsoft Copilot agents via A2A protocol)
6. Production hardening. Before any production deployment:
   • Rotate service keys to production-only credentials managed in Key Vault
   • Enable BTP audit logging on the production subaccount
   • Verify rate limits and retry policies for the XSUAA token endpoint — token refresh under load is a common failure mode
   • Confirm BTP subaccount entitlements for production — the required BTP services must be entitled for the production account, not just the development account
   • Document the key rotation schedule and the responsible party

Deliverable format

• Working SAP-agent integration (scoped to agreed modules and operations)
• Auth documentation: IDP configuration, XSUAA trust setup, service key structure (keys in Key Vault — not in the document)
• BTP service key handling procedure: how keys are rotated, where stored, who has access
• Test results from BTP subaccount: read operations, write operations (if scoped), auth failure cases
• A2A configuration document (if bridging to Microsoft Copilot agents)

Non-negotiables

• Plan a full day for auth alone. SAP BTP auth complexity is the #1 project risk in any SAP integration. XSUAA trust misconfiguration will block the entire integration — do not compress auth setup into a morning.
• No shortcuts on the SAML Bearer flow. OAuth2SAMLBearerAssertion is the required grant type for agent-to-SAP BTP authentication. Direct API key approaches will not work for BTP-native services.
• Verify SAP BTP subscription entitlement at kick-off. Required BTP services (BTP AI Core, Integration Suite, etc.) must be entitled for the client's BTP subaccount. Missing entitlements block the integration entirely — surface this at kick-off, not sprint 1.
• Verify MCP server availability at author time. The SAP Commerce Cloud MCP server was targeted Q2 2026 — confirm current availability and feature scope before designing around it.
• No production write operations without client sign-off. Autonomous agent write operations in SAP production (order posting, stock adjustment, payment posting) require explicit written approval from the client's SAP system owner.
• Escalate to Superman if the engagement is expected to exceed 1 sprint. This skill card is a starting point — it is not a substitute for a persistent specialist persona. Three or more SAP engagements trigger Bridge-agent creation (SPX-030).

References

• Build AI Agents on SAP BTP — SAP Architecture Learning — verify current at author time
• Configure OAuth 2.0 SAML Bearer Assertion Grant — SAP Help
• SAP Business Accelerator Hub — API catalogue — enumerate available API surfaces at author time
• Demystifying MCP Part 3: Integration with Joule — SAP Community
• Integrating AI Agents with Joule — SAP Architecture Learning
• SAP BTP Authentication Patterns — SAP Expert AI
• Athanasios recon: .squad/coach/knowledge/2026-09-04-enterprise-integration-recon.md (Angle 2 — SAP)
• Decision: .squad/decisions/2026-09-04-nexus-enterprise-integration-extension.md