ballerinax/azure.openai.responses Ballerina library

Ballerina Azure OpenAI Responses connector

Overview

Azure OpenAI provides access to OpenAI's powerful language models including GPT-4o, GPT-4, and o-series models through Microsoft Azure's enterprise-grade infrastructure. It combines OpenAI's advanced AI capabilities with Azure's security, compliance, and regional availability features.

The ballerinax/azure.openai.responses package offers functionality to connect and interact with the Responses API of the Azure AI Foundry Models Service. The Responses API is a stateful API that provides a more powerful and flexible way to build AI applications, supporting features like multi-turn conversations, built-in tools (web search, file search, code interpreter), and background processing.

This connector exposes the create model response operation (POST /responses).

Setup guide

To use the Azure OpenAI Responses Connector, you must have access to an Azure OpenAI resource through a Microsoft Azure account. If you do not have an Azure account, you can sign up for one here.

Create an Azure OpenAI resource and obtain the API key

1. Sign in to the Azure Portal.

2. Search for "Azure OpenAI" in the top search bar and select Azure OpenAI from the results.

3. Click Create to create a new Azure OpenAI resource. Fill in the required details such as subscription, resource group, region, and resource name, then click Review + create and finally Create.

4. Once the resource is deployed, navigate to your Azure OpenAI resource.

5. In the left-hand menu, go to Resource Management -> Keys and Endpoint.

6. Copy one of the provided keys (Key 1 or Key 2) and the endpoint URL. Store them securely to use in your application.

Derive the service URL

The Responses API is served from the /openai/v1 base path, and the connector appends only the resource path (such as /responses) to the URL you supply. Append openai/v1 to the endpoint copied from the portal to form the service URL:

https://<resource-name>.openai.azure.com/openai/v1

If the resource was created as an Azure AI Foundry resource, use its host instead:

https://<resource-name>.services.ai.azure.com/openai/v1

Note: Passing the bare endpoint copied from the portal (https://<resource-name>.openai.azure.com) sends requests to /responses rather than /openai/v1/responses, which fails with a 404.

Quickstart

To use the Azure OpenAI Responses connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

Import the ballerinax/azure.openai.responses module. The ballerina/io module is also imported to print the response.

import ballerina/io;
import ballerinax/azure.openai.responses;

Step 2: Create a new connector instance

Create a responses:Client with the API key and the service URL derived in the setup guide. The connector sends the key in the api-key header, which is the header Azure expects for API key authentication.

configurable string apiKey = ?;
configurable string serviceUrl = ?;

final responses:Client azureOpenAI = check new ({
    auth: {
        api\-key: apiKey
    }
}, serviceUrl);

Supply the values through a Config.toml file placed alongside the Ballerina.toml file:

apiKey = "<your-azure-openai-api-key>"
serviceUrl = "https://<resource-name>.openai.azure.com/openai/v1"

Note: An Azure OpenAI API key must not be passed as token. Azure accepts keys only in the api-key header, so sending a key as a bearer token fails with a 401.

Step 3: Invoke the connector operation

Now, you can utilize available connector operations.

Create a model response

The generated text is carried by the output array of the response. Each output item holds a list of content parts, and the assistant's text is in the parts of type output_text.

public function main() returns error? {

    responses:OpenAICreateResponse request = {
        model: "gpt-4o-mini",
        input: "What is the Ballerina programming language?"
    };

    responses:InlineResponse200 response = check azureOpenAI->/responses.post(request);

    foreach responses:OpenAIOutputItem item in response.output {
        anydata content = item["content"];
        if content !is anydata[] {
            continue;
        }
        foreach anydata part in content {
            if part is map<anydata> && part["type"] == "output_text" {
                io:println(part["text"]);
            }
        }
    }
}

Note: The output_text field on the response is a convenience property that the official OpenAI SDKs compute on the client side by joining the output_text content parts. The REST API does not send it, so it is nil on responses returned by this connector — read the text from output as shown above.

Step 4: Run the Ballerina application

bal run

Examples

The Azure OpenAI Responses connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

1. Simple response - Create a model response using the Azure OpenAI Responses API.