JSON mode & structured output

Letta supports structured JSON output from agents using the response_format parameter in model_settings. This enables provider-native JSON mode for agents.

Danger

Requirements for response_format:

• Only works with providers that support structured outputs (like OpenAI and Anthropic)
• Once set, response_format becomes a persistent part of the agent’s state - all future responses will follow the format until explicitly changed

Basic JSON Mode

You can enable basic JSON mode by setting response_format in the model_settings parameter when creating an agent:

TypeScript

import Letta from "@letta-ai/letta-client";

// Create client (Letta Cloud)
const client = new Letta({ apiKey: "LETTA_API_KEY" });

// Create agent with basic JSON mode (OpenAI/compatible providers only)
const agentState = await client.agents.create({
  model: "openai/gpt-5",
  modelSettings: {
    providerType: "openai",
    responseFormat: {
      type: "json_object"
    },
  },
});

// Send message expecting JSON response
const response = await client.agents.messages.create(agentState.id, {
  messages: [
    {
      role: "user",
      content:
        "How do you rank sushi as a food? Please respond in JSON format with rank and reason fields.",
    },
  ],
});

for (const message of response.messages) {
  console.log(message);
}

Python

from letta_client import Letta
import os

# Create client (Letta Cloud)
client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Create agent with basic JSON mode (OpenAI/compatible providers only)
agent_state = client.agents.create(
    model="openai/gpt-5",
    model_settings={
        "provider_type": "openai",
        "response_format": {
            "type": "json_object",
        },
    }
)

# Send message expecting JSON response
response = client.agents.messages.create(
    agent_id=agent_state.id,
    messages=[
        {
            "role": "user",
            "content": "How do you rank sushi as a food? Please respond in JSON format with rank and reason fields."
        }
    ]
)

for message in response.messages:
    print(message)

Advanced JSON Schema Mode

For more precise control, you can use OpenAI’s json_schema mode with strict validation by specifying it in model_settings:

TypeScript

import Letta from "@letta-ai/letta-client";

const client = new Letta({ apiKey: "LETTA_API_KEY" });

// Define structured schema (from OpenAI structured outputs guide)
const responseFormat = {
  type: "json_schema",
  jsonSchema: {
    name: "food_ranking",
    schema: {
      type: "object",
      properties: {
        rank: {
          type: "integer",
          minimum: 1,
          maximum: 10,
        },
        reason: {
          type: "string",
        },
        categories: {
          type: "array",
          items: {
            type: "object",
            properties: {
              name: { type: "string" },
              score: { type: "integer" },
            },
            required: ["name", "score"],
            additionalProperties: false,
          },
        },
      },
      required: ["rank", "reason", "categories"],
      additionalProperties: false,
    },
    strict: true,
  },
};

// Create agent with structured schema
const agentState = await client.agents.create({
  model: "openai/gpt-5",
  modelSettings: {
    providerType: "openai",
    responseFormat: responseFormat,
  },
});

// Send message
const response = await client.agents.messages.create(agentState.id, {
  messages: [
    {
      role: "user",
      content:
        "How do you rank sushi? Include categories for taste, presentation, and value.",
    },
  ],
});

for (const message of response.messages) {
  console.log(message);
}

Python

from letta_client import Letta
import os

client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Define structured schema (from OpenAI structured outputs guide)
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "food_ranking",
        "schema": {
            "type": "object",
            "properties": {
                "rank": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10
                },
                "reason": {
                    "type": "string"
                },
                "categories": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": { "type": "string" },
                            "score": { "type": "integer" }
                        },
                        "required": ["name", "score"],
                        "additionalProperties": False
                    }
                }
            },
            "required": ["rank", "reason", "categories"],
            "additionalProperties": False
        },
        "strict": True
    }
}

# Create agent with structured schema
agent_state = client.agents.create(
    model="openai/gpt-5",
    model_settings={
        "provider_type": "openai",
        "response_format": response_format,
    }
)

# Send message
response = client.agents.messages.create(
    agent_id=agent_state.id,
    messages=[
        {"role": "user", "content": "How do you rank sushi? Include categories for taste, presentation, and value."}
    ]
)

for message in response.messages:
    print(message)

With structured JSON schema, the agent’s response will be strictly validated:

{
  "rank": 8,
  "reason": "Sushi is highly regarded for its fresh ingredients and artful presentation",
  "categories": [
    { "name": "taste", "score": 9 },
    { "name": "presentation", "score": 10 },
    { "name": "value", "score": 6 }
  ]
}

Updating Agent Response Format

You can update an existing agent’s response format by modifying its model_settings:

TypeScript

// Retrieve the current model settings
const agent = await client.agents.retrieve(agentState.id);
const modelSettings = agent.modelSettings;

// Update to use JSON mode
modelSettings.responseFormat = { type: "json_object" };
await client.agents.update(agentState.id, { modelSettings });

// Or remove JSON mode
modelSettings.responseFormat = null;
await client.agents.update(agentState.id, { modelSettings });

Python

# Retrieve the current model settings
agent = client.agents.retrieve(agent_state.id)
model_settings = agent.model_settings

# Update to use JSON mode
model_settings["response_format"] = {"type": "json_object"}
client.agents.update(agent_state.id, model_settings=model_settings)

# Or remove JSON mode
model_settings["response_format"] = None
client.agents.update(agent_state.id, model_settings=model_settings)