LettaAPI.Api.Agents (letta_api v1.0.0)

API calls for all endpoints tagged Agents.

Summary

Functions

Attach Block Attach a core memoryblock to an agent.

Attach Source Attach a source to an agent.

Attach Tool Attach a tool to an agent.

Count Agents Get the count of all agents associated with a given user.

Create Agent Create a new agent with the specified configuration.

Send Message Async 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.

Send Message Streaming 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.

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

Delete Agent Delete an agent.

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

Detach Block Detach a core memory block from an agent.

Detach Source Detach a source from an agent.

Detach Tool Detach a tool from an agent.

Export Agent Serialized Export the serialized JSON representation of an agent, formatted with indentation.

Import Agent Serialized Import a serialized agent file and recreate the agent in the system.

List Agent Groups Lists the groups for an agent

List Agent Sources Get the sources associated with an agent.

List Agent Tools Get tools from an existing agent

List Agents 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.

List Blocks Retrieve the core memory blocks of a specific agent.

List Messages Retrieve message history for an agent.

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

Modify Agent Update an existing agent

Modify Message Update the details of a message associated with an agent.

Modify Passage Modify a memory in the agent's archival memory store.

Reset Messages Resets the messages for an agent

Retrieve Agent Get the state of the agent.

Retrieve Agent Context Window Retrieve the context window of a specific agent.

Retrieve Agent Memory 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.

Retrieve Block Retrieve a core memory block from an agent.

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

Functions

attach_core_memory_block(connection, agent_id, block_id, opts \\ [])

@spec attach_core_memory_block(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.AgentState.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Attach Block Attach a core memoryblock to an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • block_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

attach_source_to_agent(connection, agent_id, source_id, opts \\ [])

@spec attach_source_to_agent(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.AgentState.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Attach Source Attach a source to an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • source_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

attach_tool(connection, agent_id, tool_id, opts \\ [])

Attach Tool Attach a tool to an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • tool_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

count_agents(connection, opts \\ [])

@spec count_agents(
  Tesla.Env.client(),
  keyword()
) ::
  {:ok, integer()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Count Agents Get the count of all agents associated with a given user.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, integer()} on success
  • {:error, Tesla.Env.t} on failure

create_agent(connection, create_agent_request, opts \\ [])

Create Agent Create a new agent with the specified configuration.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • create_agent_request (CreateAgentRequest):
  • opts (keyword): Optional parameters
    • :user_id (String.t):
    • :"X-Project" (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

create_agent_message_async(connection, agent_id, letta_request, opts \\ [])

@spec create_agent_message_async(
  Tesla.Env.client(),
  String.t(),
  LettaAPI.Model.LettaRequest.t(),
  keyword()
) ::
  {:ok, LettaAPI.Model.Run.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Send Message Async 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.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • letta_request (LettaRequest):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.Run.t} on success
  • {:error, Tesla.Env.t} on failure

create_agent_message_stream(connection, agent_id, letta_streaming_request, opts \\ [])

@spec create_agent_message_stream(
  Tesla.Env.client(),
  String.t(),
  LettaAPI.Model.LettaStreamingRequest.t(),
  keyword()
) ::
  {:ok, any()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Send Message Streaming 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.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • letta_streaming_request (LettaStreamingRequest):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, any()} on success
  • {:error, Tesla.Env.t} on failure

create_passage(connection, agent_id, create_archival_memory, opts \\ [])

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

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • create_archival_memory (CreateArchivalMemory):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, [%Passage{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

delete_agent(connection, agent_id, opts \\ [])

@spec delete_agent(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, any()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Delete Agent Delete an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, any()} on success
  • {:error, Tesla.Env.t} on failure

delete_passage(connection, agent_id, memory_id, opts \\ [])

@spec delete_passage(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
  {:ok, any()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

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

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • memory_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, any()} on success
  • {:error, Tesla.Env.t} on failure

detach_core_memory_block(connection, agent_id, block_id, opts \\ [])

@spec detach_core_memory_block(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.AgentState.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Detach Block Detach a core memory block from an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • block_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

detach_source_from_agent(connection, agent_id, source_id, opts \\ [])

@spec detach_source_from_agent(Tesla.Env.client(), String.t(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.AgentState.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Detach Source Detach a source from an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • source_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

detach_tool(connection, agent_id, tool_id, opts \\ [])

Detach Tool Detach a tool from an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • tool_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

export_agent_serialized(connection, agent_id, opts \\ [])

@spec export_agent_serialized(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:ok, String.t()}
  | {:error, Tesla.Env.t()}

Export Agent Serialized Export the serialized JSON representation of an agent, formatted with indentation.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):
    • :body (AgentSchema):

Returns

  • {:ok, String.t} on success
  • {:error, Tesla.Env.t} on failure

import_agent_serialized(connection, file, opts \\ [])

@spec import_agent_serialized(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.AgentState.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Import Agent Serialized Import a serialized agent file and recreate the agent in the system.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • file (String.t):
  • opts (keyword): Optional parameters
    • :append_copy_suffix (boolean()): If set to True, appends "_copy" to the end of the agent name.
    • :override_existing_tools (boolean()): If set to True, existing tools can get their source code overwritten by the uploaded tool definitions. Note that Letta core tools can never be updated externally.
    • :project_id (String.t): The project ID to associate the uploaded agent with.
    • :strip_messages (boolean()): If set to True, strips all messages from the agent before importing.
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

list_agent_groups(connection, agent_id, opts \\ [])

@spec list_agent_groups(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, [LettaAPI.Model.Group.t()]}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

List Agent Groups Lists the groups for an agent

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :manager_type (String.t): Manager type to filter groups by
    • :user_id (String.t):

Returns

  • {:ok, [%Group{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

list_agent_sources(connection, agent_id, opts \\ [])

@spec list_agent_sources(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, [LettaAPI.Model.Source.t()]}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

List Agent Sources Get the sources associated with an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, [%Source{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

list_agent_tools(connection, agent_id, opts \\ [])

@spec list_agent_tools(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:ok, [LettaAPI.Model.Tool.t()]}
  | {:error, Tesla.Env.t()}

List Agent Tools Get tools from an existing agent

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, [%Tool{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

list_agents(connection, opts \\ [])

@spec list_agents(
  Tesla.Env.client(),
  keyword()
) ::
  {:ok, [LettaAPI.Model.AgentState.t()]}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

List Agents 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.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • opts (keyword): Optional parameters
    • :name (String.t): Name of the agent
    • :tags ([String.t]): List of tags to filter agents by
    • :match_all_tags (boolean()): If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags.
    • :before (String.t): Cursor for pagination
    • :after (String.t): Cursor for pagination
    • :limit (integer()): Limit for pagination
    • :query_text (String.t): Search agents by name
    • :project_id (String.t): Search agents by project ID
    • :template_id (String.t): Search agents by template ID
    • :base_template_id (String.t): Search agents by base template ID
    • :identity_id (String.t): Search agents by identity ID
    • :identifier_keys ([String.t]): Search agents by identifier keys
    • :include_relationships ([String.t]): Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. If not provided, all relationships are loaded by default. Using this can optimize performance by reducing unnecessary joins.
    • :ascending (boolean()): Whether to sort agents oldest to newest (True) or newest to oldest (False, default)
    • :user_id (String.t):

Returns

  • {:ok, [%AgentState{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

list_core_memory_blocks(connection, agent_id, opts \\ [])

@spec list_core_memory_blocks(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, [LettaAPI.Model.Block.t()]}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

List Blocks Retrieve the core memory blocks of a specific agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, [%Block{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

list_messages(connection, agent_id, opts \\ [])

@spec list_messages(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:ok, [LettaAPI.Model.LettaMessageUnion.t()]}
  | {:error, Tesla.Env.t()}

List Messages Retrieve message history for an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :after (String.t): Message after which to retrieve the returned messages.
    • :before (String.t): Message before which to retrieve the returned messages.
    • :limit (integer()): Maximum number of messages to retrieve.
    • :group_id (String.t): Group ID to filter messages by.
    • :use_assistant_message (boolean()): Whether to use assistant messages
    • :assistant_message_tool_name (String.t): The name of the designated message tool.
    • :assistant_message_tool_kwarg (String.t): The name of the message argument.
    • :user_id (String.t):

Returns

  • {:ok, [%LettaMessageUnion{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

list_passages(connection, agent_id, opts \\ [])

@spec list_passages(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, [LettaAPI.Model.Passage.t()]}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

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

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :after (String.t): Unique ID of the memory to start the query range at.
    • :before (String.t): Unique ID of the memory to end the query range at.
    • :limit (integer()): How many results to include in the response.
    • :search (String.t): Search passages by text
    • :ascending (boolean()): Whether to sort passages oldest to newest (True, default) or newest to oldest (False)
    • :user_id (String.t):

Returns

  • {:ok, [%Passage{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

modify_agent(connection, agent_id, update_agent, opts \\ [])

Modify Agent Update an existing agent

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • update_agent (UpdateAgent):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

modify_core_memory_block(connection, agent_id, block_label, block_update, opts \\ [])

@spec modify_core_memory_block(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  LettaAPI.Model.BlockUpdate.t(),
  keyword()
) ::
  {:ok, LettaAPI.Model.Block.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Modify Block Updates a core memory block of an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • block_label (String.t):
  • block_update (BlockUpdate):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.Block.t} on success
  • {:error, Tesla.Env.t} on failure

modify_message(connection, agent_id, message_id, request1, opts \\ [])

Modify Message Update the details of a message associated with an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • message_id (String.t):
  • request1 (Request1):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.ResponseModifyMessage.t} on success
  • {:error, Tesla.Env.t} on failure

modify_passage(connection, agent_id, memory_id, passage_update, opts \\ [])

Modify Passage Modify a memory in the agent's archival memory store.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • memory_id (String.t):
  • passage_update (PassageUpdate):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, [%Passage{}, ...]} on success
  • {:error, Tesla.Env.t} on failure

reset_messages(connection, agent_id, opts \\ [])

@spec reset_messages(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.AgentState.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Reset Messages Resets the messages for an agent

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :add_default_initial_messages (boolean()): If true, adds the default initial messages after resetting.
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

retrieve_agent(connection, agent_id, opts \\ [])

@spec retrieve_agent(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.AgentState.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Retrieve Agent Get the state of the agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.AgentState.t} on success
  • {:error, Tesla.Env.t} on failure

retrieve_agent_context_window(connection, agent_id, opts \\ [])

@spec retrieve_agent_context_window(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.ContextWindowOverview.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Retrieve Agent Context Window Retrieve the context window of a specific agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.ContextWindowOverview.t} on success
  • {:error, Tesla.Env.t} on failure

retrieve_agent_memory(connection, agent_id, opts \\ [])

@spec retrieve_agent_memory(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, LettaAPI.Model.Memory.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Retrieve Agent Memory 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.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.Memory.t} on success
  • {:error, Tesla.Env.t} on failure

retrieve_core_memory_block(connection, agent_id, block_label, opts \\ [])

@spec retrieve_core_memory_block(
  Tesla.Env.client(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, LettaAPI.Model.Block.t()}
  | {:ok, LettaAPI.Model.HttpValidationError.t()}
  | {:error, Tesla.Env.t()}

Retrieve Block Retrieve a core memory block from an agent.

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • block_label (String.t):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.Block.t} on success
  • {:error, Tesla.Env.t} on failure

send_message(connection, agent_id, letta_request, opts \\ [])

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

Parameters

  • connection (LettaAPI.Connection): Connection to server
  • agent_id (String.t):
  • letta_request (LettaRequest):
  • opts (keyword): Optional parameters
    • :user_id (String.t):

Returns

  • {:ok, LettaAPI.Model.LettaResponse.t} on success
  • {:error, Tesla.Env.t} on failure