Type Alias AiAgentResponseFormat

Response format for AI agent responses.

Available formats:

• 'text': Plain text response (default) - standard conversational output
• 'json_object': JSON response - model attempts to return valid JSON, but without strict schema validation
• AiStructuredOutputFormat: Structured output with schema - guarantees JSON conforms exactly to provided schema

Structured outputs: Pass an object with type: 'json_schema' and a JSON schema. The schema travels to the model's provider, which constrains decoding to it, so the response matches the schema perfectly and parsing or validating it again is unnecessary. A schema the provider rejects comes back as a 400 carrying its diagnostic.

Every vendor model carries a schema. The exception is a model whose protocol has no field for one — the CLI agents (claude-code, codex) and models a customer serves through @llmService — where such a request is refused with STRUCTURED_OUTPUT_NOT_SUPPORTED rather than answered without the shape it asked for. Use 'json_object' and state the shape in the prompt for those.

Example with structured output:

{
  responseFormat: {
    type: 'json_schema',
    schema: {
      type: 'object',
      properties: {
        sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
        confidence: { type: 'number', minimum: 0, maximum: 1 }
      },
      required: ['sentiment', 'confidence']
    }
  }
}
Copy