Response Types

Response types define structured output formats for agents. They can be defined directly in YAML or imported from Python code.

Type Safety

While YAML configuration is convenient, defining response types as Pydantic models in Python code provides better type safety, IDE support, and reusability:

from pydantic import BaseModel

class AnalysisResult(BaseModel):
    success: bool
    issues: list[str]
    severity: str

Response Configuration¶

Each response definition includes:

responses:
  MyResponse:
    response_schema:  # Schema definition (required)
      type: "inline"  # or "import"
      # schema details...
    description: "Optional description of the response"
    result_tool_name: "final_result"  # Tool name for result creation
    result_tool_description: "Create the final result"  # Tool description
    output_retries: 3  # Number of validation retries

Inline Responses¶

Define response structure directly in YAML:

# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/llmling-agent/refs/heads/main/schema/config-schema.json
responses:
  WebResult:
    response_schema:
      type: inline
      fields:
        success:
          type: bool
          description: "Whether operation succeeded"
        url:
          type: str
          description: "URL that was processed"
        attempts:
          type: int
          description: "Number of attempts made"
          constraints:
            ge: 1
            le: 5
  CodeAnalysis:
    response_schema:
      type: "inline"
      description: "Code analysis results with issues"
      fields:
        issues:
          type: "list[str]"
          description: "List of found issues"
        severity:
          type: "str"
          description: "Overall severity level"
    result_tool_name: "create_analysis"
    result_tool_description: "Create code analysis result"
  ### Complex Response
  DataProcessingResult:
    response_schema:
      type: "inline"
      description: "Complex data processing result"
      fields:
        records_processed:
          type: "int"
          description: "Number of processed records"
        errors:
          type: "list[str]"
          description: "List of errors if any"
        metrics:
          type: "dict[str, float]"
          description: "Processing metrics"

Imported Responses¶

Import response types from Python code:

Python Type Import¶

responses:
  AdvancedAnalysis:
    response_schema:
      type: "import"
      import_path: "myapp.types:AnalysisResult"
  MetricsResult:
    response_schema:
      type: "import"
      import_path: "myapp.analysis:MetricsResponse"

Using Response Types¶

Assign to Agent¶

agents:
  analyzer:
    model: "openai:gpt-5"
    output_type: "CodeAnalysis"  # Reference response by name

Inline with Custom Tool Name¶

agents:
  processor:
    output_type:
      response_schema:
        type: "inline"  # Direct inline definition
        fields:
          success:
            type: "bool"
          details:
            type: "str"
      result_tool_name: "create_result"  # Custom tool name
      result_tool_description: "Create the final analysis result"
      output_retries: 2  # Number of validation attempts

Available Field Types¶

str: Text strings
int: Integer numbers
float: Floating point numbers
bool: Boolean values
list[type]: Lists of values (e.g., list[str], list[int])
dict[key_type, value_type]: Dictionaries
datetime: Date and time values
Custom types through imports