List Agents

client.agents.list(?, ?): ArrayPage<AgentState { id, agent_type, blocks, 39 more } >

get/v1/agents/

Get a list of all agents.

ParametersExpand Collapse

query: AgentListParams { after, ascending, base_template_id, 16 more }

after?: string | null

Cursor for pagination

Deprecatedascending?: boolean

Whether to sort agents oldest to newest (True) or newest to oldest (False, default)

base_template_id?: string | null

Search agents by base template ID

before?: string | null

Cursor for pagination

identifier_keys?: Array<string> | null

Search agents by identifier keys

identity_id?: string | null

Search agents by identity ID

include?: Array<"agent.blocks" | "agent.identities" | "agent.managed_group" | 4 more>

Specify which relational fields to include in the response. No relationships are included by default.

Accepts one of the following:

"agent.blocks"

"agent.identities"

"agent.managed_group"

"agent.secrets"

"agent.sources"

"agent.tags"

"agent.tools"

include_relationships?: Array<string> | null

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.This is a legacy parameter, and no longer supported after 1.0.0 SDK versions.

last_stop_reason?: StopReasonType | null

Filter agents by their last stop reason.

Accepts one of the following:

"end_turn"

"error"

"llm_api_error"

"invalid_llm_response"

"invalid_tool_call"

"max_steps"

"no_tool_call"

"tool_rule"

"cancelled"

"requires_approval"

limit?: number | null

Limit for pagination

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.

name?: string | null

Name of the agent

order?: "asc" | "desc"

Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first

Accepts one of the following:

"asc"

"desc"

order_by?: "created_at" | "last_run_completion"

Field to sort by

Accepts one of the following:

"created_at"

"last_run_completion"

project_id?: string | null

Search agents by project ID - this will default to your default project on cloud

query_text?: string | null

Search agents by name

Deprecatedsort_by?: string | null

Field to sort by. Options: 'created_at' (default), 'last_run_completion'

tags?: Array<string> | null

List of tags to filter agents by

template_id?: string | null

Search agents by template ID

ReturnsExpand Collapse

AgentState { id, agent_type, blocks, 39 more }

Representation of an agent's state. This is the state of the agent at a given time, and is persisted in the DB backend. The state has all the information needed to recreate a persisted agent.

id: string

The id of the agent. Assigned by the database.

agent_type: AgentType

The type of agent.

Accepts one of the following:

"memgpt_agent"

"memgpt_v2_agent"

"letta_v1_agent"

"react_agent"

"workflow_agent"

"split_thread_agent"

"sleeptime_agent"

"voice_convo_agent"

"voice_sleeptime_agent"

blocks: Array<Block { value, id, base_template_id, 15 more } >

The memory blocks used by the agent.

value: string

Value of the block.

id?: string

The human-friendly ID of the Block

base_template_id?: string | null

The base template id of the block.

created_by_id?: string | null

The id of the user that made this Block.

deployment_id?: string | null

The id of the deployment.

description?: string | null

Description of the block.

entity_id?: string | null

The id of the entity within the template.

hidden?: boolean | null

If set to True, the block will be hidden.

is_template?: boolean

Whether the block is a template (e.g. saved human/persona options).

label?: string | null

Label of the block (e.g. 'human', 'persona') in the context window.

last_updated_by_id?: string | null

The id of the user that last updated this Block.

limit?: number

Character limit of the block.

metadata?: Record<string, unknown> | null

Metadata of the block.

preserve_on_migration?: boolean | null

Preserve the block on template migration.

project_id?: string | null

The associated project id.

read_only?: boolean

Whether the agent has read-only access to the block.

template_id?: string | null

The id of the template.

template_name?: string | null

Name of the block if it is a template.

Deprecatedembedding_config: EmbeddingConfig { embedding_dim, embedding_endpoint_type, embedding_model, 7 more }

Deprecated: Use embedding field instead. The embedding configuration used by the agent.

embedding_dim: number

The dimension of the embedding.

embedding_endpoint_type: "openai" | "anthropic" | "bedrock" | 16 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google_ai"

"google_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding_model: string

The model for the embedding.

azure_deployment?: string | null

The Azure deployment for the model.

azure_endpoint?: string | null

The Azure endpoint for the model.

azure_version?: string | null

The Azure version for the model.

batch_size?: number

The maximum batch size for processing embeddings.

embedding_chunk_size?: number | null

The chunk size of the embedding.

embedding_endpoint?: string | null

The endpoint for the model (None if local).

handle?: string | null

The handle for this config, in the format provider/model-name.

Deprecatedllm_config: LlmConfig { context_window, model, model_endpoint_type, 17 more }

Deprecated: Use model field instead. The LLM configuration used by the agent.

context_window: number

The context window size for the model.

model: string

LLM model name.

model_endpoint_type: "openai" | "anthropic" | "google_ai" | 18 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"google_ai"

"google_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"lmstudio-chatcompletions"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"bedrock"

"deepseek"

"xai"

compatibility_type?: "gguf" | "mlx" | null

The framework compatibility type for the model.

Accepts one of the following:

"gguf"

"mlx"

display_name?: string | null

A human-friendly display name for the model.

enable_reasoner?: boolean

Whether or not the model should use extended thinking if it is a 'reasoning' style model

frequency_penalty?: number | null

Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. From OpenAI: Number between -2.0 and 2.0.

handle?: string | null

The handle for this config, in the format provider/model-name.

max_reasoning_tokens?: number

Configurable thinking budget for extended thinking. Used for enable_reasoner and also for Google Vertex models like Gemini 2.5 Flash. Minimum value is 1024 when used with enable_reasoner.

max_tokens?: number | null

The maximum number of tokens to generate. If not set, the model will use its default value.

model_endpoint?: string | null

The endpoint for the model.

model_wrapper?: string | null

The wrapper for the model.

parallel_tool_calls?: boolean | null

If set to True, enables parallel tool calling. Defaults to False.

provider_category?: ProviderCategory | null

The provider category for the model.

Accepts one of the following:

"base"

"byok"

provider_name?: string | null

The provider name for the model.

put_inner_thoughts_in_kwargs?: boolean | null

Puts 'inner_thoughts' as a kwarg in the function call if this is set to True. This helps with function calling performance and also the generation of inner thoughts.

reasoning_effort?: "minimal" | "low" | "medium" | "high" | null

The reasoning effort to use when generating text reasoning models

Accepts one of the following:

"minimal"

"low"

"medium"

"high"

temperature?: number

The temperature to use when generating text with the model. A higher temperature will result in more random text.

tier?: string | null

The cost tier for the model (cloud only).

verbosity?: "low" | "medium" | "high" | null

Soft control for how verbose model output should be, used for GPT-5 models.

Accepts one of the following:

"low"

"medium"

"high"

Deprecatedmemory: Memory { blocks, agent_type, file_blocks, prompt_template }

Deprecated: Use blocks field instead. The in-context memory of the agent.

blocks: Array<Block { value, id, base_template_id, 15 more } >

Memory blocks contained in the agent's in-context memory

value: string

Value of the block.

id?: string

The human-friendly ID of the Block

base_template_id?: string | null

The base template id of the block.

created_by_id?: string | null

The id of the user that made this Block.

deployment_id?: string | null

The id of the deployment.

description?: string | null

Description of the block.

entity_id?: string | null

The id of the entity within the template.

hidden?: boolean | null

If set to True, the block will be hidden.

is_template?: boolean

Whether the block is a template (e.g. saved human/persona options).

label?: string | null

Label of the block (e.g. 'human', 'persona') in the context window.

last_updated_by_id?: string | null

The id of the user that last updated this Block.

limit?: number

Character limit of the block.

metadata?: Record<string, unknown> | null

Metadata of the block.

preserve_on_migration?: boolean | null

Preserve the block on template migration.

project_id?: string | null

The associated project id.

read_only?: boolean

Whether the agent has read-only access to the block.

template_id?: string | null

The id of the template.

template_name?: string | null

Name of the block if it is a template.

agent_type?: AgentType | (string & {}) | null

Agent type controlling prompt rendering.

Accepts one of the following:

AgentType = "memgpt_agent" | "memgpt_v2_agent" | "letta_v1_agent" | 6 more

Enum to represent the type of agent.

Accepts one of the following:

"memgpt_agent"

"memgpt_v2_agent"

"letta_v1_agent"

"react_agent"

"workflow_agent"

"split_thread_agent"

"sleeptime_agent"

"voice_convo_agent"

"voice_sleeptime_agent"

(string & {})

file_blocks?: Array<FileBlock>

Special blocks representing the agent's in-context memory of an attached file

file_id: string

Unique identifier of the file.

is_open: boolean

True if the agent currently has the file open.

source_id: string

Unique identifier of the source.

value: string

Value of the block.

id?: string

The human-friendly ID of the Block

base_template_id?: string | null

The base template id of the block.

created_by_id?: string | null

The id of the user that made this Block.

deployment_id?: string | null

The id of the deployment.

description?: string | null

Description of the block.

entity_id?: string | null

The id of the entity within the template.

hidden?: boolean | null

If set to True, the block will be hidden.

is_template?: boolean

Whether the block is a template (e.g. saved human/persona options).

label?: string | null

Label of the block (e.g. 'human', 'persona') in the context window.

last_accessed_at?: string | null

UTC timestamp of the agent’s most recent access to this file. Any operations from the open, close, or search tools will update this field.

formatdate-time

last_updated_by_id?: string | null

The id of the user that last updated this Block.

limit?: number

Character limit of the block.

metadata?: Record<string, unknown> | null

Metadata of the block.

preserve_on_migration?: boolean | null

Preserve the block on template migration.

project_id?: string | null

The associated project id.

read_only?: boolean

Whether the agent has read-only access to the block.

template_id?: string | null

The id of the template.

template_name?: string | null

Name of the block if it is a template.

prompt_template?: string

Deprecated. Ignored for performance.

The name of the agent.

sources: Array<Source>

The sources used by the agent.

id: string

The human-friendly ID of the Source

embedding_config: EmbeddingConfig { embedding_dim, embedding_endpoint_type, embedding_model, 7 more }

The embedding configuration used by the source.

embedding_dim: number

The dimension of the embedding.

embedding_endpoint_type: "openai" | "anthropic" | "bedrock" | 16 more

The endpoint type for the model.

Accepts one of the following:

"openai"

"anthropic"

"bedrock"

"google_ai"

"google_vertex"

"azure"

"groq"

"ollama"

"webui"

"webui-legacy"

"lmstudio"

"lmstudio-legacy"

"llamacpp"

"koboldcpp"

"vllm"

"hugging-face"

"mistral"

"together"

"pinecone"

embedding_model: string

The model for the embedding.

azure_deployment?: string | null

The Azure deployment for the model.

azure_endpoint?: string | null

The Azure endpoint for the model.

azure_version?: string | null

The Azure version for the model.

batch_size?: number

The maximum batch size for processing embeddings.

embedding_chunk_size?: number | null

The chunk size of the embedding.

embedding_endpoint?: string | null

The endpoint for the model (None if local).

handle?: string | null

The handle for this config, in the format provider/model-name.

The name of the source.

created_at?: string | null

The timestamp when the source was created.

formatdate-time

created_by_id?: string | null

The id of the user that made this Tool.

description?: string | null

The description of the source.

instructions?: string | null

Instructions for how to use the source.

last_updated_by_id?: string | null

The id of the user that made this Tool.

metadata?: Record<string, unknown> | null

Metadata associated with the source.

updated_at?: string | null

The timestamp when the source was last updated.

formatdate-time

vector_db_provider?: VectorDBProvider

The vector database provider used for this source's passages

Accepts one of the following:

"native"

"tpuf"

"pinecone"

system: string

The system prompt used by the agent.

tags: Array<string>

The tags associated with the agent.

tools: Array<Tool { id, args_json_schema, created_by_id, 14 more } >

The tools used by the agent.

id: string

The human-friendly ID of the Tool

args_json_schema?: Record<string, unknown> | null

The args JSON schema of the function.

created_by_id?: string | null

The id of the user that made this Tool.

default_requires_approval?: boolean | null

Default value for whether or not executing this tool requires approval.

description?: string | null

The description of the tool.

enable_parallel_execution?: boolean | null

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json_schema?: Record<string, unknown> | null

The JSON schema of the function.

last_updated_by_id?: string | null

The id of the user that made this Tool.

metadata_?: Record<string, unknown> | null

A dictionary of additional metadata for the tool.

name?: string | null

The name of the function.

npm_requirements?: Array<NpmRequirement { name, version } > | null

Optional list of npm packages required by this tool.

Name of the npm package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

pip_requirements?: Array<PipRequirement { name, version } > | null

Optional list of pip packages required by this tool.

Name of the pip package.

minLength1

version?: string | null

Optional version of the package, following semantic versioning.

return_char_limit?: number

The maximum number of characters in the response.

maximum1000000

minimum1

source_code?: string | null

The source code of the function.

source_type?: string | null

The type of the source code.

tags?: Array<string>

Metadata tags.

tool_type?: ToolType

The type of the tool.

Accepts one of the following:

"custom"

"letta_core"

"letta_memory_core"

"letta_multi_agent_core"

"letta_sleeptime_core"

"letta_voice_sleeptime_core"

"letta_builtin"

"letta_files_core"

"external_langchain"

"external_composio"

"external_mcp"

base_template_id?: string | null

The base template id of the agent.

created_at?: string | null

The timestamp when the object was created.

formatdate-time

created_by_id?: string | null

The id of the user that made this object.

deployment_id?: string | null

The id of the deployment.

description?: string | null

The description of the agent.

embedding?: Embedding | null

Schema for defining settings for an embedding model

model: string

The name of the model.

provider: "openai" | "ollama"

The provider of the model.

Accepts one of the following:

"openai"

"ollama"

enable_sleeptime?: boolean | null

If set to True, memory management will move to a background agent thread.

entity_id?: string | null

The id of the entity within the template.

hidden?: boolean | null

If set to True, the agent will be hidden.

identities?: Array<Identity { id, agent_ids, block_ids, 5 more } >

The identities associated with this agent.

id: string

The human-friendly ID of the Identity

Deprecatedagent_ids: Array<string>

The IDs of the agents associated with the identity.

Deprecatedblock_ids: Array<string>

The IDs of the blocks associated with the identity.

identifier_key: string

External, user-generated identifier key of the identity.

identity_type: IdentityType

The type of the identity.

Accepts one of the following:

"org"

"user"

"other"

The name of the identity.

project_id?: string | null

The project id of the identity, if applicable.

properties?: Array<IdentityProperty { key, type, value } >

List of properties associated with the identity

key: string

The key of the property

type: "string" | "number" | "boolean" | "json"

The type of the property

Accepts one of the following:

"string"

"number"

"boolean"

"json"

value: string | number | boolean | Record<string, unknown>

The value of the property

Accepts one of the following:

string

number

boolean

Record<string, unknown>

Deprecatedidentity_ids?: Array<string>

Deprecated: Use identities field instead. The ids of the identities associated with this agent.

last_run_completion?: string | null

The timestamp when the agent last completed a run.

formatdate-time

last_run_duration_ms?: number | null

The duration in milliseconds of the agent's last run.

last_stop_reason?: StopReasonType | null

The stop reason from the agent's last run.

Accepts one of the following:

"end_turn"

"error"

"llm_api_error"

"invalid_llm_response"

"invalid_tool_call"

"max_steps"

"no_tool_call"

"tool_rule"

"cancelled"

"requires_approval"

last_updated_by_id?: string | null

The id of the user that made this object.

managed_group?: Group { id, agent_ids, description, 15 more } | null

The multi-agent group that this agent manages

id: string

The id of the group. Assigned by the database.

agent_ids: Array<string>

description: string

manager_type: ManagerType

Accepts one of the following:

"round_robin"

"supervisor"

"dynamic"

"sleeptime"

"voice_sleeptime"

"swarm"

base_template_id?: string | null

The base template id.

deployment_id?: string | null

The id of the deployment.

hidden?: boolean | null

If set to True, the group will be hidden.

last_processed_message_id?: string | null

manager_agent_id?: string | null

max_message_buffer_length?: number | null

The desired maximum length of messages in the context window of the convo agent. This is a best effort, and may be off slightly due to user/assistant interleaving.

max_turns?: number | null

min_message_buffer_length?: number | null

The desired minimum length of messages in the context window of the convo agent. This is a best effort, and may be off-by-one due to user/assistant interleaving.

project_id?: string | null

The associated project id.

Deprecatedshared_block_ids?: Array<string>

sleeptime_agent_frequency?: number | null

template_id?: string | null

The id of the template.

termination_token?: string | null

turns_counter?: number | null

max_files_open?: number | null

Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent.

message_buffer_autoclear?: boolean

If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case.

message_ids?: Array<string> | null

The ids of the messages in the agent's in-context memory.

metadata?: Record<string, unknown> | null

The metadata of the agent.

model?: Model | null

Schema for defining settings for a model

model: string

The name of the model.

max_output_tokens?: number

The maximum number of tokens the model can generate.

parallel_tool_calls?: boolean

Whether to enable parallel tool calling.

Deprecatedmulti_agent_group?: Group { id, agent_ids, description, 15 more } | null

Deprecated: Use managed_group field instead. The multi-agent group that this agent manages.

id: string

The id of the group. Assigned by the database.

agent_ids: Array<string>

description: string

manager_type: ManagerType

Accepts one of the following:

"round_robin"

"supervisor"

"dynamic"

"sleeptime"

"voice_sleeptime"

"swarm"

base_template_id?: string | null

The base template id.

deployment_id?: string | null

The id of the deployment.

hidden?: boolean | null

If set to True, the group will be hidden.

last_processed_message_id?: string | null

manager_agent_id?: string | null

max_message_buffer_length?: number | null

The desired maximum length of messages in the context window of the convo agent. This is a best effort, and may be off slightly due to user/assistant interleaving.

max_turns?: number | null

min_message_buffer_length?: number | null

The desired minimum length of messages in the context window of the convo agent. This is a best effort, and may be off-by-one due to user/assistant interleaving.

project_id?: string | null

The associated project id.

Deprecatedshared_block_ids?: Array<string>

sleeptime_agent_frequency?: number | null

template_id?: string | null

The id of the template.

termination_token?: string | null

turns_counter?: number | null

per_file_view_window_char_limit?: number | null

The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent.

project_id?: string | null

The id of the project the agent belongs to.

response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null

The response format used by the agent

Accepts one of the following:

TextResponseFormat { type }

Response format for plain text responses.

type?: "text"

The type of the response format.

Accepts one of the following:

"text"

JsonSchemaResponseFormat { json_schema, type }

Response format for JSON schema-based responses.

json_schema: Record<string, unknown>

The JSON schema of the response.

type?: "json_schema"

The type of the response format.

Accepts one of the following:

"json_schema"

JsonObjectResponseFormat { type }

Response format for JSON object responses.

type?: "json_object"

The type of the response format.

Accepts one of the following:

"json_object"

secrets?: Array<AgentEnvironmentVariable { agent_id, key, value, 7 more } >

The environment variables for tool execution specific to this agent.

agent_id: string

The ID of the agent this environment variable belongs to.

key: string

The name of the environment variable.

value: string

The value of the environment variable.

id?: string

The human-friendly ID of the Agent-env

created_at?: string | null

The timestamp when the object was created.

formatdate-time

created_by_id?: string | null

The id of the user that made this object.

description?: string | null

An optional description of the environment variable.

last_updated_by_id?: string | null

The id of the user that made this object.

updated_at?: string | null

The timestamp when the object was last updated.

formatdate-time

value_enc?: string | null

Encrypted secret value (stored as encrypted string)

template_id?: string | null

The id of the template the agent belongs to.

timezone?: string | null

The timezone of the agent (IANA format).

Deprecatedtool_exec_environment_variables?: Array<AgentEnvironmentVariable { agent_id, key, value, 7 more } >

Deprecated: use secrets field instead.

agent_id: string

The ID of the agent this environment variable belongs to.

key: string

The name of the environment variable.

value: string

The value of the environment variable.

id?: string

The human-friendly ID of the Agent-env

created_at?: string | null

The timestamp when the object was created.

formatdate-time

created_by_id?: string | null

The id of the user that made this object.

description?: string | null

An optional description of the environment variable.

last_updated_by_id?: string | null

The id of the user that made this object.

updated_at?: string | null

The timestamp when the object was last updated.

formatdate-time

value_enc?: string | null

Encrypted secret value (stored as encrypted string)

tool_rules?: Array<ChildToolRule { children, tool_name, child_arg_nodes, 2 more } | InitToolRule { tool_name, args, prompt_template, type } | TerminalToolRule { tool_name, prompt_template, type } | 6 more> | null

The list of tool rules.

Accepts one of the following:

ChildToolRule { children, tool_name, child_arg_nodes, 2 more }

A ToolRule represents a tool that can be invoked by the agent.

children: Array<string>

The children tools that can be invoked.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

child_arg_nodes?: Array<ChildArgNode> | null

Optional list of typed child argument overrides. Each node must reference a child in 'children'.

The name of the child tool to invoke next.

args?: Record<string, unknown> | null

Optional prefilled arguments for this child tool. Keys must match the tool's parameter names and values must satisfy the tool's JSON schema. Supports partial prefill; non-overlapping parameters are left to the model.

prompt_template?: string | null

Optional template string (ignored).

type?: "constrain_child_tools"

Accepts one of the following:

"constrain_child_tools"

InitToolRule { tool_name, args, prompt_template, type }

Represents the initial tool rule configuration.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

args?: Record<string, unknown> | null

Optional prefilled arguments for this tool. When present, these values will override any LLM-provided arguments with the same keys during invocation. Keys must match the tool's parameter names and values must satisfy the tool's JSON schema. Supports partial prefill; non-overlapping parameters are left to the model.

prompt_template?: string | null

Optional template string (ignored). Rendering uses fast built-in formatting for performance.

type?: "run_first"

Accepts one of the following:

"run_first"

TerminalToolRule { tool_name, prompt_template, type }

Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

prompt_template?: string | null

Optional template string (ignored).

type?: "exit_loop"

Accepts one of the following:

"exit_loop"

ConditionalToolRule { child_output_mapping, tool_name, default_child, 3 more }

A ToolRule that conditionally maps to different child tools based on the output.

child_output_mapping: Record<string, string>

The output case to check for mapping

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

default_child?: string | null

The default child tool to be called. If None, any tool can be called.

prompt_template?: string | null

Optional template string (ignored).

require_output_mapping?: boolean

Whether to throw an error when output doesn't match any case

type?: "conditional"

Accepts one of the following:

"conditional"

ContinueToolRule { tool_name, prompt_template, type }

Represents a tool rule configuration where if this tool gets called, it must continue the agent loop.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

prompt_template?: string | null

Optional template string (ignored).

type?: "continue_loop"

Accepts one of the following:

"continue_loop"

RequiredBeforeExitToolRule { tool_name, prompt_template, type }

Represents a tool rule configuration where this tool must be called before the agent loop can exit.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

prompt_template?: string | null

Optional template string (ignored).

type?: "required_before_exit"

Accepts one of the following:

"required_before_exit"

MaxCountPerStepToolRule { max_count_limit, tool_name, prompt_template, type }

Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step.

max_count_limit: number

The max limit for the total number of times this tool can be invoked in a single step.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

prompt_template?: string | null

Optional template string (ignored).

type?: "max_count_per_step"

Accepts one of the following:

"max_count_per_step"

ParentToolRule { children, tool_name, prompt_template, type }

A ToolRule that only allows a child tool to be called if the parent has been called.

children: Array<string>

The children tools that can be invoked.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

prompt_template?: string | null

Optional template string (ignored).

type?: "parent_last_tool"

Accepts one of the following:

"parent_last_tool"

RequiresApprovalToolRule { tool_name, prompt_template, type }

Represents a tool rule configuration which requires approval before the tool can be invoked.

tool_name: string

The name of the tool. Must exist in the database for the user's organization.

prompt_template?: string | null

Optional template string (ignored). Rendering uses fast built-in formatting for performance.

type?: "requires_approval"

Accepts one of the following:

"requires_approval"

updated_at?: string | null

The timestamp when the object was last updated.

formatdate-time

List Agents

import Letta from '@letta-ai/letta-client';

const client = new Letta({
  apiKey: 'My API Key',
});

// Automatically fetches more pages as needed.
for await (const agentState of client.agents.list()) {
  console.log(agentState.id);
}

[
  {
    "id": "id",
    "agent_type": "memgpt_agent",
    "blocks": [
      {
        "value": "value",
        "id": "block-123e4567-e89b-12d3-a456-426614174000",
        "base_template_id": "base_template_id",
        "created_by_id": "created_by_id",
        "deployment_id": "deployment_id",
        "description": "description",
        "entity_id": "entity_id",
        "hidden": true,
        "is_template": true,
        "label": "label",
        "last_updated_by_id": "last_updated_by_id",
        "limit": 0,
        "metadata": {
          "foo": "bar"
        },
        "preserve_on_migration": true,
        "project_id": "project_id",
        "read_only": true,
        "template_id": "template_id",
        "template_name": "template_name"
      }
    ],
    "embedding_config": {
      "embedding_dim": 0,
      "embedding_endpoint_type": "openai",
      "embedding_model": "embedding_model",
      "azure_deployment": "azure_deployment",
      "azure_endpoint": "azure_endpoint",
      "azure_version": "azure_version",
      "batch_size": 0,
      "embedding_chunk_size": 0,
      "embedding_endpoint": "embedding_endpoint",
      "handle": "handle"
    },
    "llm_config": {
      "context_window": 0,
      "model": "model",
      "model_endpoint_type": "openai",
      "compatibility_type": "gguf",
      "display_name": "display_name",
      "enable_reasoner": true,
      "frequency_penalty": 0,
      "handle": "handle",
      "max_reasoning_tokens": 0,
      "max_tokens": 0,
      "model_endpoint": "model_endpoint",
      "model_wrapper": "model_wrapper",
      "parallel_tool_calls": true,
      "provider_category": "base",
      "provider_name": "provider_name",
      "put_inner_thoughts_in_kwargs": true,
      "reasoning_effort": "minimal",
      "temperature": 0,
      "tier": "tier",
      "verbosity": "low"
    },
    "memory": {
      "blocks": [
        {
          "value": "value",
          "id": "block-123e4567-e89b-12d3-a456-426614174000",
          "base_template_id": "base_template_id",
          "created_by_id": "created_by_id",
          "deployment_id": "deployment_id",
          "description": "description",
          "entity_id": "entity_id",
          "hidden": true,
          "is_template": true,
          "label": "label",
          "last_updated_by_id": "last_updated_by_id",
          "limit": 0,
          "metadata": {
            "foo": "bar"
          },
          "preserve_on_migration": true,
          "project_id": "project_id",
          "read_only": true,
          "template_id": "template_id",
          "template_name": "template_name"
        }
      ],
      "agent_type": "memgpt_agent",
      "file_blocks": [
        {
          "file_id": "file_id",
          "is_open": true,
          "source_id": "source_id",
          "value": "value",
          "id": "block-123e4567-e89b-12d3-a456-426614174000",
          "base_template_id": "base_template_id",
          "created_by_id": "created_by_id",
          "deployment_id": "deployment_id",
          "description": "description",
          "entity_id": "entity_id",
          "hidden": true,
          "is_template": true,
          "label": "label",
          "last_accessed_at": "2019-12-27T18:11:19.117Z",
          "last_updated_by_id": "last_updated_by_id",
          "limit": 0,
          "metadata": {
            "foo": "bar"
          },
          "preserve_on_migration": true,
          "project_id": "project_id",
          "read_only": true,
          "template_id": "template_id",
          "template_name": "template_name"
        }
      ],
      "prompt_template": "prompt_template"
    },
    "name": "name",
    "sources": [
      {
        "id": "source-123e4567-e89b-12d3-a456-426614174000",
        "embedding_config": {
          "embedding_dim": 0,
          "embedding_endpoint_type": "openai",
          "embedding_model": "embedding_model",
          "azure_deployment": "azure_deployment",
          "azure_endpoint": "azure_endpoint",
          "azure_version": "azure_version",
          "batch_size": 0,
          "embedding_chunk_size": 0,
          "embedding_endpoint": "embedding_endpoint",
          "handle": "handle"
        },
        "name": "name",
        "created_at": "2019-12-27T18:11:19.117Z",
        "created_by_id": "created_by_id",
        "description": "description",
        "instructions": "instructions",
        "last_updated_by_id": "last_updated_by_id",
        "metadata": {
          "foo": "bar"
        },
        "updated_at": "2019-12-27T18:11:19.117Z",
        "vector_db_provider": "native"
      }
    ],
    "system": "system",
    "tags": [
      "string"
    ],
    "tools": [
      {
        "id": "tool-123e4567-e89b-12d3-a456-426614174000",
        "args_json_schema": {
          "foo": "bar"
        },
        "created_by_id": "created_by_id",
        "default_requires_approval": true,
        "description": "description",
        "enable_parallel_execution": true,
        "json_schema": {
          "foo": "bar"
        },
        "last_updated_by_id": "last_updated_by_id",
        "metadata_": {
          "foo": "bar"
        },
        "name": "name",
        "npm_requirements": [
          {
            "name": "x",
            "version": "version"
          }
        ],
        "pip_requirements": [
          {
            "name": "x",
            "version": "version"
          }
        ],
        "return_char_limit": 1,
        "source_code": "source_code",
        "source_type": "source_type",
        "tags": [
          "string"
        ],
        "tool_type": "custom"
      }
    ],
    "base_template_id": "base_template_id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "created_by_id": "created_by_id",
    "deployment_id": "deployment_id",
    "description": "description",
    "embedding": {
      "model": "model",
      "provider": "openai"
    },
    "enable_sleeptime": true,
    "entity_id": "entity_id",
    "hidden": true,
    "identities": [
      {
        "id": "identity-123e4567-e89b-12d3-a456-426614174000",
        "agent_ids": [
          "string"
        ],
        "block_ids": [
          "string"
        ],
        "identifier_key": "identifier_key",
        "identity_type": "org",
        "name": "name",
        "project_id": "project_id",
        "properties": [
          {
            "key": "key",
            "type": "string",
            "value": "string"
          }
        ]
      }
    ],
    "identity_ids": [
      "string"
    ],
    "last_run_completion": "2019-12-27T18:11:19.117Z",
    "last_run_duration_ms": 0,
    "last_stop_reason": "end_turn",
    "last_updated_by_id": "last_updated_by_id",
    "managed_group": {
      "id": "id",
      "agent_ids": [
        "string"
      ],
      "description": "description",
      "manager_type": "round_robin",
      "base_template_id": "base_template_id",
      "deployment_id": "deployment_id",
      "hidden": true,
      "last_processed_message_id": "last_processed_message_id",
      "manager_agent_id": "manager_agent_id",
      "max_message_buffer_length": 0,
      "max_turns": 0,
      "min_message_buffer_length": 0,
      "project_id": "project_id",
      "shared_block_ids": [
        "string"
      ],
      "sleeptime_agent_frequency": 0,
      "template_id": "template_id",
      "termination_token": "termination_token",
      "turns_counter": 0
    },
    "max_files_open": 0,
    "message_buffer_autoclear": true,
    "message_ids": [
      "string"
    ],
    "metadata": {
      "foo": "bar"
    },
    "model": {
      "model": "model",
      "max_output_tokens": 0,
      "parallel_tool_calls": true
    },
    "multi_agent_group": {
      "id": "id",
      "agent_ids": [
        "string"
      ],
      "description": "description",
      "manager_type": "round_robin",
      "base_template_id": "base_template_id",
      "deployment_id": "deployment_id",
      "hidden": true,
      "last_processed_message_id": "last_processed_message_id",
      "manager_agent_id": "manager_agent_id",
      "max_message_buffer_length": 0,
      "max_turns": 0,
      "min_message_buffer_length": 0,
      "project_id": "project_id",
      "shared_block_ids": [
        "string"
      ],
      "sleeptime_agent_frequency": 0,
      "template_id": "template_id",
      "termination_token": "termination_token",
      "turns_counter": 0
    },
    "per_file_view_window_char_limit": 0,
    "project_id": "project_id",
    "response_format": {
      "type": "text"
    },
    "secrets": [
      {
        "agent_id": "agent_id",
        "key": "key",
        "value": "value",
        "id": "agent-env-123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2019-12-27T18:11:19.117Z",
        "created_by_id": "created_by_id",
        "description": "description",
        "last_updated_by_id": "last_updated_by_id",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "value_enc": "value_enc"
      }
    ],
    "template_id": "template_id",
    "timezone": "timezone",
    "tool_exec_environment_variables": [
      {
        "agent_id": "agent_id",
        "key": "key",
        "value": "value",
        "id": "agent-env-123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2019-12-27T18:11:19.117Z",
        "created_by_id": "created_by_id",
        "description": "description",
        "last_updated_by_id": "last_updated_by_id",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "value_enc": "value_enc"
      }
    ],
    "tool_rules": [
      {
        "children": [
          "string"
        ],
        "tool_name": "tool_name",
        "child_arg_nodes": [
          {
            "name": "name",
            "args": {
              "foo": "bar"
            }
          }
        ],
        "prompt_template": "prompt_template",
        "type": "constrain_child_tools"
      }
    ],
    "updated_at": "2019-12-27T18:11:19.117Z"
  }
]

Returns Examples

[
  {
    "id": "id",
    "agent_type": "memgpt_agent",
    "blocks": [
      {
        "value": "value",
        "id": "block-123e4567-e89b-12d3-a456-426614174000",
        "base_template_id": "base_template_id",
        "created_by_id": "created_by_id",
        "deployment_id": "deployment_id",
        "description": "description",
        "entity_id": "entity_id",
        "hidden": true,
        "is_template": true,
        "label": "label",
        "last_updated_by_id": "last_updated_by_id",
        "limit": 0,
        "metadata": {
          "foo": "bar"
        },
        "preserve_on_migration": true,
        "project_id": "project_id",
        "read_only": true,
        "template_id": "template_id",
        "template_name": "template_name"
      }
    ],
    "embedding_config": {
      "embedding_dim": 0,
      "embedding_endpoint_type": "openai",
      "embedding_model": "embedding_model",
      "azure_deployment": "azure_deployment",
      "azure_endpoint": "azure_endpoint",
      "azure_version": "azure_version",
      "batch_size": 0,
      "embedding_chunk_size": 0,
      "embedding_endpoint": "embedding_endpoint",
      "handle": "handle"
    },
    "llm_config": {
      "context_window": 0,
      "model": "model",
      "model_endpoint_type": "openai",
      "compatibility_type": "gguf",
      "display_name": "display_name",
      "enable_reasoner": true,
      "frequency_penalty": 0,
      "handle": "handle",
      "max_reasoning_tokens": 0,
      "max_tokens": 0,
      "model_endpoint": "model_endpoint",
      "model_wrapper": "model_wrapper",
      "parallel_tool_calls": true,
      "provider_category": "base",
      "provider_name": "provider_name",
      "put_inner_thoughts_in_kwargs": true,
      "reasoning_effort": "minimal",
      "temperature": 0,
      "tier": "tier",
      "verbosity": "low"
    },
    "memory": {
      "blocks": [
        {
          "value": "value",
          "id": "block-123e4567-e89b-12d3-a456-426614174000",
          "base_template_id": "base_template_id",
          "created_by_id": "created_by_id",
          "deployment_id": "deployment_id",
          "description": "description",
          "entity_id": "entity_id",
          "hidden": true,
          "is_template": true,
          "label": "label",
          "last_updated_by_id": "last_updated_by_id",
          "limit": 0,
          "metadata": {
            "foo": "bar"
          },
          "preserve_on_migration": true,
          "project_id": "project_id",
          "read_only": true,
          "template_id": "template_id",
          "template_name": "template_name"
        }
      ],
      "agent_type": "memgpt_agent",
      "file_blocks": [
        {
          "file_id": "file_id",
          "is_open": true,
          "source_id": "source_id",
          "value": "value",
          "id": "block-123e4567-e89b-12d3-a456-426614174000",
          "base_template_id": "base_template_id",
          "created_by_id": "created_by_id",
          "deployment_id": "deployment_id",
          "description": "description",
          "entity_id": "entity_id",
          "hidden": true,
          "is_template": true,
          "label": "label",
          "last_accessed_at": "2019-12-27T18:11:19.117Z",
          "last_updated_by_id": "last_updated_by_id",
          "limit": 0,
          "metadata": {
            "foo": "bar"
          },
          "preserve_on_migration": true,
          "project_id": "project_id",
          "read_only": true,
          "template_id": "template_id",
          "template_name": "template_name"
        }
      ],
      "prompt_template": "prompt_template"
    },
    "name": "name",
    "sources": [
      {
        "id": "source-123e4567-e89b-12d3-a456-426614174000",
        "embedding_config": {
          "embedding_dim": 0,
          "embedding_endpoint_type": "openai",
          "embedding_model": "embedding_model",
          "azure_deployment": "azure_deployment",
          "azure_endpoint": "azure_endpoint",
          "azure_version": "azure_version",
          "batch_size": 0,
          "embedding_chunk_size": 0,
          "embedding_endpoint": "embedding_endpoint",
          "handle": "handle"
        },
        "name": "name",
        "created_at": "2019-12-27T18:11:19.117Z",
        "created_by_id": "created_by_id",
        "description": "description",
        "instructions": "instructions",
        "last_updated_by_id": "last_updated_by_id",
        "metadata": {
          "foo": "bar"
        },
        "updated_at": "2019-12-27T18:11:19.117Z",
        "vector_db_provider": "native"
      }
    ],
    "system": "system",
    "tags": [
      "string"
    ],
    "tools": [
      {
        "id": "tool-123e4567-e89b-12d3-a456-426614174000",
        "args_json_schema": {
          "foo": "bar"
        },
        "created_by_id": "created_by_id",
        "default_requires_approval": true,
        "description": "description",
        "enable_parallel_execution": true,
        "json_schema": {
          "foo": "bar"
        },
        "last_updated_by_id": "last_updated_by_id",
        "metadata_": {
          "foo": "bar"
        },
        "name": "name",
        "npm_requirements": [
          {
            "name": "x",
            "version": "version"
          }
        ],
        "pip_requirements": [
          {
            "name": "x",
            "version": "version"
          }
        ],
        "return_char_limit": 1,
        "source_code": "source_code",
        "source_type": "source_type",
        "tags": [
          "string"
        ],
        "tool_type": "custom"
      }
    ],
    "base_template_id": "base_template_id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "created_by_id": "created_by_id",
    "deployment_id": "deployment_id",
    "description": "description",
    "embedding": {
      "model": "model",
      "provider": "openai"
    },
    "enable_sleeptime": true,
    "entity_id": "entity_id",
    "hidden": true,
    "identities": [
      {
        "id": "identity-123e4567-e89b-12d3-a456-426614174000",
        "agent_ids": [
          "string"
        ],
        "block_ids": [
          "string"
        ],
        "identifier_key": "identifier_key",
        "identity_type": "org",
        "name": "name",
        "project_id": "project_id",
        "properties": [
          {
            "key": "key",
            "type": "string",
            "value": "string"
          }
        ]
      }
    ],
    "identity_ids": [
      "string"
    ],
    "last_run_completion": "2019-12-27T18:11:19.117Z",
    "last_run_duration_ms": 0,
    "last_stop_reason": "end_turn",
    "last_updated_by_id": "last_updated_by_id",
    "managed_group": {
      "id": "id",
      "agent_ids": [
        "string"
      ],
      "description": "description",
      "manager_type": "round_robin",
      "base_template_id": "base_template_id",
      "deployment_id": "deployment_id",
      "hidden": true,
      "last_processed_message_id": "last_processed_message_id",
      "manager_agent_id": "manager_agent_id",
      "max_message_buffer_length": 0,
      "max_turns": 0,
      "min_message_buffer_length": 0,
      "project_id": "project_id",
      "shared_block_ids": [
        "string"
      ],
      "sleeptime_agent_frequency": 0,
      "template_id": "template_id",
      "termination_token": "termination_token",
      "turns_counter": 0
    },
    "max_files_open": 0,
    "message_buffer_autoclear": true,
    "message_ids": [
      "string"
    ],
    "metadata": {
      "foo": "bar"
    },
    "model": {
      "model": "model",
      "max_output_tokens": 0,
      "parallel_tool_calls": true
    },
    "multi_agent_group": {
      "id": "id",
      "agent_ids": [
        "string"
      ],
      "description": "description",
      "manager_type": "round_robin",
      "base_template_id": "base_template_id",
      "deployment_id": "deployment_id",
      "hidden": true,
      "last_processed_message_id": "last_processed_message_id",
      "manager_agent_id": "manager_agent_id",
      "max_message_buffer_length": 0,
      "max_turns": 0,
      "min_message_buffer_length": 0,
      "project_id": "project_id",
      "shared_block_ids": [
        "string"
      ],
      "sleeptime_agent_frequency": 0,
      "template_id": "template_id",
      "termination_token": "termination_token",
      "turns_counter": 0
    },
    "per_file_view_window_char_limit": 0,
    "project_id": "project_id",
    "response_format": {
      "type": "text"
    },
    "secrets": [
      {
        "agent_id": "agent_id",
        "key": "key",
        "value": "value",
        "id": "agent-env-123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2019-12-27T18:11:19.117Z",
        "created_by_id": "created_by_id",
        "description": "description",
        "last_updated_by_id": "last_updated_by_id",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "value_enc": "value_enc"
      }
    ],
    "template_id": "template_id",
    "timezone": "timezone",
    "tool_exec_environment_variables": [
      {
        "agent_id": "agent_id",
        "key": "key",
        "value": "value",
        "id": "agent-env-123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2019-12-27T18:11:19.117Z",
        "created_by_id": "created_by_id",
        "description": "description",
        "last_updated_by_id": "last_updated_by_id",
        "updated_at": "2019-12-27T18:11:19.117Z",
        "value_enc": "value_enc"
      }
    ],
    "tool_rules": [
      {
        "children": [
          "string"
        ],
        "tool_name": "tool_name",
        "child_arg_nodes": [
          {
            "name": "name",
            "args": {
              "foo": "bar"
            }
          }
        ],
        "prompt_template": "prompt_template",
        "type": "constrain_child_tools"
      }
    ],
    "updated_at": "2019-12-27T18:11:19.117Z"
  }
]