Configure Prompt Decorators

Prompt decorators let operators apply reusable instructions before and after client prompts. They can standardize response guidelines, tone, format, or safety requirements without requiring each client to repeat those instructions.

Prompt decorators are useful when the gateway should add shared context without replacing the client's request body. Applications continue to provide task-specific prompts, while APISIX applies the configured instructions consistently across requests.

This guide shows how to use the ai-prompt-decorator plugin with OpenAI Chat Completions and Responses API requests. The same approach can be adapted to other request protocols and providers supported by the plugin.

Prerequisite(s)

• Install Docker.
• Install cURL to send requests for validation.
• Follow the Getting Started Tutorial to start an APISIX instance in Docker or on Kubernetes.
• Have an OpenAI account with API access to a model that supports both request formats.

Obtain an OpenAI API Key

Create an OpenAI API key, then export the key and model:

export OPENAI_API_KEY="<your-api-key>"
export OPENAI_MODEL="<your-model-name>"

Create a Route

APISIX identifies Chat Completions requests from the messages field. It identifies Responses requests from the input field together with an incoming URI ending in /v1/responses.

The plugin does not modify Embeddings requests because the Embeddings format has no prompt roles to prepend or append.

Create one route for both OpenAI API paths. Configure the prompt decorator to add a system instruction before the client's prompt and a user instruction after it:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "id": "ai-prompt-decorator-route",
    "uris": [
      "/v1/chat/completions",
      "/v1/responses"
    ],
    "methods": ["POST"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai",
        "auth": {
          "header": {
            "Authorization": "Bearer $OPENAI_API_KEY"
          }
        },
        "options": {
          "model": "$OPENAI_MODEL"
        }
      },
      "ai-prompt-decorator": {
        "prepend": [
          {
            "role": "system",
            "content": "Answer briefly and conceptually."
          }
        ],
        "append": [
          {
            "role": "user",
            "content": "End the answer with a simple analogy."
          }
        ]
      }
    }
  }
EOF

❶ Configure any client-facing path for Chat Completions. APISIX identifies the format from the messages field alone and sends the request to the OpenAI Chat Completions endpoint.

❷ Configure a client-facing path for Responses requests. The path can have a custom prefix, but it must end in /v1/responses. APISIX identifies the format from this suffix together with the input field and sends the request to the OpenAI Responses endpoint.

❸ Add system content before the client's prompt. For Responses requests, the plugin adds this content to instructions.

❹ Add user content after the client's prompt. For Responses requests, the plugin adds this content to input.

The route configuration contains the OpenAI API key. When data encryption with a keyring is enabled, APISIX encrypts the key before saving the route to etcd. Configure a custom keyring in production.

Verify

Send requests in both formats to verify how APISIX decorates each prompt.

Send a Chat Completions Request

Send a request with a user message:

curl -i "http://127.0.0.1:9080/v1/chat/completions" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is mTLS authentication?"
      }
    ]
  }'

APISIX sends the following message order upstream:

{
  "messages": [
    {
      "role": "system",
      "content": "Answer briefly and conceptually."
    },
    {
      "role": "user",
      "content": "What is mTLS authentication?"
    },
    {
      "role": "user",
      "content": "End the answer with a simple analogy."
    }
  ]
}

You should receive an HTTP 200 response containing an assistant message in choices.

Send a Responses API Request

Send the same prompt in Responses API format:

curl -i "http://127.0.0.1:9080/v1/responses" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What is mTLS authentication?"
  }'

APISIX sends the decorated fields upstream as follows:

{
  "instructions": "Answer briefly and conceptually.",
  "input": "What is mTLS authentication?\nEnd the answer with a simple analogy."
}

You should receive an HTTP 200 response containing typed items in output.

Clean Up

Delete the APISIX route when you no longer need it:

curl "http://127.0.0.1:9180/apisix/admin/routes/ai-prompt-decorator-route" -X DELETE \
  -H "X-API-KEY: ${ADMIN_API_KEY}"

Remove the OpenAI values from the shell:

unset OPENAI_API_KEY OPENAI_MODEL

Next Steps

You have now configured APISIX to decorate both Chat Completions and Responses API prompts.

To add guardrails to the decorated prompts, configure ai-prompt-guard on the same route.