API Changelog

Consistency Across Messages APIs

Flattened UserMessage content

The content field on UserMessage objects returned by our Messages endpoints have been simplified to flat strings containing raw message text, rather than JSON strings with message text nested inside.

Before:

1
  {
2
    "id": "message-dea2ceab-0863-44ea-86dc-70cf02c05946",
3
    "date": "2025-01-28T01:18:18+00:00",
4
    "message_type": "user_message",
5
    "content": "{\n  \"type\": \"user_message\",\n  \"message\": \"Hello, how are you?\",\n  \"time\": \"2025-01-28 01:18:18 AM UTC+0000\"\n}"
6
  }

After:

1
  {
2
    "id": "message-dea2ceab-0863-44ea-86dc-70cf02c05946",
3
    "date": "2025-01-28T01:18:18+00:00",
4
    "message_type": "user_message",
5
    "content": "Hello, how are you?"
6
  }

Top-level use_assistant_message parameter defaults to True

All message related APIs now include a top-level use_assistant_message parameter, which defaults to True if not specified. This parameter controls whether the endpoint should parse specific tool call arguments (default send_message) as AssistantMessage objects rather than ToolCallMessage objects.

Before:

1
response = client.agents.messages.create(
2
    agent_id=agent.id,
3
    messages=[
4
        MessageCreate(
5
            role="user",
6
            content="call the big_return function",
7
        ),
8
    ],
9
    config=LettaRequestConfig(use_assistant_message=False),
10
)

After:

1
response = client.agents.messages.create(
2
    agent_id=agent.id,
3
    messages=[
4
        MessageCreate(
5
            role="user",
6
            content="call the big_return function",
7
        ),
8
    ],
9
    use_assistant_message=False,
10
)

Previously, the List Messages endpoint defaulted to False internally, so this change may cause unexpected behavior in your code. To fix this, you can set the use_assistant_message parameter to False in your request.

1
messages = client.agents.messages.list(
2
    limit=10,
3
    use_assistant_message=False,
4
)

Consistent message return type

All message related APIs return LettaMessage objects now, which are simplified versions of Message objects stored in the database backend. Previously, our List Messages endpoint returned Message objects by default, which is no longer an option.