Agents

Create Agent

Create a new agent with the specified configuration.

Headers

AuthorizationstringRequired

Header authentication of the form Bearer <token>

X-ProjectstringOptional

Request

This endpoint expects an object.
namestringOptional
The name of the agent.
memory_blockslist of objectsOptional

The blocks to create in the agent’s in-context memory.

toolslist of stringsOptional
The tools used by the agent.
tool_idslist of stringsOptional
The ids of the tools used by the agent.
source_idslist of stringsOptional
The ids of the sources used by the agent.
block_idslist of stringsOptional
The ids of the blocks used by the agent.
tool_ruleslist of objectsOptional
The tool rules governing the agent.
tagslist of stringsOptional
The tags associated with the agent.
systemstringOptional
The system prompt used by the agent.
agent_typeenumOptional
The type of agent.
llm_configobjectOptional
The LLM configuration used by the agent.
embedding_configobjectOptional
The embedding configuration used by the agent.
initial_message_sequencelist of objectsOptional

The initial set of messages to put in the agent’s in-context memory.

include_base_toolsbooleanOptionalDefaults to true

If true, attaches the Letta core tools (e.g. archival_memory and core_memory related functions).

include_multi_agent_toolsbooleanOptionalDefaults to false

If true, attaches the Letta multi-agent tools (e.g. sending a message to another agent).

include_base_tool_rulesbooleanOptionalDefaults to true

If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed).

descriptionstringOptional
The description of the agent.
metadataobjectOptional
The metadata of the agent.
modelstringOptional

The LLM configuration handle used by the agent, specified in the format provider/model-name, as an alternative to specifying llm_config.

embeddingstringOptional

The embedding configuration handle used by the agent, specified in the format provider/model-name.

context_window_limitintegerOptional
The context window limit used by the agent.
embedding_chunk_sizeintegerOptionalDefaults to 300
The embedding chunk size used by the agent.
max_tokensintegerOptional
The maximum number of tokens to generate, including reasoning step. If not set, the model will use its default value.
max_reasoning_tokensintegerOptional
The maximum number of tokens to generate for reasoning step. If not set, the model will use its default value.
enable_reasonerbooleanOptionalDefaults to false
Whether to enable internal extended thinking step for a reasoner model.
from_templatestringOptional
The template id used to configure the agent
templatebooleanOptionalDefaults to false
Whether the agent is a template
tool_exec_environment_variablesmap from strings to stringsOptional
The environment variables for tool execution specific to this agent.
memory_variablesmap from strings to stringsOptional
The variables that should be set for the agent.
project_idstringOptional
The id of the project the agent belongs to.
template_idstringOptional
The id of the template the agent belongs to.
base_template_idstringOptional
The base template id of the agent.
identity_idslist of stringsOptional
The ids of the identities associated with this agent.
message_buffer_autoclearbooleanOptionalDefaults to false

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.

enable_sleeptimebooleanOptional
If set to True, memory management will move to a background agent thread.
response_formatobjectOptional
The response format for the agent.
projectstringOptionalDeprecated

Deprecated: Project should now be passed via the X-Project header instead of in the request body. If using the sdk, this can be done via the new x_project field below.

Response

Successful Response
idstring
The id of the agent. Assigned by the database.
namestring
The name of the agent.
systemstring
The system prompt used by the agent.
agent_typeenum
The type of agent.
llm_configobject
The LLM configuration used by the agent.
embedding_configobject
The embedding configuration used by the agent.
memoryobject

The in-context memory of the agent.

toolslist of objects
The tools used by the agent.
sourceslist of objects
The sources used by the agent.
tagslist of strings
The tags associated with the agent.
created_by_idstring or null
The id of the user that made this object.
last_updated_by_idstring or null
The id of the user that made this object.
created_atstring or nullformat: "date-time"
The timestamp when the object was created.
updated_atstring or nullformat: "date-time"
The timestamp when the object was last updated.
tool_ruleslist of objects or null
The list of tool rules.
message_idslist of strings or null

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

response_formatobject or null

The response format used by the agent when returning from send_message.

descriptionstring or null
The description of the agent.
metadataobject or null
The metadata of the agent.
tool_exec_environment_variableslist of objects or null
The environment variables for tool execution specific to this agent.
project_idstring or null
The id of the project the agent belongs to.
template_idstring or null
The id of the template the agent belongs to.
base_template_idstring or null
The base template id of the agent.
identity_idslist of strings or null
The ids of the identities associated with this agent.
message_buffer_autoclearboolean or nullDefaults to false

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.

enable_sleeptimeboolean or null
If set to True, memory management will move to a background agent thread.
multi_agent_groupobject or null

The multi-agent group that this agent manages