agents

Create Agent

Changed on

Create an agent.

post/v1/agents/

Request

  • Base URL
    https://app.letta.com
  • URL
    https://app.letta.com/v1/agents/
  • Auth
    HTTP bearer

Headers

X-Projectstring nullable

The project slug to associate with the agent (cloud only).

Request body

namestring

The name of the agent.

toolsstring[] nullable

The tools used by the agent.

tool_idsstring[] nullable

The ids of the tools used by the agent.

source_idsstring[] nullable

The ids of the sources used by the agent.

block_idsstring[] nullable

The ids of the blocks used by the agent.

tagsstring[] nullable

The tags associated with the agent.

systemstring nullable

The system prompt used by the agent.

agent_type'memgpt_agent' | 'memgpt_v2_agent' | 'letta_v1_agent' | 'react_agent' | 'workflow_agent' | 'split_thread_agent' | 'sleeptime_agent' | 'voice_convo_agent' | 'voice_sleeptime_agent'

Enum to represent the type of agent.

include_base_toolsboolean

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

include_multi_agent_toolsboolean

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

include_base_tool_rulesboolean nullable

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

include_default_sourceboolean

If true, automatically creates and attaches a default data source for this agent.

descriptionstring nullable

The description of the agent.

metadataobject nullable

The metadata of the agent.

modelstring nullable

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

embeddingstring nullable

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

context_window_limitinteger nullable

The context window limit used by the agent.

embedding_chunk_sizeinteger nullable

The embedding chunk size used by the agent.

max_tokensinteger nullable

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

max_reasoning_tokensinteger nullable

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

enable_reasonerboolean nullable

Whether to enable internal extended thinking step for a reasoner model.

reasoningboolean nullable

Whether to enable reasoning for this agent.

from_templatestring nullable

Deprecated: please use the 'create agents from a template' endpoint instead.

templateboolean

Deprecated: No longer used

projectstring nullable

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.

tool_exec_environment_variablesobject nullable

Deprecated: use secrets field instead.

secretsobject nullable

The environment variables for tool execution specific to this agent.

memory_variablesobject nullable

The variables that should be set for the agent.

project_idstring nullable

The id of the project the agent belongs to.

template_idstring nullable

The id of the template the agent belongs to.

base_template_idstring nullable

The base template id of the agent.

identity_idsstring[] nullable

The ids of the identities associated with this agent.

message_buffer_autoclearboolean

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 nullable

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

timezonestring nullable

The timezone of the agent (IANA format).

max_files_openinteger nullable

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.

per_file_view_window_char_limitinteger nullable

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

hiddenboolean nullable

If set to True, the agent will be hidden.

Response

Successful Response

created_by_idstring nullable

The id of the user that made this object.

last_updated_by_idstring nullable

The id of the user that made this object.

created_atstring date-time nullable

The timestamp when the object was created.

updated_atstring date-time nullable

The timestamp when the object was last updated.

idstring required

The id of the agent. Assigned by the database.

namestring required

The name of the agent.

message_idsstring[] nullable

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

systemstring required

The system prompt used by the agent.

agent_type'memgpt_agent' | 'memgpt_v2_agent' | 'letta_v1_agent' | 'react_agent' | 'workflow_agent' | 'split_thread_agent' | 'sleeptime_agent' | 'voice_convo_agent' | 'voice_sleeptime_agent' required

Enum to represent the type of agent.

descriptionstring nullable

The description of the agent.

metadataobject nullable

The metadata of the agent.

tagsstring[] required

The tags associated with the agent.

project_idstring nullable

The id of the project the agent belongs to.

template_idstring nullable

The id of the template the agent belongs to.

base_template_idstring nullable

The base template id of the agent.

deployment_idstring nullable

The id of the deployment.

entity_idstring nullable

The id of the entity within the template.

identity_idsstring[]

The ids of the identities associated with this agent.

message_buffer_autoclearboolean

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 nullable

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

last_run_completionstring date-time nullable

The timestamp when the agent last completed a run.

last_run_duration_msinteger nullable

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

timezonestring nullable

The timezone of the agent (IANA format).

max_files_openinteger nullable

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.

per_file_view_window_char_limitinteger nullable

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

hiddenboolean nullable

If set to True, the agent will be hidden.

Example response

{
  "memory": {
    "blocks": [
      {
        "id": "block-123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "file_blocks": [
      {
        "id": "block-123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  },
  "tools": [
    {
      "id": "tool-123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "sources": [
    {
      "id": "source-123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "tool_exec_environment_variables": [
    {
      "id": "agent-env-123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "secrets": [
    {
      "id": "agent-env-123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Changes

  • 6cec99480c13Revision changes
    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • f0554a0bf8b2Revision changes
    • info

      added the new optional request property ///////

    • info

      added the new optional request property ///////

    • info

      added the new optional request property ///////