# 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`](https://docs.api7.ai/hub/ai-prompt-decorator.md) 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)[​](#prerequisites "Direct link to Prerequisite(s)")

* Install [Docker](https://docs.docker.com/get-docker/).
* Install [cURL](https://curl.se/) to send requests for validation.
* Follow the [Getting Started Tutorial](https://docs.api7.ai/apisix/getting-started.md) 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[​](#obtain-an-openai-api-key "Direct link to Obtain an OpenAI API Key")

Create an [OpenAI API key](https://platform.openai.com/api-keys), then export the key and model:

```
export OPENAI_API_KEY="<your-api-key>"

export OPENAI_MODEL="<your-model-name>"
```

## Create a Route[​](#create-a-route "Direct link to 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](https://docs.api7.ai/apisix/production/security/data-encryption-with-keyring.md) is enabled, APISIX encrypts the key before saving the route to etcd. Configure a custom keyring in production.

## Verify[​](#verify "Direct link to Verify")

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

### Send a Chat Completions Request[​](#send-a-chat-completions-request "Direct link to 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-a-responses-api-request "Direct link to 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[​](#clean-up "Direct link to 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[​](#next-steps "Direct link to 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`](https://docs.api7.ai/hub/ai-prompt-guard.md) on the same route.
