What causes "Output schema must have a title" in microsoft/autogen?

Set a title on the schema before passing it: JsonSchemaBuilder...Title("MyOutput").Build(), or add "title" to the raw JSON

microsoft/autogen · error · ArgumentException

Output schema must have a title

Error message

Output schema must have a title

What it means

ArgumentException thrown in CreateChatCompletionsOptions when GenerateReplyOptions.OutputSchema (a JsonSchema.Net JsonSchema) has no title and the code needs a name for ChatResponseFormat.CreateJsonSchemaFormat. Structured-output mode requires a named schema; an anonymous schema cannot be registered as a JSON schema response format.

Source

Thrown at dotnet/src/AutoGen.OpenAI/Agent/OpenAIChatAgent.cs:185

        {
            foreach (var f in openAIFunctionDefinitions)
            {
                option.Tools.Add(f);
            }
        }

        if (options?.StopSequence is var sequence && sequence is { Length: > 0 })
        {
            foreach (var seq in sequence)
            {
                option.StopSequences.Add(seq);
            }
        }

        if (options?.OutputSchema is not null)
        {
            option.ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat(
                jsonSchemaFormatName: options.OutputSchema.GetTitle() ?? throw new ArgumentException("Output schema must have a title"),
                jsonSchema: BinaryData.FromObjectAsJson(options.OutputSchema),
                jsonSchemaFormatDescription: options.OutputSchema.GetDescription());
        }

        return option;
    }

    private static ChatCompletionOptions CreateChatCompletionOptions(
        float? temperature = 0.7f,
        int? maxTokens = 1024,
        int? seed = null,
        ChatResponseFormat? responseFormat = null,
        IEnumerable<ChatTool>? functions = null)
    {
        var options = new ChatCompletionOptions
        {
            Temperature = temperature,
            MaxOutputTokenCount = maxTokens,

View on GitHub (pinned to 027ecf0a37)

Solutions

Set a title on the schema before passing it: JsonSchemaBuilder...Title("MyOutput").Build(), or add "title" to the raw JSON
Build the schema with JsonSchema.Net's builder or FromType<T>() on a named class, which derives a title
Verify options.OutputSchema.GetTitle() returns non-null before calling the agent

Example fix

// before
var schema = JsonSchema.FromText("{\"type\":\"object\"}");
var opts = new GenerateReplyOptions { OutputSchema = schema }; // throws

// after
var schema = JsonSchemaBuilder.FromType<MyResponse>().Title("MyResponse").Build();
var opts = new GenerateReplyOptions { OutputSchema = schema };

Defensive patterns

Strategy: validation

Validate before calling

if (options?.OutputSchema?.GetTitle() is null) { /* set title before calling agent */ }

Type guard

static bool SchemaHasTitle(JsonSchema s) => s.GetTitle() is not null;

Try / catch

catch (ArgumentException ex) when (ex.Message == "Output schema must have a title") { /* add .Title(...) and retry */ }

Prevention

Build output schemas with JsonSchemaBuilder and always set .Title(name)
Validate external schema files contain "title" at load time

When it happens

Trigger: Passing new GenerateReplyOptions { OutputSchema = schema } where schema was built without a title (e.g. JsonSchema from a raw JSON string lacking a "title" property, or a JsonSchemaBuilder chain without .Title(...)).

Common situations: Loading JSON schemas from files/strings for structured output; building schemas via FromType without setting a title; schema authored externally (Apicurio/TypeChat style) with title omitted.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/ca595383ba86f256. Report an issue: GitHub.