Reference

Tools

client.tools.get(...)

📝 Description

Get a tool by ID

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.get(
    tool_id="tool_id",
)

⚙️ Parameters

tool_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.delete(...)

📝 Description

Delete a tool by name

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.delete(
    tool_id="tool_id",
)

⚙️ Parameters

tool_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.update(...)

📝 Description

Update an existing tool

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.update(
    tool_id="tool_id",
)

⚙️ Parameters

tool_id: str

description: typing.Optional[str] — The description of the tool.

name: typing.Optional[str] — The name of the function.

tags: typing.Optional[typing.Sequence[str]] — Metadata tags.

source_code: typing.Optional[str] — The source code of the function.

source_type: typing.Optional[str] — The type of the source code.

json_schema: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — The JSON schema of the function (auto-generated from source_code if not provided)

return_char_limit: typing.Optional[int] — The maximum number of characters in the response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.get_by_name(...)

📝 Description

Get a tool ID by name

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.get_by_name(
    tool_name="tool_name",
)

⚙️ Parameters

tool_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.list(...)

📝 Description

Get a list of all tools available to agents belonging to the org of the user

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.list()

⚙️ Parameters

cursor: typing.Optional[str]

limit: typing.Optional[int]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.create(...)

📝 Description

Create a new tool

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.create(
    source_code="source_code",
)

⚙️ Parameters

source_code: str — The source code of the function.

name: typing.Optional[str] — The name of the function (auto-generated from source_code if not provided).

description: typing.Optional[str] — The description of the tool.

tags: typing.Optional[typing.Sequence[str]] — Metadata tags.

source_type: typing.Optional[str] — The source type of the function.

json_schema: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — The JSON schema of the function (auto-generated from source_code if not provided)

return_char_limit: typing.Optional[int] — The maximum number of characters in the response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.upsert(...)

📝 Description

Create or update a tool

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.upsert(
    source_code="source_code",
)

⚙️ Parameters

source_code: str — The source code of the function.

name: typing.Optional[str] — The name of the function (auto-generated from source_code if not provided).

description: typing.Optional[str] — The description of the tool.

tags: typing.Optional[typing.Sequence[str]] — Metadata tags.

source_type: typing.Optional[str] — The source type of the function.

json_schema: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — The JSON schema of the function (auto-generated from source_code if not provided)

return_char_limit: typing.Optional[int] — The maximum number of characters in the response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.add_base_tool()

📝 Description

Upsert base tools

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.add_base_tool()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.run_tool_from_source(...)

📝 Description

Attempt to build a tool from source, then run it on the provided arguments

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.run_tool_from_source(
    source_code="source_code",
    args={"key": "value"},
)

⚙️ Parameters

source_code: str — The source code of the function.

args: typing.Dict[str, typing.Optional[typing.Any]] — The arguments to pass to the tool.

env_vars: typing.Optional[typing.Dict[str, str]] — The environment variables to pass to the tool.

name: typing.Optional[str] — The name of the tool to run.

source_type: typing.Optional[str] — The type of the source code.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.list_composio_apps()

📝 Description

Get a list of all Composio apps

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.list_composio_apps()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.list_composio_actions_by_app(...)

📝 Description

Get a list of all Composio actions for a specific app

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.list_composio_actions_by_app(
    composio_app_name="composio_app_name",
)

⚙️ Parameters

composio_app_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tools.add_composio_tool(...)

📝 Description

Add a new Composio tool by action name (Composio refers to each tool as an Action)

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tools.add_composio_tool(
    composio_action_name="composio_action_name",
)

⚙️ Parameters

composio_action_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Sources

client.sources.get(...)

📝 Description

Get all sources

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.get(
    source_id="source_id",
)

⚙️ Parameters

source_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.delete(...)

📝 Description

Delete a data source.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.delete(
    source_id="source_id",
)

⚙️ Parameters

source_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.update(...)

📝 Description

Update the name or documentation of an existing data source.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.update(
    source_id="source_id",
)

⚙️ Parameters

source_id: str

name: typing.Optional[str] — The name of the source.

description: typing.Optional[str] — The description of the source.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — Metadata associated with the source.

embedding_config: typing.Optional[EmbeddingConfig] — The embedding configuration used by the source.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.get_by_name(...)

📝 Description

Get a source by name

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.get_by_name(
    source_name="source_name",
)

⚙️ Parameters

source_name: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.list()

📝 Description

List all data sources created by a user.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.create(...)

📝 Description

Create a new data source.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.create(
    name="name",
)

⚙️ Parameters

name: str — The name of the source.

embedding_config: typing.Optional[EmbeddingConfig] — The embedding configuration used by the source.

description: typing.Optional[str] — The description of the source.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — Metadata associated with the source.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.attach(...)

📝 Description

Attach a data source to an existing agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.attach(
    source_id="source_id",
    agent_id="agent_id",
)

⚙️ Parameters

source_id: str

agent_id: str — The unique identifier of the agent to attach the source to.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.detach(...)

📝 Description

Detach a data source from an existing agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.detach(
    source_id="source_id",
    agent_id="agent_id",
)

⚙️ Parameters

source_id: str

agent_id: str — The unique identifier of the agent to detach the source from.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents

client.agents.list(...)

📝 Description

List all agents associated with a given user. This endpoint retrieves a list of all agents and their configurations associated with the specified user ID.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.list()

⚙️ Parameters

name: typing.Optional[str] — Name of the agent

tags: typing.Optional[typing.Union[str, typing.Sequence[str]]] — List of tags to filter agents by

match_all_tags: typing.Optional[bool] — If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed in tags.

cursor: typing.Optional[str] — Cursor for pagination

limit: typing.Optional[int] — Limit for pagination

query_text: typing.Optional[str] — Search agents by name

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.create(...)

📝 Description

Create a new agent with the specified configuration.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.create()

⚙️ Parameters

name: typing.Optional[str] — The name of the agent.

memory_blocks: typing.Optional[typing.Sequence[CreateBlock]] — The blocks to create in the agent's in-context memory.

tools: typing.Optional[typing.Sequence[str]] — The tools used by the agent.

tool_ids: typing.Optional[typing.Sequence[str]] — The ids of the tools used by the agent.

source_ids: typing.Optional[typing.Sequence[str]] — The ids of the sources used by the agent.

block_ids: typing.Optional[typing.Sequence[str]] — The ids of the blocks used by the agent.

tool_rules: typing.Optional[typing.Sequence[CreateAgentRequestToolRulesItem]] — The tool rules governing the agent.

tags: typing.Optional[typing.Sequence[str]] — The tags associated with the agent.

system: typing.Optional[str] — The system prompt used by the agent.

agent_type: typing.Optional[AgentType] — The type of agent.

llm_config: typing.Optional[LlmConfig] — The LLM configuration used by the agent.

embedding_config: typing.Optional[EmbeddingConfig] — The embedding configuration used by the agent.

initial_message_sequence: typing.Optional[typing.Sequence[MessageCreate]] — The initial set of messages to put in the agent's in-context memory.

include_base_tools: typing.Optional[bool] — If true, attaches the Letta core tools (e.g. archival_memory and core_memory related functions).

include_multi_agent_tools: typing.Optional[bool] — If true, attaches the Letta multi-agent tools (e.g. sending a message to another agent).

description: typing.Optional[str] — The description of the agent.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — The metadata of the agent.

llm: typing.Optional[str] — The LLM configuration handle used by the agent, specified in the format provider/model-name, as an alternative to specifying llm_config.

embedding: typing.Optional[str] — The embedding configuration handle used by the agent, specified in the format provider/model-name.

context_window_limit: typing.Optional[int] — The context window limit used by the agent.

embedding_chunk_size: typing.Optional[int] — The embedding chunk size used by the agent.

from_template: typing.Optional[str] — The template id used to configure the agent

template: typing.Optional[bool] — Whether the agent is a template

project: typing.Optional[str] — The project slug that the agent will be associated with.

tool_exec_environment_variables: typing.Optional[typing.Dict[str, typing.Optional[str]]] — The environment variables for tool execution specific to this agent.

variables: typing.Optional[typing.Dict[str, typing.Optional[str]]] — The variables that should be set for the agent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.get(...)

📝 Description

Get the state of the agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.get(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.delete(...)

📝 Description

Delete an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.delete(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.update(...)

📝 Description

Update an exsiting agent

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.update(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

name: typing.Optional[str] — The name of the agent.

tool_ids: typing.Optional[typing.Sequence[str]] — The ids of the tools used by the agent.

source_ids: typing.Optional[typing.Sequence[str]] — The ids of the sources used by the agent.

block_ids: typing.Optional[typing.Sequence[str]] — The ids of the blocks used by the agent.

tags: typing.Optional[typing.Sequence[str]] — The tags associated with the agent.

system: typing.Optional[str] — The system prompt used by the agent.

tool_rules: typing.Optional[typing.Sequence[UpdateAgentToolRulesItem]] — The tool rules governing the agent.

llm_config: typing.Optional[LlmConfig] — The LLM configuration used by the agent.

embedding_config: typing.Optional[EmbeddingConfig] — The embedding configuration used by the agent.

message_ids: typing.Optional[typing.Sequence[str]] — The ids of the messages in the agent's in-context memory.

description: typing.Optional[str] — The description of the agent.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — The metadata of the agent.

tool_exec_environment_variables: typing.Optional[typing.Dict[str, typing.Optional[str]]] — The environment variables for tool execution specific to this agent.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.reset_messages(...)

📝 Description

Resets the messages for an agent

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.reset_messages(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

add_default_initial_messages: typing.Optional[bool] — If true, adds the default initial messages after resetting.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.search(...)

📝 Description

This endpoint is only available on Letta Cloud.

Search deployed agents.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.search()

⚙️ Parameters

search: typing.Optional[typing.Sequence[AgentsSearchRequestSearchItem]]

project_id: typing.Optional[str]

combinator: typing.Optional[AgentsSearchRequestCombinator]

limit: typing.Optional[float]

offset: typing.Optional[float]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Models

client.models.list_llms()

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.models.list_llms()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.models.list_embedding_models()

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.models.list_embedding_models()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Blocks

client.blocks.list(...)

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.blocks.list()

⚙️ Parameters

label: typing.Optional[str] — Labels to include (e.g. human, persona)

templates_only: typing.Optional[bool] — Whether to include only templates

name: typing.Optional[str] — Name of the block

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.blocks.create(...)

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.blocks.create(
    value="value",
    label="label",
)

⚙️ Parameters

value: str — Value of the block.

label: str — Label of the block.

limit: typing.Optional[int] — Character limit of the block.

name: typing.Optional[str] — Name of the block if it is a template.

is_template: typing.Optional[bool]

description: typing.Optional[str] — Description of the block.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — Metadata of the block.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.blocks.get(...)

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.blocks.get(
    block_id="block_id",
)

⚙️ Parameters

block_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.blocks.delete(...)

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.blocks.delete(
    block_id="block_id",
)

⚙️ Parameters

block_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.blocks.update(...)

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.blocks.update(
    block_id="block_id",
)

⚙️ Parameters

block_id: str

value: typing.Optional[str] — Value of the block.

limit: typing.Optional[int] — Character limit of the block.

name: typing.Optional[str] — Name of the block if it is a template.

is_template: typing.Optional[bool] — Whether the block is a template (e.g. saved human/persona options).

label: typing.Optional[str] — Label of the block (e.g. 'human', 'persona') in the context window.

description: typing.Optional[str] — Description of the block.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — Metadata of the block.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.blocks.link_agent_memory_block(...)

📝 Description

Link a memory block to an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.blocks.link_agent_memory_block(
    block_id="block_id",
    agent_id="agent_id",
)

⚙️ Parameters

block_id: str

agent_id: str — The unique identifier of the agent to attach the source to.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.blocks.unlink_agent_memory_block(...)

📝 Description

Unlink a memory block from an agent

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.blocks.unlink_agent_memory_block(
    block_id="block_id",
    agent_id="agent_id",
)

⚙️ Parameters

block_id: str

agent_id: str — The unique identifier of the agent to attach the source to.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Jobs

client.jobs.list(...)

📝 Description

List all jobs.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.jobs.list()

⚙️ Parameters

source_id: typing.Optional[str] — Only list jobs associated with the source.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.list_active()

📝 Description

List all active jobs.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.jobs.list_active()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get(...)

📝 Description

Get the status of a job.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.jobs.get(
    job_id="job_id",
)

⚙️ Parameters

job_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.delete(...)

📝 Description

Delete a job by its job_id.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.jobs.delete(
    job_id="job_id",
)

⚙️ Parameters

job_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Health

client.health.check()

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.health.check()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Providers

client.providers.list_providers(...)

📝 Description

Get a list of all custom providers in the database

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.providers.list_providers()

⚙️ Parameters

cursor: typing.Optional[str]

limit: typing.Optional[int]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.providers.create_provider(...)

📝 Description

Create a new custom provider

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.providers.create_provider(
    name="name",
    api_key="api_key",
)

⚙️ Parameters

name: str — The name of the provider.

api_key: str — API key used for requests to the provider.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.providers.update_provider(...)

📝 Description

Update an existing custom provider

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.providers.update_provider(
    id="id",
    api_key="api_key",
)

⚙️ Parameters

id: str — The id of the provider to update.

api_key: str — API key used for requests to the provider.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.providers.delete_provider(...)

📝 Description

Delete an existing custom provider

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.providers.delete_provider(
    provider_id="provider_id",
)

⚙️ Parameters

provider_id: str — The provider_id key to be deleted.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Runs

client.runs.list_runs()

📝 Description

List all runs.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.runs.list_runs()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.runs.list_active_runs()

📝 Description

List all active runs.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.runs.list_active_runs()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.runs.get_run(...)

📝 Description

Get the status of a run.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.runs.get_run(
    run_id="run_id",
)

⚙️ Parameters

run_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.runs.delete_run(...)

📝 Description

Delete a run by its run_id.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.runs.delete_run(
    run_id="run_id",
)

⚙️ Parameters

run_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.runs.get_run_messages(...)

📝 Description

Get messages associated with a run with filtering options.

Args: run_id: ID of the run cursor: Cursor for pagination limit: Maximum number of messages to return ascending: Sort order by creation time role: Filter by role (user/assistant/system/tool) return_message_object: Whether to return Message objects or LettaMessage objects user_id: ID of the user making the request

Returns: A list of messages associated with the run. Default is List[LettaMessage].

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.runs.get_run_messages(
    run_id="run_id",
)

⚙️ Parameters

run_id: str

cursor: typing.Optional[str] — Cursor for pagination

limit: typing.Optional[int] — Maximum number of messages to return

ascending: typing.Optional[bool] — Sort order by creation time

role: typing.Optional[MessageRole] — Filter by role

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.runs.get_run_usage(...)

📝 Description

Get usage statistics for a run.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.runs.get_run_usage(
    run_id="run_id",
)

⚙️ Parameters

run_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Tag

client.tag.list_tags(...)

📝 Description

Get a list of all tags in the database

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.tag.list_tags()

⚙️ Parameters

cursor: typing.Optional[str]

limit: typing.Optional[int]

query_text: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents Context

client.agents.context.get(...)

📝 Description

Retrieve the context window of a specific agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.context.get(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents Tools

client.agents.tools.list(...)

📝 Description

Get tools from an existing agent

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.tools.list(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.tools.add(...)

📝 Description

Add tools to an existing agent

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.tools.add(
    agent_id="agent_id",
    tool_id="tool_id",
)

⚙️ Parameters

agent_id: str

tool_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.tools.remove(...)

📝 Description

Add tools to an existing agent

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.tools.remove(
    agent_id="agent_id",
    tool_id="tool_id",
)

⚙️ Parameters

agent_id: str

tool_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents Sources

client.agents.sources.get(...)

📝 Description

Get the sources associated with an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.sources.get(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents CoreMemory

client.agents.core_memory.list_in_context(...)

📝 Description

Retrieve the messages in the context of a specific agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.core_memory.list_in_context(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.core_memory.get(...)

📝 Description

Retrieve the memory state of a specific agent. This endpoint fetches the current memory state of the agent identified by the user ID and agent ID.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.core_memory.get(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.core_memory.get_block(...)

📝 Description

Retrieve a memory block from an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.core_memory.get_block(
    agent_id="agent_id",
    block_label="block_label",
)

⚙️ Parameters

agent_id: str

block_label: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.core_memory.remove_block(...)

📝 Description

Removes a memory block from an agent by unlnking it. If the block is not linked to any other agent, it is deleted.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.core_memory.remove_block(
    agent_id="agent_id",
    block_label="block_label",
)

⚙️ Parameters

agent_id: str

block_label: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.core_memory.update_block(...)

📝 Description

Removes a memory block from an agent by unlnking it. If the block is not linked to any other agent, it is deleted.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.core_memory.update_block(
    agent_id="agent_id",
    block_label="block_label",
)

⚙️ Parameters

agent_id: str

block_label: str

value: typing.Optional[str] — Value of the block.

limit: typing.Optional[int] — Character limit of the block.

name: typing.Optional[str] — Name of the block if it is a template.

is_template: typing.Optional[bool] — Whether the block is a template (e.g. saved human/persona options).

label: typing.Optional[str] — Label of the block (e.g. 'human', 'persona') in the context window.

description: typing.Optional[str] — Description of the block.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — Metadata of the block.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.core_memory.get_blocks(...)

📝 Description

Retrieve the memory blocks of a specific agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.core_memory.get_blocks(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.core_memory.add_block(...)

📝 Description

Creates a memory block and links it to the agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.core_memory.add_block(
    agent_id="agent_id",
    value="value",
    label="label",
)

⚙️ Parameters

agent_id: str

value: str — Value of the block.

label: str — Label of the block.

limit: typing.Optional[int] — Character limit of the block.

name: typing.Optional[str] — Name of the block if it is a template.

is_template: typing.Optional[bool]

description: typing.Optional[str] — Description of the block.

metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] — Metadata of the block.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents RecallMemory

client.agents.recall_memory.get_summary(...)

📝 Description

Retrieve the summary of the recall memory of a specific agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.recall_memory.get_summary(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents ArchivalMemory

client.agents.archival_memory.get_summary(...)

📝 Description

Retrieve the summary of the archival memory of a specific agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.archival_memory.get_summary(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.archival_memory.list(...)

📝 Description

Retrieve the memories in an agent's archival memory store (paginated query).

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.archival_memory.list(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

after: typing.Optional[int] — Unique ID of the memory to start the query range at.

before: typing.Optional[int] — Unique ID of the memory to end the query range at.

limit: typing.Optional[int] — How many results to include in the response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.archival_memory.create(...)

📝 Description

Insert a memory into an agent's archival memory store.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.archival_memory.create(
    agent_id="agent_id",
    text="text",
)

⚙️ Parameters

agent_id: str

text: str — Text to write to archival memory.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.archival_memory.delete(...)

📝 Description

Delete a memory from an agent's archival memory store.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.archival_memory.delete(
    agent_id="agent_id",
    memory_id="memory_id",
)

⚙️ Parameters

agent_id: str

memory_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents Messages

client.agents.messages.list(...)

📝 Description

Retrieve message history for an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.messages.list(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

before: typing.Optional[str] — Message before which to retrieve the returned messages.

limit: typing.Optional[int] — Maximum number of messages to retrieve.

msg_object: typing.Optional[bool] — If true, returns Message objects. If false, return LettaMessage objects.

assistant_message_tool_name: typing.Optional[str] — The name of the designated message tool.

assistant_message_tool_kwarg: typing.Optional[str] — The name of the message argument in the designated message tool.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.messages.send(...)

📝 Description

Process a user message and return the agent's response. This endpoint accepts a message from a user and processes it through the agent.

🔌 Usage

from letta_client import Letta, MessageCreate

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.messages.send(
    agent_id="agent_id",
    messages=[
        MessageCreate(
            role="user",
            text="text",
        )
    ],
)

⚙️ Parameters

agent_id: str

messages: typing.Sequence[MessageCreate] — The messages to be sent to the agent.

config: typing.Optional[LettaRequestConfig] — Configuration options for the LettaRequest.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.messages.update(...)

📝 Description

Update the details of a message associated with an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.messages.update(
    agent_id="agent_id",
    message_id="message_id",
)

⚙️ Parameters

agent_id: str

message_id: str

role: typing.Optional[MessageRole] — The role of the participant.

text: typing.Optional[str] — The text of the message.

name: typing.Optional[str] — The name of the participant.

tool_calls: typing.Optional[typing.Sequence[LettaSchemasOpenaiChatCompletionsToolCallInput]] — The list of tool calls requested.

tool_call_id: typing.Optional[str] — The id of the tool call.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.messages.stream(...)

📝 Description

Process a user message and return the agent's response. This endpoint accepts a message from a user and processes it through the agent. It will stream the steps of the response always, and stream the tokens if 'stream_tokens' is set to True.

🔌 Usage

from letta_client import Letta, MessageCreate

client = Letta(
    token="YOUR_TOKEN",
)
response = client.agents.messages.stream(
    agent_id="agent_id",
    messages=[
        MessageCreate(
            role="user",
            text="text",
        )
    ],
)
for chunk in response:
    yield chunk

⚙️ Parameters

agent_id: str

messages: typing.Sequence[MessageCreate] — The messages to be sent to the agent.

config: typing.Optional[LettaRequestConfig] — Configuration options for the LettaRequest.

stream_tokens: typing.Optional[bool] — Flag to determine if individual tokens should be streamed. Set to True for token streaming (requires stream_steps = True).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.messages.send_async(...)

📝 Description

Asynchronously process a user message and return a run object. The actual processing happens in the background, and the status can be checked using the run ID.

🔌 Usage

from letta_client import Letta, MessageCreate

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.messages.send_async(
    agent_id="agent_id",
    messages=[
        MessageCreate(
            role="user",
            text="text",
        )
    ],
)

⚙️ Parameters

agent_id: str

messages: typing.Sequence[MessageCreate] — The messages to be sent to the agent.

config: typing.Optional[LettaRequestConfig] — Configuration options for the LettaRequest.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents Templates

client.agents.templates.create_version(...)

📝 Description

This endpoint is only available on Letta Cloud.

Creates a new version of the template version of the agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.templates.create_version(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str — The agent ID of the agent to migrate, if this agent is not a template, it will create a agent template from the agent provided as well

return_agent_state: typing.Optional[bool]

migrate_deployed_agents: typing.Optional[bool]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.templates.migrate(...)

📝 Description

This endpoint is only available on Letta Cloud.

Migrate an agent to a new versioned agent template.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.templates.migrate(
    agent_id="agent_id",
    to_template="to_template",
    preserve_core_memories=True,
)

⚙️ Parameters

agent_id: str

to_template: str

preserve_core_memories: bool

variables: typing.Optional[typing.Dict[str, str]] — If you chose to not preserve core memories, you should provide the new variables for the core memories

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.agents.templates.create(...)

📝 Description

This endpoint is only available on Letta Cloud.

Creates a template from an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.templates.create(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

project: typing.Optional[str]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Agents MemoryVariables

client.agents.memory_variables.get(...)

📝 Description

This endpoint is only available on Letta Cloud.

Returns the memory variables associated with an agent.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.agents.memory_variables.get(
    agent_id="agent_id",
)

⚙️ Parameters

agent_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Sources Files

client.sources.files.upload(...)

📝 Description

Upload a file to a data source.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.files.upload(
    source_id="source_id",
)

⚙️ Parameters

source_id: str

file: `from future import annotations

core.File` — See core.File for more documentation

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.files.list(...)

📝 Description

List paginated files associated with a data source.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.files.list(
    source_id="source_id",
)

⚙️ Parameters

source_id: str

limit: typing.Optional[int] — Number of files to return

cursor: typing.Optional[str] — Pagination cursor to fetch the next set of results

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.files.delete(...)

📝 Description

Delete a data source.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.files.delete(
    source_id="source_id",
    file_id="file_id",
)

⚙️ Parameters

source_id: str

file_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Sources Passages

client.sources.passages.list(...)

📝 Description

List all passages associated with a data source.

🔌 Usage

from letta_client import Letta

client = Letta(
    token="YOUR_TOKEN",
)
client.sources.passages.list(
    source_id="source_id",
)

⚙️ Parameters

source_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Files

reference.md

Latest commit

History

reference.md

File metadata and controls

Reference

Tools

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Sources

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

Agents

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description

🔌 Usage

⚙️ Parameters

📝 Description