Implement structured outputs

Signed-off-by: Djordje Lukic <djordje.lukic@docker.com>

Author: rumpl

cagent-schema.json

@@ -8,8 +8,18 @@
     "version": {
       "type": "string",
       "description": "Configuration version",
-      "enum": ["1", "2", "v1", "v2"],
-      "examples": ["1", "2", "v1", "v2"]
+      "enum": [
+        "1",
+        "2",
+        "v1",
+        "v2"
+      ],
+      "examples": [
+        "1",
+        "2",
+        "v1",
+        "v2"
+      ]
     },
     "agents": {
       "type": "object",
@@ -103,16 +113,79 @@
           "oneOf": [
             {
               "type": "object",
-              "additionalProperties": { "type": "string" }
+              "additionalProperties": {
+                "type": "string"
+              }
             },
             {
               "type": "array",
               "items": {
                 "type": "object",
-                "additionalProperties": { "type": "string" }
+                "additionalProperties": {
+                  "type": "string"
+                }
               }
             }
           ]
+        },
+        "structured_output": {
+          "type": "object",
+          "description": "Structured output configuration for constraining model responses to a specific JSON schema. Supported by OpenAI (native) and Google Gemini (native). Anthropic requires prompt engineering or tool-based approaches.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Name of the response format schema"
+            },
+            "description": {
+              "type": "string",
+              "description": "Optional description of what the schema represents"
+            },
+            "strict": {
+              "type": "boolean",
+              "description": "Enable strict schema adherence (OpenAI only). When true, all properties must be in required array.",
+              "default": false
+            },
+            "schema": {
+              "type": "object",
+              "description": "JSON Schema object defining the structure of the response. Must include type, properties, and required fields.",
+              "required": [
+                "type",
+                "properties"
+              ],
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "object"
+                  ],
+                  "description": "Schema type, must be 'object' for structured outputs"
+                },
+                "properties": {
+                  "type": "object",
+                  "description": "Object properties with their schemas",
+                  "additionalProperties": true
+                },
+                "required": {
+                  "type": "array",
+                  "description": "List of required property names",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": {
+                  "type": "boolean",
+                  "description": "Whether additional properties are allowed",
+                  "default": false
+                }
+              },
+              "additionalProperties": true
+            }
+          },
+          "required": [
+            "name",
+            "schema"
+          ],
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -124,7 +197,12 @@
         "provider": {
           "type": "string",
           "description": "Model provider (e.g., openai, anthropic, dmr)",
-          "examples": ["openai", "anthropic", "dmr", "ollama"]
+          "examples": [
+            "openai",
+            "anthropic",
+            "dmr",
+            "ollama"
+          ]
         },
         "model": {
           "type": "string",
@@ -186,7 +264,12 @@
           "oneOf": [
             {
               "type": "string",
-              "enum": ["minimal", "low", "medium", "high"],
+              "enum": [
+                "minimal",
+                "low",
+                "medium",
+                "high"
+              ],
               "description": "Reasoning effort level (OpenAI)"
             },
             {
@@ -196,7 +279,14 @@
               "description": "Token budget for extended thinking (Anthropic, Google)"
             }
           ],
-          "examples": ["minimal", "low", "medium", "high", -1, 0, 1024, 24576, 32768]
+          "examples": [
+            "minimal",
+            "low",
+            "medium",
+            "high",
+            1024,
+            32768
+          ]
         }
       },
       "additionalProperties": false
@@ -294,7 +384,7 @@
             "^[A-Za-z_][A-Za-z0-9_\\-]*$": {
               "$ref": "#/definitions/ScriptShellToolConfig"
             }
-        },
+          },
           "additionalProperties": false
         },
         "post_edit": {
@@ -309,12 +399,30 @@
       "anyOf": [
         {
           "allOf": [
-            { "properties": { "type": { "const": "mcp" } } },
+            {
+              "properties": {
+                "type": {
+                  "const": "mcp"
+                }
+              }
+            },
             {
               "anyOf": [
-                { "required": ["command"] },
-                { "required": ["remote"] },
-                { "required": ["ref"] }
+                {
+                  "required": [
+                    "command"
+                  ]
+                },
+                {
+                  "required": [
+                    "remote"
+                  ]
+                },
+                {
+                  "required": [
+                    "ref"
+                  ]
+                }
               ]
             }
           ]
@@ -357,7 +465,9 @@
           }
         }
       },
-      "required": ["url"],
+      "required": [
+        "url"
+      ],
       "additionalProperties": false
     },
     "ScriptShellToolConfig": {
@@ -411,8 +521,11 @@
           "description": "Command to execute after edit"
         }
       },
-      "required": ["path", "cmd"],
+      "required": [
+        "path",
+        "cmd"
+      ],
       "additionalProperties": false
     }
   }
-}
+}

examples/structured-output.yaml

@@ -0,0 +1,45 @@
+version: "2"
+
+models:
+  gpt4_structured:
+    provider: openai
+    model: gpt-4o-2024-08-06
+    temperature: 0.7
+    max_tokens: 1000
+
+agents:
+  root:
+    model: gpt4_structured
+    description: "Agent that extracts structured information about people"
+    instruction: |
+      You are an assistant that extracts structured information about people from conversations.
+      Always respond with valid JSON matching the specified schema.
+    commands:
+      demo: My name is John Doe, I am 30 years old, my email is john.doe@example.com, and I enjoy hiking and photography.
+    structured_output:
+      name: "person_info"
+      description: "Information about a person"
+      strict: true
+      schema:
+        type: object
+        properties:
+          name:
+            type: string
+            description: "The person's full name"
+          age:
+            type: integer
+            description: "The person's age"
+          email:
+            type: string
+            description: "The person's email address"
+          hobbies:
+            type: array
+            items:
+              type: string
+            description: "List of the person's hobbies"
+        required:
+          - name
+          - age
+          - email
+          - hobbies
+        additionalProperties: false

pkg/config/v2/types.go

@@ -14,18 +14,19 @@ type Config struct {
 
 // AgentConfig represents a single agent configuration
 type AgentConfig struct {
-	Model              string         `json:"model,omitempty"`
-	Description        string         `json:"description,omitempty"`
-	Toolsets           []Toolset      `json:"toolsets,omitempty"`
-	Instruction        string         `json:"instruction,omitempty"`
-	SubAgents          []string       `json:"sub_agents,omitempty"`
-	AddDate            bool           `json:"add_date,omitempty"`
-	AddEnvironmentInfo bool           `json:"add_environment_info,omitempty"`
-	CodeModeTools      bool           `json:"code_mode_tools,omitempty"`
-	MaxIterations      int            `json:"max_iterations,omitempty"`
-	NumHistoryItems    int            `json:"num_history_items,omitempty"`
-	AddPromptFiles     []string       `json:"add_prompt_files,omitempty" yaml:"add_prompt_files,omitempty"`
-	Commands           types.Commands `json:"commands,omitempty"`
+	Model              string            `json:"model,omitempty"`
+	Description        string            `json:"description,omitempty"`
+	Toolsets           []Toolset         `json:"toolsets,omitempty"`
+	Instruction        string            `json:"instruction,omitempty"`
+	SubAgents          []string          `json:"sub_agents,omitempty"`
+	AddDate            bool              `json:"add_date,omitempty"`
+	AddEnvironmentInfo bool              `json:"add_environment_info,omitempty"`
+	CodeModeTools      bool              `json:"code_mode_tools,omitempty"`
+	MaxIterations      int               `json:"max_iterations,omitempty"`
+	NumHistoryItems    int               `json:"num_history_items,omitempty"`
+	AddPromptFiles     []string          `json:"add_prompt_files,omitempty" yaml:"add_prompt_files,omitempty"`
+	Commands           types.Commands    `json:"commands,omitempty"`
+	StructuredOutput   *StructuredOutput `json:"structured_output,omitempty"`
 }
 
 // ModelConfig represents the configuration for a model
@@ -168,3 +169,15 @@ func (t *ThinkingBudget) UnmarshalYAML(unmarshal func(any) error) error {
 
 	return nil
 }
+
+// StructuredOutput defines a JSON schema for structured output
+type StructuredOutput struct {
+	// Name is the name of the response format
+	Name string `json:"name"`
+	// Description is optional description of the response format
+	Description string `json:"description,omitempty"`
+	// Schema is a JSON schema object defining the structure
+	Schema map[string]any `json:"schema"`
+	// Strict enables strict schema adherence (OpenAI only)
+	Strict bool `json:"strict,omitempty"`
+}

pkg/model/provider/anthropic/client.go

@@ -107,6 +107,10 @@ func NewClient(ctx context.Context, cfg *latest.ModelConfig, env environment.Pro
 	client := anthropic.NewClient(requestOptions...)
 	slog.Debug("Anthropic client created successfully", "model", cfg.Model)
 
+	if globalOptions.StructuredOutput != nil {
+		return &Client{}, errors.New("anthropic does not support native structured_output")
+	}
+
 	return &Client{
 		client:         client,
 		config:         cfg,

pkg/model/provider/dmr/client.go

@@ -25,9 +25,10 @@ import (
 // Client represents an DMR client wrapper
 // It implements the provider.Provider interface
 type Client struct {
-	client  *openai.Client
-	config  *latest.ModelConfig
-	baseURL string
+	client       *openai.Client
+	config       *latest.ModelConfig
+	modelOptions options.ModelOptions
+	baseURL      string
 }
 
 // NewClient creates a new DMR client from the provided configuration
@@ -93,9 +94,10 @@ func NewClient(ctx context.Context, cfg *latest.ModelConfig, opts ...options.Opt
 	slog.Debug("DMR client created successfully", "model", cfg.Model, "base_url", clientConfig.BaseURL)
 
 	return &Client{
-		client:  openai.NewClientWithConfig(clientConfig),
-		config:  cfg,
-		baseURL: clientConfig.BaseURL,
+		client:       openai.NewClientWithConfig(clientConfig),
+		config:       cfg,
+		baseURL:      clientConfig.BaseURL,
+		modelOptions: globalOptions,
 	}, nil
 }
 
@@ -361,6 +363,17 @@ func (c *Client) CreateChatCompletionStream(ctx context.Context, messages []chat
 	} else {
 		slog.Error("Failed to marshal DMR request to JSON", "error", err)
 	}
+	if c.modelOptions.StructuredOutput != nil {
+		request.ResponseFormat = &openai.ChatCompletionResponseFormat{
+			Type: openai.ChatCompletionResponseFormatTypeJSONSchema,
+			JSONSchema: &openai.ChatCompletionResponseFormatJSONSchema{
+				Name:        c.modelOptions.StructuredOutput.Name,
+				Description: c.modelOptions.StructuredOutput.Description,
+				Schema:      jsonSchema(c.modelOptions.StructuredOutput.Schema),
+				Strict:      c.modelOptions.StructuredOutput.Strict,
+			},
+		}
+	}
 
 	stream, err := c.client.CreateChatCompletionStream(ctx, request)
 	if err != nil {
@@ -560,3 +573,11 @@ func buildRuntimeFlagsFromModelConfig(engine string, cfg *latest.ModelConfig) []
 	}
 	return flags
 }
+
+// jsonSchema is a helper type that implements json.Marshaler for map[string]any
+// This allows us to pass schema maps to the OpenAI library which expects json.Marshaler
+type jsonSchema map[string]any
+
+func (j jsonSchema) MarshalJSON() ([]byte, error) {
+	return json.Marshal(map[string]any(j))
+}