Author(s): Kunal

Originally published on Towards AI.

In the previous article, we have already laid the architectural foundation and built a robust FastAPI backend ready for integration. Now that our API is live and verified, it is time to face the “Integration Gauntlet.”

Exposing custom APIs to SAP’s ecosystem isn’t just about importing a file — it’s about navigating undocumented schema limitations, hard platform constraints, and the unique way SAP handles connectivity. In this part, we’ll move from the backend to the SAP Build platform and resolve the infrastructure bottlenecks that keep most developers stuck.

Importing the API into SAP Build Actions

With the API running successfully and tested independently, the next step was exposing it to the SAP ecosystem.

On paper, this sounds straightforward. SAP Build Actions supports OpenAPI specifications, and FastAPI conveniently generates an OpenAPI document automatically. The expectation is simple: export the specification, import it into SAP Build, and begin building Skills.

Unfortunately, this is where I encountered the first major integration challenge.

The OpenAPI document generated by FastAPI was technically correct. It validated successfully in OpenAPI tools, loaded without issues in Swagger UI, and worked perfectly in API testing environments.

SAP Build disagreed.

The import failed repeatedly with generic validation errors that provided very little information about the underlying problem.

After several hours of investigation, the root cause became clear.

The OpenAPI 3.1 Problem

Modern FastAPI versions generate OpenAPI 3.1 specifications.

SAP Build Actions currently expects OpenAPI 3.0.x compatibility.

While the difference appears minor, several schema features introduced in OpenAPI 3.1 are not accepted during SAP Build imports.

As a result, a specification that is completely valid according to OpenAPI standards may still be rejected.

The practical solution was to downgrade the generated specification before importing it.

Changes Required

The following modifications were required before SAP Build would successfully import the API:

• Change OpenAPI version from 3.1.0 to 3.0.3
• Replace anyOf structures containing null
• Convert nullable fields into OpenAPI 3.0 compatible format
• Remove unsupported schema constructs
• Add an explicit servers section
• Replace examples arrays with example

A simplified example:

Generated by FastAPI

{
 “openapi”: “3.1.0”
}

Accepted by SAP Build

{
 “openapi”: “3.0.3”
}

This sounds trivial until you discover dozens of schema objects requiring similar adjustments.

Eventually I automated the conversion using Python because manually fixing the specification after every API change quickly became unsustainable.

The 20 Action Limit

The next surprise was not a bug.

It was a platform limitation.

SAP Build Actions imposes a hard limit on the number of Actions imported from a specification.

If your API contains many endpoints, you cannot simply import everything and decide later what the agent should use.

This forces architectural decisions much earlier than expected.

My original API contained significantly more endpoints than were realistically needed by the AI agent. Once the Action limit became apparent, endpoint design had to be reconsidered.

The most useful strategy was to think like an agent rather than like a backend engineer.

Instead of exposing every resource individually, expose capabilities.

For example:

Instead of:

GET /alerts
GET /critical-alerts
GET /warning-alerts
GET /resolved-alerts
GET /customer-alerts
GET /portfolio-alerts

Consider:

GET /alerts?type=critical
GET /alerts?type=warning
GET /alerts?type=resolved

Or even:

GET /browse?category=alerts

This approach dramatically reduces Action consumption while keeping the functionality available.

The lesson here is that APIs built for AI agents often benefit from consolidation rather than extreme specialization.

Importing the Specification

Once the OpenAPI document was adjusted, importing became relatively straightforward.

The workflow was:

1. Export OpenAPI specification
2. Convert OpenAPI 3.1 → 3.0.3
3. Upload specification into SAP Build Actions
4. Review generated Actions
5. Test every Action individually

That last step is important.

Do not proceed directly to Skills.

Test every Action first.

A successful import does not guarantee successful execution.

Many problems only become visible when the Action attempts to communicate with the backend.

This distinction becomes important in the next phase of the architecture.

Part 3: The BTP Destination Layer

At this stage, the API existed.

The specification imported successfully.

Actions were generated.

Everything appeared ready.

Yet every request failed.

The reason turned out to be one of the least obvious parts of the entire architecture.

Authentication.

Most developers naturally look for authentication settings inside the Action configuration itself.

You import an API.

You configure credentials.

You execute requests.

That mental model works in many platforms.

SAP approaches the problem differently.

Authentication is not configured inside the Action project.

Instead, it is delegated to a separate infrastructure component known as a Destination.

Initially, this felt confusing because the Action editor exposes very few authentication controls.

There is no obvious place to enter credentials.

No OAuth wizard.

No API key configuration.

No Basic Authentication setup.

The assumption was that I had missed something.

I had not.

The configuration genuinely lives elsewhere.

Understanding Destinations

A BTP Destination acts as an abstraction layer between SAP applications and external services.

Rather than embedding connectivity information inside individual projects, SAP centralizes it.

This means:

URL configuration lives in the Destination
Authentication lives in the Destination
Connectivity settings live in the Destination
Actions consume the Destination

Conceptually:

Action → Destination → External API

The benefit becomes clear at enterprise scale.

Multiple applications can reuse the same Destination configuration without duplicating credentials or connection settings.

While initially frustrating, the architecture makes sense once viewed through an operational and governance lens.

Destination Configuration

The Destination configuration used for this project looked similar to the following:

Property Value
Type HTTP
Proxy Type Internet
Authentication BasicAuthentication
URL API Base URL
Username Service User
Password Service Password

Once the Destination was configured correctly, Actions immediately began authenticating successfully.

What initially appeared to be an API problem was actually a connectivity configuration issue.

This became a recurring theme throughout the project.

Many failures appeared in one layer while actually originating in another.

The most effective debugging strategy was therefore to validate each layer independently:

• Validation Sequence
• Test API directly using Postman
• Test Destination connectivity
• Test Action execution
• Test Skill execution
• Test Agent orchestration

Skipping layers makes troubleshooting significantly harder because error messages rarely indicate the true source of the problem.

The Importance of Isolated Testing

One of the biggest mistakes developers make when building AI agents is attempting to test the complete stack immediately.

A natural instinct is to ask the agent a question and expect everything underneath to work.

When the response fails, it becomes difficult to identify whether the issue exists in:

The prompt
The Skill
The Action
Authentication
The API
Response mapping

Testing each layer independently avoids this ambiguity.

By the time I reached the Agent layer, every Action and every Skill had already been validated individually.

That discipline ultimately saved far more time than it cost.

With Actions successfully communicating through Destinations, the next challenge was building Skills.

This is where SAP Joule Studio’s orchestration model begins to reveal both its strengths and its quirks.

With our Actions successfully imported, our OpenAPI specifications cleaned, and our BTP Destinations verified, we finally have a stable pipe between our external logic and the SAP ecosystem.

But connectivity is only half the battle. A pipeline is useless if the Agent doesn’t know how to navigate it effectively.

In the final part of this series, we move into the “Intelligence” layer.

We will tackle the complexities of building Skills in SAP Joule Studio, the “End Trigger” configuration traps, and the specific prompting strategies required to stop an agent from hallucinating.

Stay tuned for the final stretch.

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI