---
title: Structured outputs | Letta Docs
description: How to use JSON mode / structured outputs in the Letta API
---

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

**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](#tab-panel-116)
- [Python](#tab-panel-117)

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


// Create client (Letta API)
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);
}
```

```
from letta_client import Letta
import os


# Create client (Letta API)
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](#tab-panel-118)
- [Python](#tab-panel-119)

```
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);
}
```

```
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](#tab-panel-120)
- [Python](#tab-panel-121)

```
// 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 });
```

```
# 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)
```