OpenAI .NET Library

To constrain chat completion content to a specific JSON schema, use the ChatResponseFormat.CreateJsonSchemaFormat method. This is supported on specific model snapshots like gpt-4o-mini, gpt-4o-mini-2024-07-18, and gpt-4o-2024-08-06.

1. Create Schema: Define your JSON schema as a string or byte array.
2. Set Response Format: In ChatCompletionOptions, set the ResponseFormat property using ChatResponseFormat.CreateJsonSchemaFormat.
3. Strict Mode: Use jsonSchemaIsStrict: true to ensure the model adheres strictly to the provided schema.
4. Parse Result: The model's response text will be a JSON string that can be parsed using JsonDocument.

ChatCompletionOptions options = new()
{
    ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat(
        jsonSchemaFormatName: "math_reasoning",
        jsonSchema: BinaryData.FromBytes("""
            {
                "type": "object",
                "properties": {
                    "steps": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "explanation": { "type": "string" },
                                "output": { "type": "string" }
                            },
                            "required": ["explanation", "output"],
                            "additionalProperties": false
                        }
                    },
                    "final_answer": { "type": "string" }
                },
                "required": ["steps", "final_answer"],
                "additionalProperties": false
            }
            """u8.ToArray()),
        jsonSchemaIsStrict: true)
};

ChatCompletion completion = client.CompleteChat(messages, options);
using JsonDocument structuredJson = JsonDocument.Parse(completion.Content[0].Text);

To build an assistant capable of analyzing uploaded documents (RAG), follow these steps:

1. Initialize Clients: Use OpenAIClient to obtain an OpenAIFileClient (from OpenAI.Files) and an AssistantClient (from OpenAI.Assistants).
   • Note: The Assistants API is in beta. AssistantClient is marked [Experimental]. You must suppress the OPENAI001 warning to use it.
2. Upload Files: Use OpenAIFileClient.UploadFile with FileUploadPurpose.Assistants to make files available to the assistant.
3. Create Assistant: Use AssistantClient.CreateAssistant with AssistantCreationOptions. To enable RAG, include FileSearchToolDefinition in the Tools collection and configure ToolResources using a VectorStoreCreationHelper to index your uploaded files.
4. Run Threads: Create a thread and run it using AssistantClient.CreateThreadAndRun.
5. Poll Status: Use AssistantClient.GetRun in a loop, checking threadRun.Status.IsTerminal to wait for completion.
6. Retrieve Messages: Use AssistantClient.GetMessages to fetch the conversation history, including assistant responses and any generated files (like images).

// 1. Initialize Clients
OpenAIClient openAIClient = new(Environment.GetEnvironmentVariable("OPENAI_API_KEY"));
OpenAIFileClient fileClient = openAIClient.GetOpenAIFileClient();
AssistantClient assistantClient = openAIClient.GetAssistantClient();

// 2. Upload File
OpenAIFile salesFile = fileClient.UploadFile(
    document, 
    "monthly_sales.json", 
    FileUploadPurpose.Assistants);

// 3. Create Assistant with RAG capabilities
AssistantCreationOptions assistantOptions = new()
{
    Name = "Example: Contoso sales RAG",
    Instructions = "You are an assistant that looks up sales data...",
    Tools = 
    {
        new FileSearchToolDefinition(),
        new CodeInterpreterToolDefinition(),
    },
    ToolResources = new()
    {
        FileSearch = new()
        {
            NewVectorStores = 
            {
                new VectorStoreCreationHelper([salesFile.Id]),
            }
        }
    },
};
Assistant assistant = assistantClient.CreateAssistant("gpt-5.1", assistantOptions);

// 4. Create Thread and Run
ThreadCreationOptions threadOptions = new()
{
    InitialMessages = { "How well did product 113045 sell in February? Graph its trend over time." }
};
ThreadRun threadRun = assistantClient.CreateThreadAndRun(assistant.Id, threadOptions);

// 5. Poll for completion
do
{
    Thread.Sleep(TimeSpan.FromSeconds(1));
    threadRun = assistantClient.GetRun(threadRun.ThreadId, threadRun.Id);
} while (!threadRun.Status.IsTerminal);

// 6. Get Messages
CollectionResult<ThreadMessage> messages = assistantClient.GetMessages(threadRun.ThreadId, new MessageCollectionOptions() { Order = MessageCollectionOrder.Ascending });

You can enable the model to call functions by defining ChatTool instances and passing them via ChatCompletionOptions.

1. Define Tools: Use ChatTool.CreateFunctionTool to describe your functions. You can provide a functionName, functionDescription, and a JSON schema for functionParameters using BinaryData.
2. Configure Options: Add the tools to the Tools property of a ChatCompletionOptions instance.
3. Handle Tool Calls: When calling CompleteChat, check the FinishReason of the resulting ChatCompletion. If it is ChatFinishReason.ToolCalls, you must:
   • Add the AssistantChatMessage (containing the tool calls) to your message history.
   • Execute the local functions corresponding to the ToolCalls.
   • Add a ToolChatMessage for each result to the message history.
   • Call CompleteChat again with the updated history to get the final response.

Note: Arguments returned by the model in toolCall.FunctionArguments are stringified JSON objects. You should parse and validate them before execution.

// 1. Define tools
ChatTool getCurrentLocationTool = ChatTool.CreateFunctionTool(
    functionName: nameof(GetCurrentLocation),
    functionDescription: "Get the user's current location"
);

ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool(
    functionName: nameof(GetCurrentWeather),
    functionDescription: "Get the current weather in a given location",
    functionParameters: BinaryData.FromBytes("""
        {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. Boston, MA"
                },
                "unit": {
                    "type": "string",
                    "enum": [ "celsius", "fahrenheit" ],
                    "description": "The temperature unit to use. Infer this from the specified location."
                }
            },
            "required": [ "location" ]
        }
        """u8.ToArray())
);

// 2. Set options
ChatCompletionOptions options = new()
{
    Tools = { getCurrentLocationTool, getCurrentWeatherTool },
};

// 3. Execution loop pattern
List<ChatMessage> messages = [ new UserChatMessage("What's the weather like today?") ];
bool requiresAction;
do
{
    requiresAction = false;
    ChatCompletion completion = client.CompleteChat(messages, options);

    switch (completion.FinishReason)
    {
        case ChatFinishReason.Stop:
            messages.Add(new AssistantChatMessage(completion));
            break;

        case ChatFinishReason.ToolCalls:
            messages.Add(new AssistantChatMessage(completion));
            foreach (ChatToolCall toolCall in completion.ToolCalls)
            {
                // Execute local function and add ToolChatMessage to history
                string toolResult = ExecuteLocalFunction(toolCall);
                messages.Add(new ToolChatMessage(toolCall.Id, toolResult));
            }
            requiresAction = true;
            break;
        // ... handle other cases
    }
} while (requiresAction);