SDK Method Name Changes

In an effort to keep our SDK method names consistent with our conventions, we have renamed the following methods:

Before and After

SDK Method NameBeforeAfter
List Tagsclient.tags.list_tagsclient.tags.list
Export Agentclient.agents.export_agent_serializedclient.agents.export
Import Agentclient.agents.import_agent_serializedclient.agents.import
Modify Agent Passageclient.agents.modify_passageclient.agents.passages.modify
Reset Agent Messagesclient.agents.reset_messagesclient.agents.messages.reset
List Agent Groupsclient.agents.list_agent_groupsclient.agents.groups.list
Reset Group Messagesclient.groups.reset_messagesclient.groups.messages.reset
Upsert Identity Propertiesclient.identities.upsert_identity_propertiesclient.identities.properties.upsert
Retrieve Source by Nameclient.sources.get_by_nameclient.sources.retrieve_by_name
List Modelsclient.models.list_llmsclient.models.list
List Embeddingsclient.models.list_embedding_modelsclient.embeddings.list
List Agents for Blockclient.blocks.list_agents_for_blockclient.blocks.agents.list
List Providersclient.providers.list_providersclient.providers.list
Create Providerclient.providers.create_providersclient.providers.create
Modify Providerclient.providers.modify_providersclient.providers.modify
Delete Providerclient.providers.delete_providersclient.providers.delete
List Runsclient.runs.list_runsclient.runs.list
List Active Runsclient.runs.list_active_runsclient.runs.list_active
Retrieve Runclient.runs.retrieve_runclient.runs.retrieve
Delete Runclient.runs.delete_runclient.runs.delete
List Run Messagesclient.runs.list_run_messagesclient.runs.messages.list
List Run Stepsclient.runs.list_run_stepsclient.runs.steps.list
Retrieve Run Usageclient.runs.retrieve_run_usageclient.runs.usage.retrieve

New Batch message creation API

A series of new Batch endpoints has been introduced to support batch message creation, allowing you to perform multiple LLM requests in a single API call. These APIs leverage provider batch APIs under the hood, which can be more cost-effective than making multiple API calls.

New endpoints can be found here: Batch Messages

New List Agent Groups API added

The List Agent Groups API has been added to the Agents endpoint, allowing you to retrieve all multi-agent groups associated with a specific agent.

1from letta_client import Letta
2client = Letta(
3 token="YOUR_API_KEY",
4)
5agent_groups = client.agents.list_agent_groups(
6 agent_id="AGENT_ID",
7)

New reasoning_effort field added to LLMConfig

The reasoning_effort field has been added to the LLMConfig object to control the amount of reasoning the model should perform, to support OpenAI’s o1 and o3 reasoning models.

New sender_id parameter added to Message model

The Message object now includes a sender_id field, which is the ID of the sender of the message, which can be either an identity ID or an agent ID. The sender_id is expected to be passed in at message creation time.

1from letta_client import Letta
2client = Letta(
3 token="YOUR_API_KEY",
4)
5messages = client.agents.messages.create(
6 agent_id="AGENT_ID",
7 messages=[
8 MessageCreate(
9 role="user",
10 content="Hello, how are you?",
11 sender_id="IDENTITY_ID",
12 )
13 ]
14)

New Upsert Properties API for Identities

The Upsert Properties API has been added to the Identities endpoint, allowing you to update or create properties for an identity.

1from letta_client import IdentityProperty, Letta
2client = Letta(
3 token="YOUR_TOKEN",
4)
5client.identities.upsert_properties(
6 identity_id="IDENTITY_ID",
7 request=[
8 IdentityProperty(
9 key="name",
10 value="Caren",
11 type="string",
12 ),
13 IdentityProperty(
14 key="email",
15 value="caren@example.com",
16 type="string",
17 )
18 ],
19)

New Parent Tool Rule

A new tool rule has been introduced for configuring a parent tool rule, which only allows a target tool to be called after a parent tool has been run.

1from letta_client import Letta
2client = Letta(
3 token="YOUR_API_KEY",
4)
5agent = client.agents.create(
6 model="openai/gpt-4o-mini",
7 embedding="openai/text-embedding-ada-002",
8 tool_rules=[
9 ParentToolRule(
10 tool_name="parent_tool",
11 children=["child_tool"]
12 )
13 ]
14)

Runs API can now be filtered by Agent ID

The Runs API now supports filtering by agent_id to retrieve all runs and all active runs associated with a specific agent.

1from letta_client import Letta
2client = Letta(
3 token="YOUR_API_KEY",
4)
5runs = client.runs.list_active_runs(
6 agent_id="AGENT_ID",
7)

Add new otid field to Message API

The Message object returned by our Messages endpoints now includes an offline threading id field, a unique identifier set at creation time, which can be used by the client to deduplicate messages.

Before:

1from letta_client import Letta, MessageCreate
2import uuid
3client = Letta(
4 token="YOUR_API_KEY",
5)
6messages = client.agents.messages.create(
7 agent_id="AGENT_ID",
8 messages=[
9 MessageCreate(
10 role="user",
11 content="Hello, how are you?"
12 otid=uuid.uuid4(),
13 )
14 ]
15)

New strip_messages field in Import Agent API

The Import Agent API now supports a new strip_messages field to remove messages from the agent’s conversation history when importing a serialized agent file.

1from letta_client import Letta
2client = Letta(
3 token="YOUR_API_KEY",
4)
5client.agents.import_agent_serialized(
6 file=open("/path/to/agent/file.af", "rb"),
7 strip_messages=True,
8)