Creating a wrapper

Lakera Red tests AI systems by sending probes and analyzing the responses. To do that, Red needs an HTTP endpoint it can call.

If your system already matches Red’s supported contracts, connect it directly with an Agent target. If it does not, place a wrapper in front of it.

What a wrapper does

A wrapper is a lightweight HTTP service between Red and your AI system. It translates Red’s request format into your system’s format, waits for the full response, and returns Red-compatible JSON.

Red -> Wrapper -> Your API
Red <- Wrapper <- Your API

This is especially useful when your system is not directly OpenAI-compatible, streams output, or needs custom auth handling.

Handle authentication in the way that best fits your system. Your wrapper can either forward Lakera Red credentials upstream or use its own configured credentials when calling the target system.

Wrapper contract

Your wrapper must expose the Stateful agent contract. Red uses a sessionId to maintain multi-turn conversations.

Request (Red → wrapper):

1
{
2
  "message": "Tell me about your refund policy",
3
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
4
}

Response (wrapper → Red):

1
{
2
  "message": "Our refund policy allows...",
3
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
4
}

On the first request, Red omits sessionId. Your wrapper should create a new session and return its ID. Red then sends that sessionId on follow-up requests.

Typical wrapper flow

1. Authenticate the inbound request from Red.
2. Resolve an existing session or create a new one.
3. Translate Red’s request into the payload your upstream system expects.
4. Call the upstream API.
5. Collect the full response (buffer if upstream streams).
6. Return Red-compatible JSON with the sessionId.

Generate a starter wrapper with AI

1
Create a minimal HTTP wrapper for Lakera Red.
2
3
## Preferred language/framework
4
5
<e.g., Node + Express, Python + Flask, Go>
6
7
## Lakera Red endpoint
8
9
The wrapper must expose a Stateful endpoint:
10
11
POST /chat
12
13
Request: { "message": "string", "sessionId": "string (optional)" }
14
15
Response: { "message": "string", "sessionId": "string" }
16
17
## Requirements
18
19
- Require an Authorization: Bearer <TOKEN> header; reject requests without it with 401
20
- Store conversation history in memory, keyed by sessionId; persistence is not required
21
- Translate the Lakera Red request into my upstream API format
22
- Translate the upstream API response back into the Lakera Red response format
23
- Return the full response synchronously
24
- Keep the implementation minimal and easy to run locally
25
26
## My upstream API request example
27
28
<paste a full curl command or JSON request example, including headers>
29
30
## My upstream API response example
31
32
<paste a full JSON response example>
33
34
## My upstream auth details
35
36
<paste auth scheme, headers, token location, and any required fields>
37
38
## Please return
39
40
1. A complete working wrapper
41
2. A short explanation of where the translation happens
42
3. How to run it locally
43
4. How to deploy it so Lakera Red can reach it
44
5. An example curl request to test it

Practical guidance

Secure the wrapper endpoint with authentication, such as a Bearer Token or API Key. Once deployed, use the Test Connection option in Red to verify the setup.

How to configure Red for a wrapper

Configure the wrapper as an Agent target:

Next steps

• Agent target configuration for full details on the request/response contracts.
• Getting Started with Lakera Red to create the target and run your first scan.