Bring Your Own Agent: Building an A2A-Compliant Pro-Code Agent on SAP BTP and Plugging It into Joule
A technical walkthrough for BTP developers: SAP CAP + SAP Cloud SDK for AI + an agent framework, exposed to Joule via the Agent2Agent (A2A) protocol.
Joule Studio covers a lot of ground, but some agents need full programmatic control: custom state machines, complex tool chains, specialised models or partner IP you want to reuse across customers. SAP's reference architecture for these cases is clear — build a pro-code agent on SAP BTP and integrate it with Joule using A2A, an approach SAP calls "Bring Your Own Agent".
1. The building blocks
SAP Cloud SDK for AI (JavaScript/TypeScript, Python, Java) — the official SDK for SAP AI Core, the Generative AI Hub and the orchestration service. It gives you harmonised access to models plus templating, grounding, data masking and content filtering.
SAP CAP — structures the use-case logic, persistence (SAP HANA Cloud) and connectivity to S/4HANA, SuccessFactors or Ariba via Destination and Connectivity services.
An agent framework — LangGraph, CrewAI, AG2 or Smolagents. The SDK ships a LangChain integration (@sap-ai-sdk/langchain) that works with LangGraph.
A2A server endpoint — the contract through which Joule talks to your agent.
2. Calling the LLM through the orchestration service (SDK v2)
Always go through the orchestration service rather than calling a model directly — you get masking, filtering and model portability for free. With SDK v2 the configuration uses the consolidated promptTemplating module:
import { OrchestrationClient, buildAzureContentSafetyFilter } from '@sap-ai-sdk/orchestration';
const client = new OrchestrationClient({
promptTemplating: {
model: { name: process.env.LLM_MODEL }, // any model deployed in your Generative AI Hub
prompt: {
template: [
{ role: 'system', content: 'You are a procurement assistant. Answer only from tool results.' },
{ role: 'user', content: '{{?question}}' }
]
}
},
filtering: {
input: { filters: [buildAzureContentSafetyFilter('input', { prompt_shield: true })] }
}
}, { resourceGroup: 'default' });
const res = await client.chatCompletion({ placeholderValues: { question } });
console.log(res.getContent());Notes for v1 users: v2 renamed llm/templating to promptTemplating, inputParams to placeholderValues, and filter builders now take an explicit 'input' or 'output' type. Bind an AI Core instance (plan extended) to your app, and make sure an orchestration deployment exists in your resource group.
3. Structuring the agent with CAP
We keep the agent graph thin and let CAP own the business logic:
CAP services implement tools (e.g., getOpenPOs, checkBudget) with proper @restrict rules.
The same services can be annotated with @mcp (via @cap-js/mcp) so other agents — including Joule Studio agents — can reuse them.
The agent loop (LangGraph or similar) decides which tool to call, keeps state in HANA Cloud for long-running tasks, and asks the user for confirmation before writes.
4. Exposing the A2A endpoint
Your agent must act as an A2A server: publish an Agent Card describing its skills, and accept JSON-RPC requests. Per SAP's architecture guidance, Joule acts as the A2A client and sends a message/send request containing the user utterance, following A2A protocol version 0.3.0, with text messages currently supported. Implement the server with the official A2A SDK for your language, protect it with XSUAA/IAS, and deploy it to Cloud Foundry or Kyma.
5. Registering the agent in Joule
Create a Joule scenario representing the pro-code agent.
Add a dialog function with an action of type agent-request.
Point it to the agent's A2A endpoint through a BTP destination.
Deploy the Joule content and test from Joule with realistic prompts.
SAP's Architecture Center also publishes a reference implementation for A2A-compliant pro-code agents with Joule integration — a good baseline before writing your own.
6. Production checklist
Identity: decide user-context (principal propagation) vs. technical user per tool.
Guardrails: enable data masking for personal data and input/output filtering in orchestration.
Determinism: confirmations for any write; idempotent actions; max-iteration limits in the graph.
Observability: log the orchestration request ID (getRequestId()), tool calls and decisions; use the CAP log and BTP Application Logging.
Model lifecycle: SAP regularly retires models in the Generative AI Hub — keep the model name in configuration, not code, and watch the SDK release notes.
Evaluation: maintain a golden test set and run it in CI on every prompt or model change.
FAQ
Python or TypeScript? Both are first-class. TypeScript fits naturally with CAP Node.js; Python suits teams already using LangGraph or data-science tooling (PyPI package sap-ai-sdk-gen).
Can external agents call Joule Agents too? Yes — SAP announced a governed agent gateway at TechEd 2026 that lets third-party agents invoke Joule Agents with enforced access control.
Build it with us
Raven Infotech delivers pro-code agents on SAP BTP end to end — CAP, SAP Cloud SDK for AI, A2A and Joule integration — and trains your team along the way. Contact us for a pro-code agent starter kit and a 1-week PoC.
Comments