Azure OpenAI assistant create output binding for Azure Functions

Important

The Azure OpenAI extension for Azure Functions is currently in preview.

The Azure OpenAI assistant create output binding allows you to create a new assistant chat bot from your function code execution.

For information on setup and configuration details of the Azure OpenAI extension, see Azure OpenAI extensions for Azure Functions. To learn more about Azure OpenAI assistants, see Azure OpenAI Assistants API.

Note

References and examples are only provided for the Node.js v4 model.

Note

References and examples are only provided for the Python v2 model.

Note

While both C# process models are supported, only isolated worker model examples are provided.

Example

Go support isn't currently available for this binding.

This example demonstrates the creation process, where the HTTP PUT function that creates a new assistant chat bot with the specified ID. The response to the prompt is returned in the HTTP response.

/// <summary>
/// HTTP PUT function that creates a new assistant chat bot with the specified ID.
/// </summary>
[Function(nameof(CreateAssistant))]
public static async Task<CreateChatBotOutput> CreateAssistant(
    [HttpTrigger(AuthorizationLevel.Function, "put", Route = "assistants/{assistantId}")] HttpRequestData req,
    string assistantId)
{
    string instructions =
       """
        Don't make assumptions about what values to plug into functions.
        Ask for clarification if a user request is ambiguous.
        """;

    using StreamReader reader = new(req.Body);

    string request = await reader.ReadToEndAsync();


    return new CreateChatBotOutput
    {
        HttpResponse = new ObjectResult(new { assistantId }) { StatusCode = 201 },
        ChatBotCreateRequest = new AssistantCreateRequest(assistantId, instructions)
        {
            ChatStorageConnectionSetting = DefaultChatStorageConnectionSetting,
            CollectionName = DefaultCollectionName,
        },
    };
}

public class CreateChatBotOutput
{
    [AssistantCreateOutput()]
    public AssistantCreateRequest? ChatBotCreateRequest { get; set; }

    [HttpResult]
    public IActionResult? HttpResponse { get; set; }
}

This example demonstrates the creation process, where the HTTP PUT function that creates a new assistant chat bot with the specified ID. The response to the prompt is returned in the HTTP response.

/**
 * The default storage account setting for the table storage account.
 * This constant is used to specify the connection string for the table storage
 * account
 * where chat data will be stored.
 */
final String DEFAULT_CHATSTORAGE = "AzureWebJobsStorage";

/**
 * The default collection name for the table storage account.
 * This constant is used to specify the collection name for the table storage
 * account
 * where chat data will be stored.
 */
final String DEFAULT_COLLECTION = "ChatState";

/*
 * HTTP PUT function that creates a new assistant chat bot with the specified ID.
 */
@FunctionName("CreateAssistant")
public HttpResponseMessage createAssistant(
    @HttpTrigger(
        name = "req", 
        methods = {HttpMethod.PUT}, 
        authLevel = AuthorizationLevel.FUNCTION, 
        route = "assistants/{assistantId}") 
        HttpRequestMessage<Optional<String>> request,
    @BindingName("assistantId") String assistantId,
    @AssistantCreate(name = "AssistantCreate") OutputBinding<AssistantCreateRequest> message,
    final ExecutionContext context) {
        context.getLogger().info("Java HTTP trigger processed a request.");
        
        String instructions = "Don't make assumptions about what values to plug into functions.\n" +
                "Ask for clarification if a user request is ambiguous.";

        AssistantCreateRequest assistantCreateRequest = new AssistantCreateRequest(assistantId, instructions);
        assistantCreateRequest.setChatStorageConnectionSetting(DEFAULT_CHATSTORAGE);
        assistantCreateRequest.setCollectionName(DEFAULT_COLLECTION);

        message.setValue(assistantCreateRequest);
        JSONObject response = new JSONObject();
        response.put("assistantId", assistantId);
        
        return request.createResponseBuilder(HttpStatus.CREATED)
            .header("Content-Type", "application/json")
            .body(response.toString())
            .build();    
}

This example demonstrates the creation process, where the HTTP PUT function that creates a new assistant chat bot with the specified ID. The response to the prompt is returned in the HTTP response.

const { app, input, output } = require("@azure/functions");

const CHAT_STORAGE_CONNECTION_SETTING = "AzureWebJobsStorage";
const COLLECTION_NAME = "ChatState";

const chatBotCreateOutput = output.generic({
    type: 'assistantCreate'
})
app.http('CreateAssistant', {
    methods: ['PUT'],
    route: 'assistants/{assistantId}',
    authLevel: 'function',
    extraOutputs: [chatBotCreateOutput],
    handler: async (request, context) => {
        const assistantId = request.params.assistantId
        const instructions =
            `
            Don't make assumptions about what values to plug into functions.
            Ask for clarification if a user request is ambiguous.
            `
        const createRequest = {
            id: assistantId,
            instructions: instructions,
            chatStorageConnectionSetting: CHAT_STORAGE_CONNECTION_SETTING,
            collectionName: COLLECTION_NAME
        }
        context.extraOutputs.set(chatBotCreateOutput, createRequest)
        return { status: 202, jsonBody: { assistantId: assistantId } }
    }
})

import { HttpRequest, InvocationContext, app, input, output } from "@azure/functions"

const CHAT_STORAGE_CONNECTION_SETTING = "AzureWebJobsStorage";
const COLLECTION_NAME = "ChatState";

const chatBotCreateOutput = output.generic({
    type: 'assistantCreate'
})
app.http('CreateAssistant', {
    methods: ['PUT'],
    route: 'assistants/{assistantId}',
    authLevel: 'function',
    extraOutputs: [chatBotCreateOutput],
    handler: async (request: HttpRequest, context: InvocationContext) => {
        const assistantId = request.params.assistantId
        const instructions =
            `
            Don't make assumptions about what values to plug into functions.
            Ask for clarification if a user request is ambiguous.
            `
        const createRequest = {
            id: assistantId,
            instructions: instructions,
            chatStorageConnectionSetting: CHAT_STORAGE_CONNECTION_SETTING,
            collectionName: COLLECTION_NAME
        }
        context.extraOutputs.set(chatBotCreateOutput, createRequest)
        return { status: 202, jsonBody: { assistantId: assistantId } }
    }
})

This example demonstrates the creation process, where the HTTP PUT function that creates a new assistant chat bot with the specified ID. The response to the prompt is returned in the HTTP response.

Here's the function.json file for Create Assistant:

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "route": "assistants/{assistantId}",
      "methods": [
        "put"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "assistantCreate",
      "direction": "out",
      "dataType": "string",
      "name": "Requests"
    }
  ]
}

For more information about function.json file properties, see the Configuration section.

{{This comes from the example code comment}}

using namespace System.Net

param($Request, $TriggerMetadata)

$assistantId = $Request.params.assistantId

$instructions = "Don't make assumptions about what values to plug into functions."
$instructions += "\nAsk for clarification if a user request is ambiguous."

$create_request = @{
    "id" = $assistantId
    "instructions" = $instructions
    "chatStorageConnectionSetting" = "AzureWebJobsStorage"
    "collectionName" = "ChatState"
}

Push-OutputBinding -Name Requests -Value (ConvertTo-Json $create_request)

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::Accepted
    Body       = (ConvertTo-Json @{ "assistantId" = $assistantId})
    Headers    = @{
        "Content-Type" = "application/json"
    }
})

This example demonstrates the creation process, where the HTTP PUT function that creates a new assistant chat bot with the specified ID. The response to the prompt is returned in the HTTP response.

DEFAULT_CHAT_STORAGE_SETTING = "AzureWebJobsStorage"
DEFAULT_CHAT_COLLECTION_NAME = "ChatState"


@apis.function_name("CreateAssistant")
@apis.route(route="assistants/{assistantId}", methods=["PUT"])
@apis.assistant_create_output(arg_name="requests")
def create_assistant(
    req: func.HttpRequest, requests: func.Out[str]
) -> func.HttpResponse:
    assistantId = req.route_params.get("assistantId")
    instructions = """
            Don't make assumptions about what values to plug into functions.
            Ask for clarification if a user request is ambiguous.
            """
    create_request = {
        "id": assistantId,
        "instructions": instructions,
        "chatStorageConnectionSetting": DEFAULT_CHAT_STORAGE_SETTING,
        "collectionName": DEFAULT_CHAT_COLLECTION_NAME,
    }
    requests.set(json.dumps(create_request))
    response_json = {"assistantId": assistantId}
    return func.HttpResponse(
        json.dumps(response_json), status_code=202, mimetype="application/json"
    )

Attributes

Apply the CreateAssistant attribute to define an assistant create output binding, which supports these parameters:

Parameter	Description
Id	The identifier of the assistant to create.
Instructions	Optional. The instructions that are provided to assistant to follow.
ChatStorageConnectionSetting	Optional. The configuration section name for the table settings for chat storage. The default value is AzureWebJobsStorage.
CollectionName	Optional. The table collection name for chat storage. The default value is ChatState.

Annotations

The CreateAssistant annotation enables you to define an assistant create output binding, which supports these parameters:

Element	Description
name	Gets or sets the name of the output binding.
id	The identifier of the assistant to create.
instructions	Optional. The instructions that are provided to assistant to follow.
chatStorageConnectionSetting	Optional. The configuration section name for the table settings for chat storage. The default value is AzureWebJobsStorage.
collectionName	Optional. The table collection name for chat storage. The default value is ChatState.

Decorators

During the preview, define the output binding as a generic_output_binding binding of type createAssistant, which supports these parameters:

Parameter	Description
arg_name	The name of the variable that represents the binding parameter.
id	The identifier of the assistant to create.
instructions	Optional. The instructions that are provided to assistant to follow.
chat_storage_connection_setting	Optional. The configuration section name for the table settings for chat storage. The default value is AzureWebJobsStorage.
collection_name	Optional. The table collection name for chat storage. The default value is ChatState.

Configuration

The binding supports these configuration properties that you set in the function.json file.

Property	Description
type	Must be CreateAssistant.
direction	Must be out.
name	The name of the output binding.
id	The identifier of the assistant to create.
instructions	Optional. The instructions that are provided to assistant to follow.
chatStorageConnectionSetting	Optional. The configuration section name for the table settings for chat storage. The default value is AzureWebJobsStorage.
collectionName	Optional. The table collection name for chat storage. The default value is ChatState.

Configuration

The binding supports these properties, which are defined in your code:

Property	Description
id	The identifier of the assistant to create.
instructions	Optional. The instructions that are provided to assistant to follow.
chatStorageConnectionSetting	Optional. The configuration section name for the table settings for chat storage. The default value is AzureWebJobsStorage.
collectionName	Optional. The table collection name for chat storage. The default value is ChatState.

Usage

See the Example section for complete examples.

Connections

To use the Azure OpenAI binding extension, you need to specify a connection to an OpenAI model definition. Set the OpenAI model connection in your bindings by using one of these approaches:

• Use the AIConnectionName binding property (preferred for Azure OpenAI).
• Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_KEY in app settings (for Azure OpenAI).
• Set only Open_API_Key in app settings (for https://api.openai.com).

The way you set the connection depends on both the model API and the authentication method, as indicated by the following table:

Authentication/Model API	Azure OpenAI	OpenAI (https://api.openai.com)
Managed identity connection	AIConnectionName	Not supported
Key Vault reference	AZURE_OPENAI_ENDPOINT AZURE_OPENAI_KEY	Open_API_Key
App Configuration reference	AZURE_OPENAI_ENDPOINT AZURE_OPENAI_KEY	Open_API_Key
Shared secret	AZURE_OPENAI_ENDPOINT AZURE_OPENAI_KEY	Open_API_Key

Use managed identity-based connections and the AIConnectionName property.

When you use AIConnectionName, the value of this property setting depends on the type of connection:

• Managed identity connection: The AIConnectionName property is a <CONNECTION_NAME_PREFIX> shared by a group of settings that together define an identity-based connection to Azure OpenAI. For more information, see Define identity connections.
• Key Vault reference: The AIConnectionName property setting returns an Azure Key Vault reference to the location where the API key is centrally maintained. For more information, see Define Key Vault connections.
• App Configuration reference: The AIConnectionName property setting returns an Azure App Configuration reference that returns an API key or a Key Vault reference. For more information, see Azure App Configuration in the connections article.
• API key: The AIConnectionName property setting resolves to app settings containing the endpoint and key directly. Because shared keys can be compromised, use managed identity connections when possible. For more information, see Define connections.

To learn more about bindings connections, see Manage connections in Azure Functions.

AIConnectionName Property

The OpenAI bindings include an AIConnectionName property that you can use to specify the <ConnectionNamePrefix> for the group of app settings that define the connection to Azure OpenAI:

Setting name	Description
<CONNECTION_NAME_PREFIX>__endpoint	Sets the URI endpoint of the Azure OpenAI service. This setting is always required.
<CONNECTION_NAME_PREFIX>__clientId	Sets the specific user-assigned identity to use when obtaining an access token. Requires that <CONNECTION_NAME_PREFIX>__credential is set to managedidentity. The property accepts a client ID corresponding to a user-assigned identity assigned to the application. It's invalid to specify both a Resource ID and a client ID. If you don't specify this property, the system-assigned identity is used. This property is used differently in local development scenarios, when credential shouldn't be set.
<CONNECTION_NAME_PREFIX>__credential	Defines how an access token is obtained for the connection. Use managedidentity for managed identity authentication. This value is only valid when a managed identity is available in the hosting environment.
<CONNECTION_NAME_PREFIX>__managedIdentityResourceId	When credential is set to managedidentity, set this property to specify the resource Identifier to use when obtaining a token. The property accepts a resource identifier corresponding to the resource ID of the user-defined managed identity. It's invalid to specify both a resource ID and a client ID. If you don't specify either, the system-assigned identity is used. This property is used differently in local development scenarios, when credential shouldn't be set.
<CONNECTION_NAME_PREFIX>__key	Sets the shared secret key required to access the endpoint of the Azure OpenAI service by using key-based authentication. As a security best practice, always use Microsoft Entra ID with managed identities for authentication.

Consider these managed identity connection settings when you set the AIConnectionName property to myAzureOpenAI:

• myAzureOpenAI__endpoint=https://contoso.openai.azure.com/
• myAzureOpenAI__credential=managedidentity
• myAzureOpenAI__clientId=aaaaaaaa-bbbb-cccc-1111-222222222222

At runtime, the host interprets these settings as a single myAzureOpenAI setting:

"myAzureOpenAI":
{
    "endpoint": "https://contoso.openai.azure.com/",
    "credential": "managedidentity",
    "clientId": "aaaaaaaa-bbbb-cccc-1111-222222222222"
}

When you use managed identities, make sure to add your identity to the Cognitive Services OpenAI User role.

When running locally, add these settings to the local.settings.json project file. For more information, see Local development with identity-based connections.

Environment variables

To support legacy apps and providers other than Azure OpenAI, define key-based authentication to OpenAI by using these environment variables.

Variable name	Description
AZURE_OPENAI_ENDPOINT	Sets the URI endpoint of your Azure OpenAI instance. Don't use with Open_API_Key.
AZURE_OPENAI_KEY	Sets the shared secret key required to access your Azure OpenAI endpoint (AZURE_OPENAI_ENDPOINT) by using key-based authentication.
Open_API_Key	Sets the shared secret key required to access the https://api.openai.com endpoint by using key-based authentication.

Set these variables in your app settings.

When running locally, add these settings to the local.settings.json project file.

For more information, see Work with application settings.

Related content

• Assistant samples
• Azure OpenAI extension
• Azure OpenAI assistant trigger
• Azure OpenAI assistant query input binding
• Azure OpenAI assistant post input binding