Letta · Schema
CreateAgentRequest
CreateAgent model specifically for POST request body, excluding user_id which comes from headers
AIAgentsStateful AgentsMemoryMemGPTContinual LearningMCPMulti-AgentRAGOpen Source
Properties
| Name | Type | Description |
|---|---|---|
| name | string | The name of the agent. |
| memory_blocks | object | The blocks to create in the agent's in-context memory. |
| tools | object | The tools used by the agent. |
| tool_ids | object | The ids of the tools used by the agent. |
| source_ids | object | Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent. |
| folder_ids | object | The ids of the folders used by the agent. |
| block_ids | object | The ids of the blocks used by the agent. |
| tool_rules | object | The tool rules governing the agent. |
| tags | object | The tags associated with the agent. |
| system | object | The system prompt used by the agent. |
| agent_type | object | The type of agent. |
| initial_message_sequence | object | The initial set of messages to put in the agent's in-context memory. |
| include_base_tools | boolean | If true, attaches the Letta core tools (e.g. core_memory related functions). |
| include_multi_agent_tools | boolean | If true, attaches the Letta multi-agent tools (e.g. sending a message to another agent). |
| include_base_tool_rules | object | If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed). |
| include_default_source | boolean | If true, automatically creates and attaches a default data source for this agent. |
| description | object | The description of the agent. |
| metadata | object | The metadata of the agent. |
| llm_config | object | Deprecated: Use `model` field instead. The LLM configuration used by the agent. |
| embedding_config | object | Deprecated: Use `embedding` field instead. The embedding configuration used by the agent. |
| model | object | The model handle for the agent to use (format: provider/model-name). |
| embedding | object | The embedding model handle used by the agent (format: provider/model-name). |
| model_settings | object | The model settings for the agent. |
| compaction_settings | object | The compaction settings configuration used for compaction. |
| context_window_limit | object | The context window limit used by the agent. |
| embedding_chunk_size | object | Deprecated: No longer used. The embedding chunk size used by the agent. |
| max_tokens | object | Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step. |
| max_reasoning_tokens | object | Deprecated: Use `model` field to configure reasoning tokens instead. The maximum number of tokens to generate for reasoning step. |
| enable_reasoner | object | Deprecated: Use `model` field to configure reasoning instead. Whether to enable internal extended thinking step for a reasoner model. |
| reasoning | object | Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent. |
| from_template | object | Deprecated: please use the 'create agents from a template' endpoint instead. |
| template | boolean | Deprecated: No longer used. |
| project | object | 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 x_project parameter. |
| tool_exec_environment_variables | object | Deprecated: Use `secrets` field instead. Environment variables for tool execution. |
| secrets | object | The environment variables for tool execution specific to this agent. |
| memory_variables | object | Deprecated: Only relevant for creating agents from a template. Use the 'create agents from a template' endpoint instead. |
| project_id | object | Deprecated: No longer used. The id of the project the agent belongs to. |
| template_id | object | Deprecated: No longer used. The id of the template the agent belongs to. |
| base_template_id | object | Deprecated: No longer used. The base template id of the agent. |
| identity_ids | object | The ids of the identities associated with this 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 |
| enable_sleeptime | object | If set to True, memory management will move to a background agent thread. |
| response_format | object | Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent. |
| timezone | object | The timezone of the agent (IANA format). |
| max_files_open | object | 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_limit | object | The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent. |
| hidden | object | Deprecated: No longer used. If set to True, the agent will be hidden. |
| parallel_tool_calls | object | Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "#/components/schemas/CreateAgentRequest",
"title": "CreateAgentRequest",
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "The name of the agent."
},
"memory_blocks": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/CreateBlock"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Memory Blocks",
"description": "The blocks to create in the agent's in-context memory."
},
"tools": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools",
"description": "The tools used by the agent."
},
"tool_ids": {
"anyOf": [
{
"items": {
"type": "string",
"maxLength": 41,
"minLength": 41,
"pattern": "^tool-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the tool in the format 'tool-<uuid4>'",
"examples": [
"tool-123e4567-e89b-42d3-8456-426614174000"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Ids",
"description": "The ids of the tools used by the agent."
},
"source_ids": {
"anyOf": [
{
"items": {
"type": "string",
"maxLength": 43,
"minLength": 43,
"pattern": "^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the source in the format 'source-<uuid4>'",
"examples": [
"source-123e4567-e89b-42d3-8456-426614174000"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Source Ids",
"description": "Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent.",
"deprecated": true
},
"folder_ids": {
"anyOf": [
{
"items": {
"type": "string",
"maxLength": 43,
"minLength": 43,
"pattern": "^source-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the source in the format 'source-<uuid4>'",
"examples": [
"source-123e4567-e89b-42d3-8456-426614174000"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Folder Ids",
"description": "The ids of the folders used by the agent."
},
"block_ids": {
"anyOf": [
{
"items": {
"type": "string",
"maxLength": 42,
"minLength": 42,
"pattern": "^block-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the block in the format 'block-<uuid4>'",
"examples": [
"block-123e4567-e89b-42d3-8456-426614174000"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Block Ids",
"description": "The ids of the blocks used by the agent."
},
"tool_rules": {
"anyOf": [
{
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/ChildToolRule"
},
{
"$ref": "#/components/schemas/InitToolRule"
},
{
"$ref": "#/components/schemas/TerminalToolRule"
},
{
"$ref": "#/components/schemas/ConditionalToolRule"
},
{
"$ref": "#/components/schemas/ContinueToolRule"
},
{
"$ref": "#/components/schemas/RequiredBeforeExitToolRule"
},
{
"$ref": "#/components/schemas/MaxCountPerStepToolRule"
},
{
"$ref": "#/components/schemas/ParentToolRule"
},
{
"$ref": "#/components/schemas/RequiresApprovalToolRule"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"conditional": "#/components/schemas/ConditionalToolRule",
"constrain_child_tools": "#/components/schemas/ChildToolRule",
"continue_loop": "#/components/schemas/ContinueToolRule",
"exit_loop": "#/components/schemas/TerminalToolRule",
"max_count_per_step": "#/components/schemas/MaxCountPerStepToolRule",
"parent_last_tool": "#/components/schemas/ParentToolRule",
"required_before_exit": "#/components/schemas/RequiredBeforeExitToolRule",
"requires_approval": "#/components/schemas/RequiresApprovalToolRule",
"run_first": "#/components/schemas/InitToolRule"
}
}
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Rules",
"description": "The tool rules governing the agent."
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "The tags associated with the agent."
},
"system": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "System",
"description": "The system prompt used by the agent."
},
"agent_type": {
"$ref": "#/components/schemas/AgentType",
"description": "The type of agent."
},
"initial_message_sequence": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageCreate"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Initial Message Sequence",
"description": "The initial set of messages to put in the agent's in-context memory."
},
"include_base_tools": {
"type": "boolean",
"title": "Include Base Tools",
"description": "If true, attaches the Letta core tools (e.g. core_memory related functions).",
"default": true
},
"include_multi_agent_tools": {
"type": "boolean",
"title": "Include Multi Agent Tools",
"description": "If true, attaches the Letta multi-agent tools (e.g. sending a message to another agent).",
"default": false
},
"include_base_tool_rules": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Include Base Tool Rules",
"description": "If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed)."
},
"include_default_source": {
"type": "boolean",
"title": "Include Default Source",
"description": "If true, automatically creates and attaches a default data source for this agent.",
"default": false,
"deprecated": true
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "The description of the agent."
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata",
"description": "The metadata of the agent."
},
"llm_config": {
"anyOf": [
{
"$ref": "#/components/schemas/LLMConfig"
},
{
"type": "null"
}
],
"description": "Deprecated: Use `model` field instead. The LLM configuration used by the agent.",
"deprecated": true
},
"embedding_config": {
"anyOf": [
{
"$ref": "#/components/schemas/EmbeddingConfig"
},
{
"type": "null"
}
],
"description": "Deprecated: Use `embedding` field instead. The embedding configuration used by the agent.",
"deprecated": true
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model",
"description": "The model handle for the agent to use (format: provider/model-name)."
},
"embedding": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Embedding",
"description": "The embedding model handle used by the agent (format: provider/model-name)."
},
"model_settings": {
"anyOf": [
{
"oneOf": [
{
"$ref": "#/components/schemas/OpenAIModelSettings"
},
{
"$ref": "#/components/schemas/SGLangModelSettings"
},
{
"$ref": "#/components/schemas/AnthropicModelSettings"
},
{
"$ref": "#/components/schemas/GoogleAIModelSettings"
},
{
"$ref": "#/components/schemas/GoogleVertexModelSettings"
},
{
"$ref": "#/components/schemas/AzureModelSettings"
},
{
"$ref": "#/components/schemas/XAIModelSettings"
},
{
"$ref": "#/components/schemas/ZAIModelSettings"
},
{
"$ref": "#/components/schemas/GroqModelSettings"
},
{
"$ref": "#/components/schemas/DeepseekModelSettings"
},
{
"$ref": "#/components/schemas/TogetherModelSettings"
},
{
"$ref": "#/components/schemas/BedrockModelSettings"
},
{
"$ref": "#/components/schemas/BasetenModelSettings"
},
{
"$ref": "#/components/schemas/OpenRouterModelSettings"
},
{
"$ref": "#/components/schemas/ChatGPTOAuthModelSettings"
}
],
"discriminator": {
"propertyName": "provider_type",
"mapping": {
"anthropic": "#/components/schemas/AnthropicModelSettings",
"azure": "#/components/schemas/AzureModelSettings",
"baseten": "#/components/schemas/BasetenModelSettings",
"bedrock": "#/components/schemas/BedrockModelSettings",
"chatgpt_oauth": "#/components/schemas/ChatGPTOAuthModelSettings",
"deepseek": "#/components/schemas/DeepseekModelSettings",
"google_ai": "#/components/schemas/GoogleAIModelSettings",
"google_vertex": "#/components/schemas/GoogleVertexModelSettings",
"groq": "#/components/schemas/GroqModelSettings",
"openai": "#/components/schemas/OpenAIModelSettings",
"openrouter": "#/components/schemas/OpenRouterModelSettings",
"sglang": "#/components/schemas/SGLangModelSettings",
"together": "#/components/schemas/TogetherModelSettings",
"xai": "#/components/schemas/XAIModelSettings",
"zai": "#/components/schemas/ZAIModelSettings"
}
}
},
{
"type": "null"
}
],
"title": "Model Settings",
"description": "The model settings for the agent."
},
"compaction_settings": {
"anyOf": [
{
"$ref": "#/components/schemas/CompactionSettings-Input"
},
{
"type": "null"
}
],
"description": "The compaction settings configuration used for compaction."
},
"context_window_limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Context Window Limit",
"description": "The context window limit used by the agent."
},
"embedding_chunk_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Embedding Chunk Size",
"description": "Deprecated: No longer used. The embedding chunk size used by the agent.",
"default": 300,
"deprecated": true
},
"max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Tokens",
"description": "Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step.",
"deprecated": true
},
"max_reasoning_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Reasoning Tokens",
"description": "Deprecated: Use `model` field to configure reasoning tokens instead. The maximum number of tokens to generate for reasoning step.",
"deprecated": true
},
"enable_reasoner": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Reasoner",
"description": "Deprecated: Use `model` field to configure reasoning instead. Whether to enable internal extended thinking step for a reasoner model.",
"default": true,
"deprecated": true
},
"reasoning": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Reasoning",
"description": "Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent.",
"deprecated": true
},
"from_template": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "From Template",
"description": "Deprecated: please use the 'create agents from a template' endpoint instead.",
"deprecated": true
},
"template": {
"type": "boolean",
"title": "Template",
"description": "Deprecated: No longer used.",
"default": false,
"deprecated": true
},
"project": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project",
"description": "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 x_project parameter.",
"deprecated": true
},
"tool_exec_environment_variables": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Tool Exec Environment Variables",
"description": "Deprecated: Use `secrets` field instead. Environment variables for tool execution.",
"deprecated": true
},
"secrets": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Secrets",
"description": "The environment variables for tool execution specific to this agent."
},
"memory_variables": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Memory Variables",
"description": "Deprecated: Only relevant for creating agents from a template. Use the 'create agents from a template' endpoint instead.",
"deprecated": true
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project Id",
"description": "Deprecated: No longer used. The id of the project the agent belongs to.",
"deprecated": true
},
"template_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Template Id",
"description": "Deprecated: No longer used. The id of the template the agent belongs to.",
"deprecated": true
},
"base_template_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Base Template Id",
"description": "Deprecated: No longer used. The base template id of the agent.",
"deprecated": true
},
"identity_ids": {
"anyOf": [
{
"items": {
"type": "string",
"maxLength": 45,
"minLength": 45,
"pattern": "^identity-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "The ID of the identity in the format 'identity-<uuid4>'",
"examples": [
"identity-123e4567-e89b-42d3-8456-426614174000"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Identity Ids",
"description": "The ids of the identities associated with this agent."
},
"message_buffer_autoclear": {
"type": "boolean",
"title": "Message Buffer Autoclear",
"description": "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.",
"default": false
},
"enable_sleeptime": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Sleeptime",
"description": "If set to True, memory management will move to a background agent thread."
},
"response_format": {
"anyOf": [
{
"oneOf": [
{
"$ref": "#/components/schemas/TextResponseFormat"
},
{
"$ref": "#/components/schemas/JsonSchemaResponseFormat"
},
{
"$ref": "#/components/schemas/JsonObjectResponseFormat"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"json_object": "#/components/schemas/JsonObjectResponseFormat",
"json_schema": "#/components/schemas/JsonSchemaResponseFormat",
"text": "#/components/schemas/TextResponseFormat"
}
}
},
{
"type": "null"
}
],
"title": "Response Format",
"description": "Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent.",
"deprecated": true
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Timezone",
"description": "The timezone of the agent (IANA format)."
},
"max_files_open": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Files Open",
"description": "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_limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Per File View Window Char Limit",
"description": "The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent."
},
"hidden": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Hidden",
"description": "Deprecated: No longer used. If set to True, the agent will be hidden.",
"deprecated": true
},
"parallel_tool_calls": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Parallel Tool Calls",
"description": "Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling.",
"deprecated": true
}
},
"type": "object",
"description": "CreateAgent model specifically for POST request body, excluding user_id which comes from headers"
}