---
title: "Modify Agent"
method: PATCH
path: "/v1/agents/{agent_id}"
tags: ["agents"]
---

# Modify Agent

`PATCH /v1/agents/{agent_id}`

Update an existing agent.

## Path parameters

- `agent_id` string, required

## Request body

- UpdateAgent
  - `name` string, nullable — The name of the agent.
  - `tool_ids` string[], nullable — The ids of the tools used by the agent.
  - `source_ids` string[], nullable — The ids of the sources used by the agent.
  - `block_ids` string[], nullable — The ids of the blocks used by the agent.
  - `tags` string[], nullable — The tags associated with the agent.
  - `system` string, nullable — The system prompt used by the agent.
  - `tool_rules` union[], nullable — The tool rules governing the agent.
    - union
      - ChildToolRule — A ToolRule represents a tool that can be invoked by the agent.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'constrain_child_tools'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `children` string[], required — The children tools that can be invoked.
        - `child_arg_nodes` ToolCallNode[], nullable — Optional list of typed child argument overrides. Each node must reference a child in 'children'.
          - `name` string, required — The name of the child tool to invoke next.
          - `args` object, nullable — 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.
      - InitToolRule — Represents the initial tool rule configuration.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'run_first'
        - `prompt_template` string, nullable — Optional template string (ignored). Rendering uses fast built-in formatting for performance.
        - `args` object, nullable — 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.
      - TerminalToolRule — Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'exit_loop'
        - `prompt_template` string, nullable — Optional template string (ignored).
      - ConditionalToolRule — A ToolRule that conditionally maps to different child tools based on the output.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'conditional'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `default_child` string, nullable — The default child tool to be called. If None, any tool can be called.
        - `child_output_mapping` object, required — The output case to check for mapping
        - `require_output_mapping` boolean — Whether to throw an error when output doesn't match any case
      - ContinueToolRule — Represents a tool rule configuration where if this tool gets called, it must continue the agent loop.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'continue_loop'
        - `prompt_template` string, nullable — Optional template string (ignored).
      - RequiredBeforeExitToolRule — Represents a tool rule configuration where this tool must be called before the agent loop can exit.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'required_before_exit'
        - `prompt_template` string, nullable — Optional template string (ignored).
      - MaxCountPerStepToolRule — Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'max_count_per_step'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `max_count_limit` integer, required — The max limit for the total number of times this tool can be invoked in a single step.
      - ParentToolRule — A ToolRule that only allows a child tool to be called if the parent has been called.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'parent_last_tool'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `children` string[], required — The children tools that can be invoked.
      - RequiresApprovalToolRule — Represents a tool rule configuration which requires approval before the tool can be invoked.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'requires_approval'
        - `prompt_template` string, nullable — Optional template string (ignored). Rendering uses fast built-in formatting for performance.
  - `llm_config` LLMConfig — Configuration for Language Model (LLM) connection and generation parameters.
    - `model` string, required — LLM model name.
    - `model_endpoint_type` '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', required — The endpoint type for the model.
    - `model_endpoint` string, nullable — The endpoint for the model.
    - `provider_name` string, nullable — The provider name for the model.
    - `provider_category` 'base' | 'byok'
    - `model_wrapper` string, nullable — The wrapper for the model.
    - `context_window` integer, required — The context window size for the model.
    - `put_inner_thoughts_in_kwargs` boolean, nullable — 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.
    - `handle` string, nullable — The handle for this config, in the format provider/model-name.
    - `temperature` number — The temperature to use when generating text with the model. A higher temperature will result in more random text.
    - `max_tokens` integer, nullable — The maximum number of tokens to generate. If not set, the model will use its default value.
    - `enable_reasoner` boolean — Whether or not the model should use extended thinking if it is a 'reasoning' style model
    - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high', nullable — The reasoning effort to use when generating text reasoning models
    - `max_reasoning_tokens` integer — 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.
    - `frequency_penalty` number, nullable — 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.
    - `compatibility_type` 'gguf' | 'mlx', nullable — The framework compatibility type for the model.
    - `verbosity` 'low' | 'medium' | 'high', nullable — Soft control for how verbose model output should be, used for GPT-5 models.
    - `tier` string, nullable — The cost tier for the model (cloud only).
  - `embedding_config` EmbeddingConfig — Configuration for embedding model connection and processing parameters.
    - `embedding_endpoint_type` 'openai' | 'anthropic' | 'bedrock' | 'google_ai' | 'google_vertex' | 'azure' | 'groq' | 'ollama' | 'webui' | 'webui-legacy' | 'lmstudio' | 'lmstudio-legacy' | 'llamacpp' | 'koboldcpp' | 'vllm' | 'hugging-face' | 'mistral' | 'together' | 'pinecone', required — The endpoint type for the model.
    - `embedding_endpoint` string, nullable — The endpoint for the model (`None` if local).
    - `embedding_model` string, required — The model for the embedding.
    - `embedding_dim` integer, required — The dimension of the embedding.
    - `embedding_chunk_size` integer, nullable — The chunk size of the embedding.
    - `handle` string, nullable — The handle for this config, in the format provider/model-name.
    - `batch_size` integer — The maximum batch size for processing embeddings.
    - `azure_endpoint` string, nullable — The Azure endpoint for the model.
    - `azure_version` string, nullable — The Azure version for the model.
    - `azure_deployment` string, nullable — The Azure deployment for the model.
  - `message_ids` string[], nullable — The ids of the messages in the agent's in-context memory.
  - `description` string, nullable — The description of the agent.
  - `metadata` object, nullable — The metadata of the agent.
  - `tool_exec_environment_variables` object, nullable — Deprecated: use `secrets` field instead
  - `secrets` object, nullable — The environment variables for tool execution specific to this agent.
  - `project_id` string, nullable — The id of the project the agent belongs to.
  - `template_id` string, nullable — The id of the template the agent belongs to.
  - `base_template_id` string, nullable — The base template id of the agent.
  - `identity_ids` string[], nullable — The ids of the identities associated with this agent.
  - `message_buffer_autoclear` boolean, nullable — 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.
  - `model` string, nullable — The LLM configuration handle used by the agent, specified in the format provider/model-name, as an alternative to specifying llm_config.
  - `embedding` string, nullable — The embedding configuration handle used by the agent, specified in the format provider/model-name.
  - `reasoning` boolean, nullable — Whether to enable reasoning for this agent.
  - `enable_sleeptime` boolean, nullable — If set to True, memory management will move to a background agent thread.
  - `response_format` union — The response format for the agent.
    - TextResponseFormat — Response format for plain text responses.
      - `type` 'text' — The type of the response format.
    - JsonSchemaResponseFormat — Response format for JSON schema-based responses.
      - `type` 'json_schema' — The type of the response format.
      - `json_schema` object, required — The JSON schema of the response.
    - JsonObjectResponseFormat — Response format for JSON object responses.
      - `type` 'json_object' — The type of the response format.
  - `last_run_completion` string, date-time, nullable — The timestamp when the agent last completed a run.
  - `last_run_duration_ms` integer, nullable — The duration in milliseconds of the agent's last run.
  - `timezone` string, nullable — The timezone of the agent (IANA format).
  - `max_files_open` integer, 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_limit` integer, 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.
  - `hidden` boolean, nullable — If set to True, the agent will be hidden.

## Response `200`

Successful Response

- AgentState — 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. Parameters: id (str): The unique identifier of the agent. name (str): The name of the agent (must be unique to the user). created_at (datetime): The datetime the agent was created. message_ids (List[str]): The ids of the messages in the agent's in-context memory. memory (Memory): The in-context memory of the agent. tools (List[str]): The tools used by the agent. This includes any memory editing functions specified in `memory`. system (str): The system prompt used by the agent. llm_config (LLMConfig): The LLM configuration used by the agent. embedding_config (EmbeddingConfig): The embedding configuration used by the agent.
  - `created_by_id` string, nullable — The id of the user that made this object.
  - `last_updated_by_id` string, nullable — The id of the user that made this object.
  - `created_at` string, date-time, nullable — The timestamp when the object was created.
  - `updated_at` string, date-time, nullable — The timestamp when the object was last updated.
  - `id` string, required — The id of the agent. Assigned by the database.
  - `name` string, required — The name of the agent.
  - `tool_rules` union[], nullable — The list of tool rules.
    - union
      - ChildToolRule — A ToolRule represents a tool that can be invoked by the agent.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'constrain_child_tools'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `children` string[], required — The children tools that can be invoked.
        - `child_arg_nodes` ToolCallNode[], nullable — Optional list of typed child argument overrides. Each node must reference a child in 'children'.
          - `name` string, required — The name of the child tool to invoke next.
          - `args` object, nullable — 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.
      - InitToolRule — Represents the initial tool rule configuration.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'run_first'
        - `prompt_template` string, nullable — Optional template string (ignored). Rendering uses fast built-in formatting for performance.
        - `args` object, nullable — 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.
      - TerminalToolRule — Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'exit_loop'
        - `prompt_template` string, nullable — Optional template string (ignored).
      - ConditionalToolRule — A ToolRule that conditionally maps to different child tools based on the output.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'conditional'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `default_child` string, nullable — The default child tool to be called. If None, any tool can be called.
        - `child_output_mapping` object, required — The output case to check for mapping
        - `require_output_mapping` boolean — Whether to throw an error when output doesn't match any case
      - ContinueToolRule — Represents a tool rule configuration where if this tool gets called, it must continue the agent loop.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'continue_loop'
        - `prompt_template` string, nullable — Optional template string (ignored).
      - RequiredBeforeExitToolRule — Represents a tool rule configuration where this tool must be called before the agent loop can exit.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'required_before_exit'
        - `prompt_template` string, nullable — Optional template string (ignored).
      - MaxCountPerStepToolRule — Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'max_count_per_step'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `max_count_limit` integer, required — The max limit for the total number of times this tool can be invoked in a single step.
      - ParentToolRule — A ToolRule that only allows a child tool to be called if the parent has been called.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'parent_last_tool'
        - `prompt_template` string, nullable — Optional template string (ignored).
        - `children` string[], required — The children tools that can be invoked.
      - RequiresApprovalToolRule — Represents a tool rule configuration which requires approval before the tool can be invoked.
        - `tool_name` string, required — The name of the tool. Must exist in the database for the user's organization.
        - `type` 'requires_approval'
        - `prompt_template` string, nullable — Optional template string (ignored). Rendering uses fast built-in formatting for performance.
  - `message_ids` string[], nullable — The ids of the messages in the agent's in-context memory.
  - `system` string, 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.
  - `llm_config` LLMConfig, required — Configuration for Language Model (LLM) connection and generation parameters.
    - `model` string, required — LLM model name.
    - `model_endpoint_type` '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', required — The endpoint type for the model.
    - `model_endpoint` string, nullable — The endpoint for the model.
    - `provider_name` string, nullable — The provider name for the model.
    - `provider_category` 'base' | 'byok'
    - `model_wrapper` string, nullable — The wrapper for the model.
    - `context_window` integer, required — The context window size for the model.
    - `put_inner_thoughts_in_kwargs` boolean, nullable — 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.
    - `handle` string, nullable — The handle for this config, in the format provider/model-name.
    - `temperature` number — The temperature to use when generating text with the model. A higher temperature will result in more random text.
    - `max_tokens` integer, nullable — The maximum number of tokens to generate. If not set, the model will use its default value.
    - `enable_reasoner` boolean — Whether or not the model should use extended thinking if it is a 'reasoning' style model
    - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high', nullable — The reasoning effort to use when generating text reasoning models
    - `max_reasoning_tokens` integer — 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.
    - `frequency_penalty` number, nullable — 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.
    - `compatibility_type` 'gguf' | 'mlx', nullable — The framework compatibility type for the model.
    - `verbosity` 'low' | 'medium' | 'high', nullable — Soft control for how verbose model output should be, used for GPT-5 models.
    - `tier` string, nullable — The cost tier for the model (cloud only).
  - `embedding_config` EmbeddingConfig, required — Configuration for embedding model connection and processing parameters.
    - `embedding_endpoint_type` 'openai' | 'anthropic' | 'bedrock' | 'google_ai' | 'google_vertex' | 'azure' | 'groq' | 'ollama' | 'webui' | 'webui-legacy' | 'lmstudio' | 'lmstudio-legacy' | 'llamacpp' | 'koboldcpp' | 'vllm' | 'hugging-face' | 'mistral' | 'together' | 'pinecone', required — The endpoint type for the model.
    - `embedding_endpoint` string, nullable — The endpoint for the model (`None` if local).
    - `embedding_model` string, required — The model for the embedding.
    - `embedding_dim` integer, required — The dimension of the embedding.
    - `embedding_chunk_size` integer, nullable — The chunk size of the embedding.
    - `handle` string, nullable — The handle for this config, in the format provider/model-name.
    - `batch_size` integer — The maximum batch size for processing embeddings.
    - `azure_endpoint` string, nullable — The Azure endpoint for the model.
    - `azure_version` string, nullable — The Azure version for the model.
    - `azure_deployment` string, nullable — The Azure deployment for the model.
  - `response_format` union — The response format used by the agent when returning from `send_message`.
    - TextResponseFormat — Response format for plain text responses.
      - `type` 'text' — The type of the response format.
    - JsonSchemaResponseFormat — Response format for JSON schema-based responses.
      - `type` 'json_schema' — The type of the response format.
      - `json_schema` object, required — The JSON schema of the response.
    - JsonObjectResponseFormat — Response format for JSON object responses.
      - `type` 'json_object' — The type of the response format.
  - `description` string, nullable — The description of the agent.
  - `metadata` object, nullable — The metadata of the agent.
  - `memory` Memory, required — Represents the in-context memory (i.e. Core memory) of the agent. This includes both the `Block` objects (labelled by sections), as well as tools to edit the blocks.
    - `agent_type` union — Agent type controlling prompt rendering.
      - '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.
      - string
    - `blocks` Block[], required — Memory blocks contained in the agent's in-context memory
      - `value` string, required — Value of the block.
      - `limit` integer — Character limit of the block.
      - `project_id` string, nullable — The associated project id.
      - `name` string, nullable — The id of the template.
      - `is_template` boolean — Whether the block is a template (e.g. saved human/persona options).
      - `base_template_id` string, nullable — The base template id of the block.
      - `deployment_id` string, nullable — The id of the deployment.
      - `entity_id` string, nullable — The id of the entity within the template.
      - `preserve_on_migration` boolean, nullable — Preserve the block on template migration.
      - `label` string, nullable — Label of the block (e.g. 'human', 'persona') in the context window.
      - `read_only` boolean — Whether the agent has read-only access to the block.
      - `description` string, nullable — Description of the block.
      - `metadata` object, nullable — Metadata of the block.
      - `hidden` boolean, nullable — If set to True, the block will be hidden.
      - `id` string — The human-friendly ID of the Block
      - `created_by_id` string, nullable — The id of the user that made this Block.
      - `last_updated_by_id` string, nullable — The id of the user that last updated this Block.
    - `file_blocks` FileBlock[] — Special blocks representing the agent's in-context memory of an attached file
      - `value` string, required — Value of the block.
      - `limit` integer — Character limit of the block.
      - `project_id` string, nullable — The associated project id.
      - `name` string, nullable — The id of the template.
      - `is_template` boolean — Whether the block is a template (e.g. saved human/persona options).
      - `base_template_id` string, nullable — The base template id of the block.
      - `deployment_id` string, nullable — The id of the deployment.
      - `entity_id` string, nullable — The id of the entity within the template.
      - `preserve_on_migration` boolean, nullable — Preserve the block on template migration.
      - `label` string, nullable — Label of the block (e.g. 'human', 'persona') in the context window.
      - `read_only` boolean — Whether the agent has read-only access to the block.
      - `description` string, nullable — Description of the block.
      - `metadata` object, nullable — Metadata of the block.
      - `hidden` boolean, nullable — If set to True, the block will be hidden.
      - `id` string — The human-friendly ID of the Block
      - `created_by_id` string, nullable — The id of the user that made this Block.
      - `last_updated_by_id` string, nullable — The id of the user that last updated this Block.
      - `file_id` string, required — Unique identifier of the file.
      - `source_id` string, required — Unique identifier of the source.
      - `is_open` boolean, required — True if the agent currently has the file open.
      - `last_accessed_at` string, date-time, nullable — 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.
    - `prompt_template` string — Deprecated. Ignored for performance.
  - `tools` Tool[], required — The tools used by the agent.
    - `id` string — The human-friendly ID of the Tool
    - `tool_type` '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'
    - `description` string, nullable — The description of the tool.
    - `source_type` string, nullable — The type of the source code.
    - `name` string, nullable — The name of the function.
    - `tags` string[] — Metadata tags.
    - `source_code` string, nullable — The source code of the function.
    - `json_schema` object, nullable — The JSON schema of the function.
    - `args_json_schema` object, nullable — The args JSON schema of the function.
    - `return_char_limit` integer — The maximum number of characters in the response.
    - `pip_requirements` PipRequirement[], nullable — Optional list of pip packages required by this tool.
      - `name` string, required — Name of the pip package.
      - `version` string, nullable — Optional version of the package, following semantic versioning.
    - `npm_requirements` NpmRequirement[], nullable — Optional list of npm packages required by this tool.
      - `name` string, required — Name of the npm package.
      - `version` string, nullable — Optional version of the package, following semantic versioning.
    - `default_requires_approval` boolean, nullable — Default value for whether or not executing this tool requires approval.
    - `created_by_id` string, nullable — The id of the user that made this Tool.
    - `last_updated_by_id` string, nullable — The id of the user that made this Tool.
    - `metadata_` object, nullable — A dictionary of additional metadata for the tool.
  - `sources` Source[], required — The sources used by the agent.
    - `name` string, required — The name of the source.
    - `description` string, nullable — The description of the source.
    - `instructions` string, nullable — Instructions for how to use the source.
    - `metadata` object, nullable — Metadata associated with the source.
    - `id` string — The human-friendly ID of the Source
    - `embedding_config` EmbeddingConfig, required — Configuration for embedding model connection and processing parameters.
      - `embedding_endpoint_type` 'openai' | 'anthropic' | 'bedrock' | 'google_ai' | 'google_vertex' | 'azure' | 'groq' | 'ollama' | 'webui' | 'webui-legacy' | 'lmstudio' | 'lmstudio-legacy' | 'llamacpp' | 'koboldcpp' | 'vllm' | 'hugging-face' | 'mistral' | 'together' | 'pinecone', required — The endpoint type for the model.
      - `embedding_endpoint` string, nullable — The endpoint for the model (`None` if local).
      - `embedding_model` string, required — The model for the embedding.
      - `embedding_dim` integer, required — The dimension of the embedding.
      - `embedding_chunk_size` integer, nullable — The chunk size of the embedding.
      - `handle` string, nullable — The handle for this config, in the format provider/model-name.
      - `batch_size` integer — The maximum batch size for processing embeddings.
      - `azure_endpoint` string, nullable — The Azure endpoint for the model.
      - `azure_version` string, nullable — The Azure version for the model.
      - `azure_deployment` string, nullable — The Azure deployment for the model.
    - `vector_db_provider` 'native' | 'tpuf' | 'pinecone' — Supported vector database providers for archival memory
    - `created_by_id` string, nullable — The id of the user that made this Tool.
    - `last_updated_by_id` string, nullable — The id of the user that made this Tool.
    - `created_at` string, date-time, nullable — The timestamp when the source was created.
    - `updated_at` string, date-time, nullable — The timestamp when the source was last updated.
  - `tags` string[], required — The tags associated with the agent.
  - `tool_exec_environment_variables` AgentEnvironmentVariable[] — Deprecated: use `secrets` field instead.
    - `created_by_id` string, nullable — The id of the user that made this object.
    - `last_updated_by_id` string, nullable — The id of the user that made this object.
    - `created_at` string, date-time, nullable — The timestamp when the object was created.
    - `updated_at` string, date-time, nullable — The timestamp when the object was last updated.
    - `id` string — The human-friendly ID of the Agent-env
    - `key` string, required — The name of the environment variable.
    - `value` string, required — The value of the environment variable.
    - `description` string, nullable — An optional description of the environment variable.
    - `value_enc` string, nullable — Encrypted secret value (stored as encrypted string)
    - `agent_id` string, required — The ID of the agent this environment variable belongs to.
  - `secrets` AgentEnvironmentVariable[] — The environment variables for tool execution specific to this agent.
    - `created_by_id` string, nullable — The id of the user that made this object.
    - `last_updated_by_id` string, nullable — The id of the user that made this object.
    - `created_at` string, date-time, nullable — The timestamp when the object was created.
    - `updated_at` string, date-time, nullable — The timestamp when the object was last updated.
    - `id` string — The human-friendly ID of the Agent-env
    - `key` string, required — The name of the environment variable.
    - `value` string, required — The value of the environment variable.
    - `description` string, nullable — An optional description of the environment variable.
    - `value_enc` string, nullable — Encrypted secret value (stored as encrypted string)
    - `agent_id` string, required — The ID of the agent this environment variable belongs to.
  - `project_id` string, nullable — The id of the project the agent belongs to.
  - `template_id` string, nullable — The id of the template the agent belongs to.
  - `base_template_id` string, nullable — The base template id of the agent.
  - `deployment_id` string, nullable — The id of the deployment.
  - `entity_id` string, nullable — The id of the entity within the template.
  - `identity_ids` string[] — 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 use case.
  - `enable_sleeptime` boolean, nullable — If set to True, memory management will move to a background agent thread.
  - `multi_agent_group` Group
    - `id` string, required — The id of the group. Assigned by the database.
    - `manager_type` 'round_robin' | 'supervisor' | 'dynamic' | 'sleeptime' | 'voice_sleeptime' | 'swarm', required
    - `agent_ids` string[], required
    - `description` string, required
    - `project_id` string, nullable — The associated project id.
    - `template_id` string, nullable — The id of the template.
    - `base_template_id` string, nullable — The base template id.
    - `deployment_id` string, nullable — The id of the deployment.
    - `shared_block_ids` string[]
    - `manager_agent_id` string, nullable
    - `termination_token` string, nullable
    - `max_turns` integer, nullable
    - `sleeptime_agent_frequency` integer, nullable
    - `turns_counter` integer, nullable
    - `last_processed_message_id` string, nullable
    - `max_message_buffer_length` integer, nullable — 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.
    - `min_message_buffer_length` integer, nullable — 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.
    - `hidden` boolean, nullable — If set to True, the group will be hidden.
  - `last_run_completion` string, date-time, nullable — The timestamp when the agent last completed a run.
  - `last_run_duration_ms` integer, nullable — The duration in milliseconds of the agent's last run.
  - `timezone` string, nullable — The timezone of the agent (IANA format).
  - `max_files_open` integer, 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_limit` integer, 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.
  - `hidden` boolean, nullable — If set to True, the agent will be hidden.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.net/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yu-code666/letta-api/versions/6cec99480c13/schema)