# Agents ## List Agents **get** `/v1/agents/` Get a list of all agents. ### Query Parameters - `after: optional string` Cursor for pagination - `ascending: optional boolean` Whether to sort agents oldest to newest (True) or newest to oldest (False, default) - `base_template_id: optional string` Search agents by base template ID - `before: optional string` Cursor for pagination - `created_by_id: optional string` Filter agents by the user who created them. - `identifier_keys: optional array of string` Search agents by identifier keys - `identity_id: optional string` Search agents by identity ID - `include: optional array of "agent.blocks" or "agent.identities" or "agent.managed_group" or 5 more` Specify which relational fields to include in the response. No relationships are included by default. - `"agent.blocks"` - `"agent.identities"` - `"agent.managed_group"` - `"agent.pending_approval"` - `"agent.secrets"` - `"agent.sources"` - `"agent.tags"` - `"agent.tools"` - `include_relationships: optional array of string` 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: optional StopReasonType` Filter agents by their last stop reason. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `limit: optional number` Limit for pagination - `match_all_tags: optional boolean` If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags. - `name: optional string` Name of the agent - `order: optional "asc" or "desc"` Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at" or "updated_at" or "last_run_completion"` Field to sort by - `"created_at"` - `"updated_at"` - `"last_run_completion"` - `project_id: optional string` Search agents by project ID - this will default to your default project on cloud - `query_text: optional string` Search agents by name - `sort_by: optional string` Field to sort by. Options: 'created_at' (default), 'last_run_completion' - `tags: optional array of string` List of tags to filter agents by - `template_id: optional string` Search agents by template ID ### Returns - `id: string` The id of the agent. Assigned by the database. - `agent_type: AgentType` The type of agent. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/ \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ] ``` ## Create Agent **post** `/v1/agents/` Create an agent. ### Body Parameters - `agent_type: optional AgentType` The type of agent. - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `base_template_id: optional string` Deprecated: No longer used. The base template id of the agent. - `block_ids: optional array of string` The ids of the blocks used by the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `context_window_limit: optional number` The context window limit used by the agent. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_chunk_size: optional number` Deprecated: No longer used. The embedding chunk size used by the agent. - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `enable_reasoner: optional boolean` Deprecated: Use `model` field to configure reasoning instead. Whether to enable internal extended thinking step for a reasoner model. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `folder_ids: optional array of string` The ids of the folders used by the agent. - `from_template: optional string` Deprecated: please use the 'create agents from a template' endpoint instead. - `hidden: optional boolean` Deprecated: No longer used. If set to True, the agent will be hidden. - `identity_ids: optional array of string` The ids of the identities associated with this agent. - `include_base_tool_rules: optional boolean` If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed). - `include_base_tools: optional boolean` If true, attaches the Letta core tools (e.g. core_memory related functions). - `include_default_source: optional boolean` If true, automatically creates and attaches a default data source for this agent. - `initial_message_sequence: optional array of MessageCreate` The initial set of messages to put in the agent's in-context memory. - `content: array of LettaMessageContentUnion or string` The content of the message. - `array of LettaMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `string` - `role: "user" or "system" or "assistant"` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `group_id: optional string` The multi-agent group that the message was sent in - `name: optional string` The name of the participant. - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `type: optional "message"` The message type to be created. - `"message"` - `llm_config: optional LlmConfig` Configuration for Language Model (LLM) connection and generation parameters. .. deprecated:: LLMConfig is deprecated and should not be used as an input or return type in API calls. Use the schemas in letta.schemas.model (ModelSettings, OpenAIModelSettings, etc.) instead. For conversion, use the _to_model() method or Model._from_llm_config() method. - `context_window: number` The context window size for the model. - `model: string` LLM model name. - `model_endpoint_type: "openai" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `max_files_open: optional number` 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. - `max_reasoning_tokens: optional number` Deprecated: Use `model` field to configure reasoning tokens instead. The maximum number of tokens to generate for reasoning step. - `max_tokens: optional number` Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step. - `memory_blocks: optional array of CreateBlock` The blocks to create in the agent's in-context memory. - `label: string` Label of the block. - `value: string` Value of the block. - `base_template_id: optional string` The base template id of the block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags to associate with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `memory_variables: optional map[string]` Deprecated: Only relevant for creating agents from a template. Use the 'create agents from a template' endpoint instead. - `message_buffer_autoclear: optional 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. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle for the agent to use (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings for the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `name: optional string` The name of the agent. - `parallel_tool_calls: optional boolean` Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling. - `per_file_view_window_char_limit: optional number` 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: optional string` 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. - `project_id: optional string` Deprecated: No longer used. The id of the project the agent belongs to. - `reasoning: optional boolean` Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional map[string]` The environment variables for tool execution specific to this agent. - `source_ids: optional array of string` Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent. - `system: optional string` The system prompt used by the agent. - `tags: optional array of string` The tags associated with the agent. - `template: optional boolean` Deprecated: No longer used. - `template_id: optional string` Deprecated: No longer used. The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional map[string]` Deprecated: Use `secrets` field instead. Environment variables for tool execution. - `tool_ids: optional array of string` The ids of the tools used by the agent. - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The tool rules governing the agent. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `tools: optional array of string` The tools used by the agent. ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/ \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{}' ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Update Agent **patch** `/v1/agents/{agent_id}` Update an existing agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `base_template_id: optional string` The base template id of the agent. - `block_ids: optional array of string` The ids of the blocks used by the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `context_window_limit: optional number` The context window limit used by the agent. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `folder_ids: optional array of string` The ids of the folders used by the agent. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identity_ids: optional array of string` The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `llm_config: optional LlmConfig` Configuration for Language Model (LLM) connection and generation parameters. .. deprecated:: LLMConfig is deprecated and should not be used as an input or return type in API calls. Use the schemas in letta.schemas.model (ModelSettings, OpenAIModelSettings, etc.) instead. For conversion, use the _to_model() method or Model._from_llm_config() method. - `context_window: number` The context window size for the model. - `model: string` LLM model name. - `model_endpoint_type: "openai" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `max_files_open: optional number` 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. - `max_tokens: optional number` Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step. - `message_buffer_autoclear: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings for the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `name: optional string` The name of the agent. - `parallel_tool_calls: optional boolean` Deprecated: Use `model_settings` to configure parallel tool calls instead. If set to True, enables parallel tool calling. - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `reasoning: optional boolean` Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional map[string]` The environment variables for tool execution specific to this agent. - `source_ids: optional array of string` Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent. - `system: optional string` The system prompt used by the agent. - `tags: optional array of string` The tags associated with the agent. - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional map[string]` Deprecated: use `secrets` field instead - `tool_ids: optional array of string` The ids of the tools used by the agent. - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The tool rules governing the agent. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{}' ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Retrieve Agent **get** `/v1/agents/{agent_id}` Get the state of the agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `include: optional array of "agent.blocks" or "agent.identities" or "agent.managed_group" or 5 more` Specify which relational fields to include in the response. No relationships are included by default. - `"agent.blocks"` - `"agent.identities"` - `"agent.managed_group"` - `"agent.pending_approval"` - `"agent.secrets"` - `"agent.sources"` - `"agent.tags"` - `"agent.tools"` - `include_relationships: optional array of string` 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. ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Delete Agent **delete** `/v1/agents/{agent_id}` Delete an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID \ -X DELETE \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## Export Agent **get** `/v1/agents/{agent_id}/export` Export the serialized JSON representation of an agent, formatted with indentation. ### Path Parameters - `agent_id: string` ### Query Parameters - `conversation_id: optional string` Conversation ID to export. If provided, uses messages from this conversation instead of the agent's global message history. - `max_steps: optional number` - `scrub_messages: optional boolean` If True, excludes all messages from the export. Useful for sharing agent configs without conversation history. - `use_legacy_format: optional boolean` If True, exports using the legacy single-agent 'v1' format with inline tools/blocks. If False, exports using the new multi-entity 'v2' format, with separate agents, tools, blocks, files, etc. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/export \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json "string" ``` ## Import Agent **post** `/v1/agents/import` Import a serialized agent file and recreate the agent(s) in the system. Returns the IDs of all imported agents. ### Header Parameters - `"x-override-embedding-model": optional string` ### Returns - `agent_ids: array of string` List of IDs of the imported agents ### Example ```http curl https://api.letta.com/v1/agents/import \ -H 'Content-Type: multipart/form-data' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -F 'file=@/path/to/file' ``` #### Response ```json { "agent_ids": [ "string" ] } ``` ## Recompile Agent **post** `/v1/agents/{agent_id}/recompile` Manually trigger system prompt recompilation for an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `dry_run: optional boolean` If True, do not persist changes; still returns the compiled system prompt. - `update_timestamp: optional boolean` If True, update the in-context memory last edit timestamp embedded in the system prompt. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/recompile \ -X POST \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json "string" ``` ## Domain Types ### Agent Environment Variable - `AgentEnvironmentVariable object { agent_id, key, value, 7 more }` - `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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) ### Agent State - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Agent Type - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` ### Anthropic Model Settings - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` ### Azure Model Settings - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. ### Bedrock Model Settings - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. ### Child Tool Rule - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` ### Conditional Tool Rule - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` ### Continue Tool Rule - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` ### Deepseek Model Settings - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. ### Google AI Model Settings - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. ### Google Vertex Model Settings - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. ### Groq Model Settings - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. ### Init Tool Rule - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` ### Json Object Response Format - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` ### Json Schema Response Format - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` ### Letta Message Content Union - `LettaMessageContentUnion = TextContent or ImageContent or ToolCallContent or 4 more` Sent via the Anthropic Messages API - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` ### Max Count Per Step Tool Rule - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` ### Message Create - `MessageCreate object { content, role, batch_item_id, 5 more }` Request to create a message - `content: array of LettaMessageContentUnion or string` The content of the message. - `array of LettaMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `string` - `role: "user" or "system" or "assistant"` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `group_id: optional string` The multi-agent group that the message was sent in - `name: optional string` The name of the participant. - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `type: optional "message"` The message type to be created. - `"message"` ### OpenAI Model Settings - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. ### Parent Tool Rule - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` ### Required Before Exit Tool Rule - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` ### Requires Approval Tool Rule - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` ### Terminal Tool Rule - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` ### Text Response Format - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` ### Together Model Settings - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. ### Xai Model Settings - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `temperature: optional number` The temperature of the model. ### Agent Delete Response - `AgentDeleteResponse = unknown` ### Agent Export File Response - `AgentExportFileResponse = string` ### Agent Import File Response - `AgentImportFileResponse object { agent_ids }` Response model for imported agents - `agent_ids: array of string` List of IDs of the imported agents ### Agent Recompile Response - `AgentRecompileResponse = string` # Messages ## List Messages **get** `/v1/agents/{agent_id}/messages` Retrieve message history for an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `after: optional string` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `assistant_message_tool_kwarg: optional string` The name of the message argument. - `assistant_message_tool_name: optional string` The name of the designated message tool. - `before: optional string` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `conversation_id: optional string` Conversation ID to filter messages by. - `group_id: optional string` Group ID to filter messages by. - `include_err: optional boolean` Whether to include error messages and error statuses. For debugging purposes only. - `include_return_message_types: optional array of MessageType` Message types to include in response. When null, all message types are returned. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `limit: optional number` Maximum number of messages to return - `order: optional "asc" or "desc"` Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` - `use_assistant_message: optional boolean` Whether to use assistant messages ### Returns - `SystemMessage object { id, content, date, 8 more }` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `UserMessage object { id, content, date, 8 more }` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ReasoningMessage object { id, date, reasoning, 10 more }` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` - `HiddenReasoningMessage object { id, date, state, 9 more }` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ToolCallMessage object { id, date, tool_call, 9 more }` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ToolReturnMessage object { id, date, status, 13 more }` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err: optional boolean` - `message_type: optional "tool_return_message"` The type of the message. - `"tool_return_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `stderr: optional array of string` - `stdout: optional array of string` - `step_id: optional string` - `tool_returns: optional array of ToolReturn` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `AssistantMessage object { id, content, date, 8 more }` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ApprovalRequestMessage object { id, date, tool_call, 9 more }` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `ToolCallDelta object { arguments, name, tool_call_id }` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ApprovalResponseMessage object { id, date, approval_request_id, 11 more }` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `SummaryMessage object { id, date, summary, 9 more }` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: optional number` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: optional number` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: optional boolean` - `message_type: optional "summary_message"` - `"summary_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `EventMessage object { id, date, event_data, 9 more }` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: map[unknown]` - `event_type: "compaction"` - `"compaction"` - `is_err: optional boolean` - `message_type: optional "event_message"` - `"event_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/messages \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "id": "id", "content": "content", "date": "2019-12-27T18:11:19.117Z", "is_err": true, "message_type": "system_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id" } ] ``` ## Create Message **post** `/v1/agents/{agent_id}/messages` Process a user message and return the agent's response. This endpoint accepts a message from a user and processes it through the agent. **Note:** Sending multiple concurrent requests to the same agent can lead to undefined behavior. Each agent processes messages sequentially, and concurrent requests may interleave in unexpected ways. Wait for each request to complete before sending the next one. Use separate agents or conversations for parallel processing. The response format is controlled by the `streaming` field in the request body: - If `streaming=false` (default): Returns a complete LettaResponse with all messages - If `streaming=true`: Returns a Server-Sent Events (SSE) stream Additional streaming options (only used when streaming=true): - `stream_tokens`: Stream individual tokens instead of complete steps - `include_pings`: Include keepalive pings to prevent connection timeouts - `background`: Process the request in the background ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `assistant_message_tool_name: optional string` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `background: optional boolean` Whether to process the request in the background (only used when streaming=true). - `client_skills: optional array of object { description, location, name }` Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. - `description: string` Description of what the skill does - `location: string` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: string` The name of the skill - `client_tools: optional array of object { name, description, parameters }` Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. - `name: string` The name of the tool function - `description: optional string` Description of what the tool does - `parameters: optional map[unknown]` JSON Schema for the function parameters - `enable_thinking: optional string` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: optional boolean` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_pings: optional boolean` Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `input: optional string or array of TextContent or ImageContent or ToolCallContent or 5 more` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `string` - `array of TextContent or ImageContent or ToolCallContent or 5 more` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoning object { id, summary, encrypted_content, type }` The style of reasoning content returned by the OpenAI Responses API - `id: string` The unique identifier for this reasoning step. - `summary: array of object { index, text }` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content: optional string` The encrypted reasoning content. - `type: optional "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: optional number` Maximum number of steps the agent should take to process the request. - `messages: optional array of MessageCreate or ApprovalCreate or object { tool_returns, group_id, otid, type }` The messages to be sent to the agent. - `MessageCreate object { content, role, batch_item_id, 5 more }` Request to create a message - `content: array of LettaMessageContentUnion or string` The content of the message. - `array of LettaMessageContentUnion` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `ToolCallContent object { id, input, name, 2 more }` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `string` - `role: "user" or "system" or "assistant"` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `group_id: optional string` The multi-agent group that the message was sent in - `name: optional string` The name of the participant. - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `type: optional "message"` The message type to be created. - `"message"` - `ApprovalCreate object { approval_request_id, approvals, approve, 4 more }` Input to approve or deny a tool call request - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `approve: optional boolean` Whether the tool has been approved - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturnCreate object { tool_returns, group_id, otid, type }` Submit tool return(s) from client-side tool execution. This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case. - `tool_returns: array of ToolReturn` List of tool returns from client-side execution - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `type: optional "tool_return"` The message type to be created. - `"tool_return"` - `override_model: optional string` Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. - `override_system: optional string` Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. - `return_logprobs: optional boolean` If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). - `return_token_ids: optional boolean` If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. - `stream_tokens: optional boolean` Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). - `streaming: optional boolean` If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. ### Returns - `LettaResponse object { messages, stop_reason, usage, 2 more }` Response object from an agent interaction, consisting of the new messages generated by the agent and usage statistics. The type of the returned messages can be either `Message` or `LettaMessage`, depending on what was specified in the request. Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned by the agent. usage (LettaUsageStatistics): The usage statistics - `messages: array of Message` The messages returned by the agent. - `SystemMessage object { id, content, date, 8 more }` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `UserMessage object { id, content, date, 8 more }` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ReasoningMessage object { id, date, reasoning, 10 more }` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` - `HiddenReasoningMessage object { id, date, state, 9 more }` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ToolCallMessage object { id, date, tool_call, 9 more }` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ToolReturnMessage object { id, date, status, 13 more }` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err: optional boolean` - `message_type: optional "tool_return_message"` The type of the message. - `"tool_return_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `stderr: optional array of string` - `stdout: optional array of string` - `step_id: optional string` - `tool_returns: optional array of ToolReturn` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `AssistantMessage object { id, content, date, 8 more }` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ApprovalRequestMessage object { id, date, tool_call, 9 more }` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `ToolCallDelta object { arguments, name, tool_call_id }` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ApprovalResponseMessage object { id, date, approval_request_id, 11 more }` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `SummaryMessage object { id, date, summary, 9 more }` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: optional number` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: optional number` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: optional boolean` - `message_type: optional "summary_message"` - `"summary_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `EventMessage object { id, date, event_data, 9 more }` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: map[unknown]` - `event_type: "compaction"` - `"compaction"` - `is_err: optional boolean` - `message_type: optional "event_message"` - `"event_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `stop_reason: object { stop_reason, message_type }` The stop reason from Letta indicating why agent loop stopped execution. - `stop_reason: StopReasonType` The reason why execution stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `message_type: optional "stop_reason"` The type of the message. - `"stop_reason"` - `usage: object { cache_write_tokens, cached_input_tokens, completion_tokens, 7 more }` The usage statistics of the agent. - `cache_write_tokens: optional number` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: optional number` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: optional number` The number of tokens generated by the agent. - `context_tokens: optional number` Estimate of tokens currently in the context window. - `message_type: optional "usage_statistics"` - `"usage_statistics"` - `prompt_tokens: optional number` The number of tokens in the prompt. - `reasoning_tokens: optional number` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: optional array of string` The background task run IDs associated with the agent interaction - `step_count: optional number` The number of steps taken by the agent. - `total_tokens: optional number` The total number of tokens processed by the agent. - `logprobs: optional object { content, refusal }` Log probabilities of the output tokens from the last LLM call. Only present if return_logprobs was enabled. - `content: optional array of object { token, logprob, top_logprobs, bytes }` - `token: string` - `logprob: number` - `top_logprobs: array of object { token, logprob, bytes }` - `token: string` - `logprob: number` - `bytes: optional array of number` - `bytes: optional array of number` - `refusal: optional array of object { token, logprob, top_logprobs, bytes }` - `token: string` - `logprob: number` - `top_logprobs: array of object { token, logprob, bytes }` - `token: string` - `logprob: number` - `bytes: optional array of number` - `bytes: optional array of number` - `turns: optional array of object { role, content, output_ids, 2 more }` Token data for all LLM generations in multi-turn agent interaction. Includes token IDs and logprobs for each assistant turn, plus tool result content. Only present if return_token_ids was enabled. Used for RL training with loss masking. - `role: "assistant" or "tool"` Role of this turn: 'assistant' for LLM generations (trainable), 'tool' for tool results (non-trainable). - `"assistant"` - `"tool"` - `content: optional string` Text content. For tool turns, client tokenizes this with loss_mask=0. - `output_ids: optional array of number` Token IDs from SGLang native endpoint. Only present for assistant turns. - `output_token_logprobs: optional array of array of unknown` Logprobs from SGLang: [[logprob, token_id, top_logprob_or_null], ...]. Only present for assistant turns. - `tool_name: optional string` Name of the tool called. Only present for tool turns. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/messages \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{}' ``` #### Response ```json { "messages": [ { "id": "id", "content": "content", "date": "2019-12-27T18:11:19.117Z", "is_err": true, "message_type": "system_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id" } ], "stop_reason": { "stop_reason": "end_turn", "message_type": "stop_reason" }, "usage": { "cache_write_tokens": 0, "cached_input_tokens": 0, "completion_tokens": 0, "context_tokens": 0, "message_type": "usage_statistics", "prompt_tokens": 0, "reasoning_tokens": 0, "run_ids": [ "string" ], "step_count": 0, "total_tokens": 0 }, "logprobs": { "content": [ { "token": "token", "logprob": 0, "top_logprobs": [ { "token": "token", "logprob": 0, "bytes": [ 0 ] } ], "bytes": [ 0 ] } ], "refusal": [ { "token": "token", "logprob": 0, "top_logprobs": [ { "token": "token", "logprob": 0, "bytes": [ 0 ] } ], "bytes": [ 0 ] } ] }, "turns": [ { "role": "assistant", "content": "content", "output_ids": [ 0 ], "output_token_logprobs": [ [ {} ] ], "tool_name": "tool_name" } ] } ``` ## Create Message Streaming **post** `/v1/agents/{agent_id}/messages/stream` Process a user message and return the agent's response. Deprecated: Use the `POST /{agent_id}/messages` endpoint with `streaming=true` in the request body instead. **Note:** Sending multiple concurrent requests to the same agent can lead to undefined behavior. Each agent processes messages sequentially, and concurrent requests may interleave in unexpected ways. Wait for each request to complete before sending the next one. Use separate agents or conversations for parallel processing. This endpoint accepts a message from a user and processes it through the agent. It will stream the steps of the response always, and stream the tokens if 'stream_tokens' is set to True. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `assistant_message_tool_name: optional string` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `background: optional boolean` Whether to process the request in the background (only used when streaming=true). - `client_skills: optional array of object { description, location, name }` Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. - `description: string` Description of what the skill does - `location: string` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: string` The name of the skill - `client_tools: optional array of object { name, description, parameters }` Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. - `name: string` The name of the tool function - `description: optional string` Description of what the tool does - `parameters: optional map[unknown]` JSON Schema for the function parameters - `enable_thinking: optional string` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: optional boolean` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_pings: optional boolean` Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `input: optional string or array of TextContent or ImageContent or ToolCallContent or 5 more` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `string` - `array of TextContent or ImageContent or ToolCallContent or 5 more` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoning object { id, summary, encrypted_content, type }` The style of reasoning content returned by the OpenAI Responses API - `id: string` The unique identifier for this reasoning step. - `summary: array of object { index, text }` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content: optional string` The encrypted reasoning content. - `type: optional "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: optional number` Maximum number of steps the agent should take to process the request. - `messages: optional array of MessageCreate or ApprovalCreate or object { tool_returns, group_id, otid, type }` The messages to be sent to the agent. - `MessageCreate object { content, role, batch_item_id, 5 more }` Request to create a message - `content: array of LettaMessageContentUnion or string` The content of the message. - `array of LettaMessageContentUnion` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `ToolCallContent object { id, input, name, 2 more }` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `string` - `role: "user" or "system" or "assistant"` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `group_id: optional string` The multi-agent group that the message was sent in - `name: optional string` The name of the participant. - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `type: optional "message"` The message type to be created. - `"message"` - `ApprovalCreate object { approval_request_id, approvals, approve, 4 more }` Input to approve or deny a tool call request - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `approve: optional boolean` Whether the tool has been approved - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturnCreate object { tool_returns, group_id, otid, type }` Submit tool return(s) from client-side tool execution. This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case. - `tool_returns: array of ToolReturn` List of tool returns from client-side execution - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `type: optional "tool_return"` The message type to be created. - `"tool_return"` - `override_model: optional string` Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. - `override_system: optional string` Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. - `return_logprobs: optional boolean` If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). - `return_token_ids: optional boolean` If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. - `stream_tokens: optional boolean` Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). - `streaming: optional boolean` If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. ### Returns - `LettaStreamingResponse = SystemMessage or UserMessage or ReasoningMessage or 10 more` Streaming response type for Server-Sent Events (SSE) endpoints. Each event in the stream will be one of these types. - `SystemMessage object { id, content, date, 8 more }` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `UserMessage object { id, content, date, 8 more }` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ReasoningMessage object { id, date, reasoning, 10 more }` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` - `HiddenReasoningMessage object { id, date, state, 9 more }` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ToolCallMessage object { id, date, tool_call, 9 more }` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ToolReturnMessage object { id, date, status, 13 more }` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err: optional boolean` - `message_type: optional "tool_return_message"` The type of the message. - `"tool_return_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `stderr: optional array of string` - `stdout: optional array of string` - `step_id: optional string` - `tool_returns: optional array of ToolReturn` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `AssistantMessage object { id, content, date, 8 more }` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ApprovalRequestMessage object { id, date, tool_call, 9 more }` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `ToolCallDelta object { arguments, name, tool_call_id }` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ApprovalResponseMessage object { id, date, approval_request_id, 11 more }` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `Ping object { id, date, is_err, 7 more }` A ping message used as a keepalive to prevent SSE streams from timing out during long running requests. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format - `id: string` - `date: string` - `is_err: optional boolean` - `message_type: optional "ping"` The type of the message. Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests. - `"ping"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ErrorMessage object { error_type, message, message_type, 3 more }` Error messages are used to notify the client of an error that occurred during the agent's execution. - `error_type: string` The type of error. - `message: string` The error message. - `message_type: "error_message"` The type of the message. - `"error_message"` - `run_id: string` The ID of the run. - `detail: optional string` An optional error detail. - `seq_id: optional number` The sequence ID for cursor-based pagination. - `StopReason object { stop_reason, message_type }` The stop reason from Letta indicating why agent loop stopped execution. - `stop_reason: StopReasonType` The reason why execution stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `message_type: optional "stop_reason"` The type of the message. - `"stop_reason"` - `UsageStatistics object { cache_write_tokens, cached_input_tokens, completion_tokens, 7 more }` Usage statistics for the agent interaction. Attributes: completion_tokens (int): The number of tokens generated by the agent. prompt_tokens (int): The number of tokens in the prompt. total_tokens (int): The total number of tokens processed by the agent. step_count (int): The number of steps taken by the agent. cached_input_tokens (Optional[int]): The number of input tokens served from cache. None if not reported. cache_write_tokens (Optional[int]): The number of input tokens written to cache. None if not reported. reasoning_tokens (Optional[int]): The number of reasoning/thinking tokens generated. None if not reported. - `cache_write_tokens: optional number` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: optional number` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: optional number` The number of tokens generated by the agent. - `context_tokens: optional number` Estimate of tokens currently in the context window. - `message_type: optional "usage_statistics"` - `"usage_statistics"` - `prompt_tokens: optional number` The number of tokens in the prompt. - `reasoning_tokens: optional number` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: optional array of string` The background task run IDs associated with the agent interaction - `step_count: optional number` The number of steps taken by the agent. - `total_tokens: optional number` The total number of tokens processed by the agent. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/messages/stream \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "id", "content": "content", "date": "2019-12-27T18:11:19.117Z", "is_err": true, "message_type": "system_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id" } ``` ## Cancel Message **post** `/v1/agents/{agent_id}/messages/cancel` Cancel runs associated with an agent. If run_ids are passed in, cancel those in particular. Note to cancel active runs associated with an agent, redis is required. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `run_ids: optional array of string` Optional list of run IDs to cancel ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/messages/cancel \ -X POST \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "foo": "bar" } ``` ## Create Message Async **post** `/v1/agents/{agent_id}/messages/async` Asynchronously process a user message and return a run object. The actual processing happens in the background, and the status can be checked using the run ID. This is "asynchronous" in the sense that it's a background run and explicitly must be fetched by the run ID. **Note:** Sending multiple concurrent requests to the same agent can lead to undefined behavior. Each agent processes messages sequentially, and concurrent requests may interleave in unexpected ways. Wait for each request to complete before sending the next one. Use separate agents or conversations for parallel processing. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `assistant_message_tool_name: optional string` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `callback_url: optional string` Optional callback URL to POST to when the job completes - `client_skills: optional array of object { description, location, name }` Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. - `description: string` Description of what the skill does - `location: string` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: string` The name of the skill - `client_tools: optional array of object { name, description, parameters }` Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. - `name: string` The name of the tool function - `description: optional string` Description of what the tool does - `parameters: optional map[unknown]` JSON Schema for the function parameters - `enable_thinking: optional string` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: optional boolean` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `input: optional string or array of TextContent or ImageContent or ToolCallContent or 5 more` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `string` - `array of TextContent or ImageContent or ToolCallContent or 5 more` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoning object { id, summary, encrypted_content, type }` The style of reasoning content returned by the OpenAI Responses API - `id: string` The unique identifier for this reasoning step. - `summary: array of object { index, text }` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content: optional string` The encrypted reasoning content. - `type: optional "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: optional number` Maximum number of steps the agent should take to process the request. - `messages: optional array of MessageCreate or ApprovalCreate or object { tool_returns, group_id, otid, type }` The messages to be sent to the agent. - `MessageCreate object { content, role, batch_item_id, 5 more }` Request to create a message - `content: array of LettaMessageContentUnion or string` The content of the message. - `array of LettaMessageContentUnion` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `ToolCallContent object { id, input, name, 2 more }` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `string` - `role: "user" or "system" or "assistant"` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `group_id: optional string` The multi-agent group that the message was sent in - `name: optional string` The name of the participant. - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `type: optional "message"` The message type to be created. - `"message"` - `ApprovalCreate object { approval_request_id, approvals, approve, 4 more }` Input to approve or deny a tool call request - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `approve: optional boolean` Whether the tool has been approved - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturnCreate object { tool_returns, group_id, otid, type }` Submit tool return(s) from client-side tool execution. This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case. - `tool_returns: array of ToolReturn` List of tool returns from client-side execution - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `type: optional "tool_return"` The message type to be created. - `"tool_return"` - `override_model: optional string` Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. - `override_system: optional string` Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. - `return_logprobs: optional boolean` If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). - `return_token_ids: optional boolean` If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. ### Returns - `Run object { id, agent_id, background, 14 more }` Representation of a run - a conversation or processing session for an agent. Runs track when agents process messages and maintain the relationship between agents, steps, and messages. - `id: string` The human-friendly ID of the Run - `agent_id: string` The unique identifier of the agent associated with the run. - `background: optional boolean` Whether the run was created in background mode. - `base_template_id: optional string` The base template ID that the run belongs to. - `callback_error: optional string` Optional error message from attempting to POST the callback endpoint. - `callback_sent_at: optional string` Timestamp when the callback was last attempted. - `callback_status_code: optional number` HTTP status code returned by the callback endpoint. - `callback_url: optional string` If set, POST to this URL when the run completes. - `completed_at: optional string` The timestamp when the run was completed. - `conversation_id: optional string` The unique identifier of the conversation associated with the run. - `created_at: optional string` The timestamp when the run was created. - `metadata: optional map[unknown]` Additional metadata for the run. - `request_config: optional object { assistant_message_tool_kwarg, assistant_message_tool_name, include_return_message_types, use_assistant_message }` The request configuration for the run. - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. - `assistant_message_tool_name: optional string` The name of the designated message tool. - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. - `status: optional "created" or "running" or "completed" or 2 more` The current status of the run. - `"created"` - `"running"` - `"completed"` - `"failed"` - `"cancelled"` - `stop_reason: optional StopReasonType` The reason why the run was stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `total_duration_ns: optional number` Total run duration in nanoseconds - `ttft_ns: optional number` Time to first token for a run in nanoseconds ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/messages/async \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "run-123e4567-e89b-12d3-a456-426614174000", "agent_id": "agent_id", "background": true, "base_template_id": "base_template_id", "callback_error": "callback_error", "callback_sent_at": "2019-12-27T18:11:19.117Z", "callback_status_code": 0, "callback_url": "callback_url", "completed_at": "2019-12-27T18:11:19.117Z", "conversation_id": "conversation_id", "created_at": "2019-12-27T18:11:19.117Z", "metadata": { "foo": "bar" }, "request_config": { "assistant_message_tool_kwarg": "assistant_message_tool_kwarg", "assistant_message_tool_name": "assistant_message_tool_name", "include_return_message_types": [ "system_message" ], "use_assistant_message": true }, "status": "created", "stop_reason": "end_turn", "total_duration_ns": 0, "ttft_ns": 0 } ``` ## Reset Messages **patch** `/v1/agents/{agent_id}/reset-messages` Resets the messages for an agent ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `add_default_initial_messages: optional boolean` If true, adds the default initial messages after resetting. ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/reset-messages \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{}' ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Summarize Messages **post** `/v1/agents/{agent_id}/summarize` Summarize an agent's conversation history. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). ### Returns - `CompactionResponse object { num_messages_after, num_messages_before, summary }` - `num_messages_after: number` - `num_messages_before: number` - `summary: string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/summarize \ -X POST \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "num_messages_after": 0, "num_messages_before": 0, "summary": "summary" } ``` ## Domain Types ### Approval Create - `ApprovalCreate object { approval_request_id, approvals, approve, 4 more }` Input to approve or deny a tool call request - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `approve: optional boolean` Whether the tool has been approved - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` ### Approval Request Message - `ApprovalRequestMessage object { id, date, tool_call, 9 more }` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` ### Approval Response Message - `ApprovalResponseMessage object { id, date, approval_request_id, 11 more }` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Approval Return - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` ### Assistant Message - `AssistantMessage object { id, content, date, 8 more }` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Event Message - `EventMessage object { id, date, event_data, 9 more }` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: map[unknown]` - `event_type: "compaction"` - `"compaction"` - `is_err: optional boolean` - `message_type: optional "event_message"` - `"event_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Hidden Reasoning Message - `HiddenReasoningMessage object { id, date, state, 9 more }` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Image Content - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` ### Internal Message - `InternalMessage object { id, role, agent_id, 22 more }` Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats. Attributes: id (str): The unique identifier of the message. role (MessageRole): The role of the participant. text (str): The text of the message. user_id (str): The unique identifier of the user. agent_id (str): The unique identifier of the agent. model (str): The model used to make the function call. name (str): The name of the participant. created_at (datetime): The time the message was created. tool_calls (List[OpenAIToolCall,]): The list of tool calls requested. tool_call_id (str): The id of the tool call. step_id (str): The id of the step that this message was created in. otid (str): The offline threading id associated with this message. tool_returns (List[ToolReturn]): The list of tool returns requested. group_id (str): The multi-agent group that the message was sent in. sender_id (str): The id of the sender of the message, can be an identity id or agent id. conversation_id (str): The conversation this message belongs to. t - `id: string` The human-friendly ID of the Message - `role: MessageRole` The role of the participant. - `"assistant"` - `"user"` - `"tool"` - `"function"` - `"system"` - `"approval"` - `"summary"` - `agent_id: optional string` The unique identifier of the agent. - `approval_request_id: optional string` The id of the approval request if this message is associated with a tool call request. - `approvals: optional array of ApprovalReturn or object { status, func_response, stderr, 2 more }` The list of approvals for this message. - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `LettaSchemasMessageToolReturnOutput object { status, func_response, stderr, 2 more }` - `status: "success" or "error"` The status of the tool call - `"success"` - `"error"` - `func_response: optional string or array of TextContent or ImageContent` The function response - either a string or list of content parts (text/image) - `string` - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `stderr: optional array of string` Captured stderr from the tool invocation - `stdout: optional array of string` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id: optional unknown` The ID for the tool call - `approve: optional boolean` Whether tool call is approved. - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `content: optional array of TextContent or ImageContent or ToolCallContent or 5 more` The content of the message. - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoning object { id, summary, encrypted_content, type }` The style of reasoning content returned by the OpenAI Responses API - `id: string` The unique identifier for this reasoning step. - `summary: array of object { index, text }` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content: optional string` The encrypted reasoning content. - `type: optional "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `conversation_id: optional string` The conversation this message belongs to - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `denial_reason: optional string` The reason the tool call request was denied. - `group_id: optional string` The multi-agent group that the message was sent in - `is_err: optional boolean` Whether this message is part of an error step. Used only for debugging purposes. - `last_updated_by_id: optional string` The id of the user that made this object. - `model: optional string` The model used to make the function call. - `name: optional string` For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called. - `otid: optional string` The offline threading id associated with this message - `run_id: optional string` The id of the run that this message was created in. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `step_id: optional string` The id of the step that this message was created in. - `tool_call_id: optional string` The ID of the tool call. Only applicable for role tool. - `tool_calls: optional array of object { id, function, type }` The list of tool calls requested. Only applicable for role assistant. - `id: string` - `function: object { arguments, name }` The function that the model called. - `arguments: string` - `name: string` - `type: "function"` - `"function"` - `tool_returns: optional array of object { status, func_response, stderr, 2 more }` Tool execution return information for prior tool calls - `status: "success" or "error"` The status of the tool call - `"success"` - `"error"` - `func_response: optional string or array of TextContent or ImageContent` The function response - either a string or list of content parts (text/image) - `string` - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `stderr: optional array of string` Captured stderr from the tool invocation - `stdout: optional array of string` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id: optional unknown` The ID for the tool call - `updated_at: optional string` The timestamp when the object was last updated. ### Job Status - `JobStatus = "created" or "running" or "completed" or 4 more` Status of the job. - `"created"` - `"running"` - `"completed"` - `"failed"` - `"pending"` - `"cancelled"` - `"expired"` ### Job Type - `JobType = "job" or "run" or "batch"` - `"job"` - `"run"` - `"batch"` ### Letta Assistant Message Content Union - `LettaAssistantMessageContentUnion object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` ### Letta Request - `LettaRequest object { assistant_message_tool_kwarg, assistant_message_tool_name, client_skills, 13 more }` - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `assistant_message_tool_name: optional string` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `client_skills: optional array of object { description, location, name }` Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. - `description: string` Description of what the skill does - `location: string` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: string` The name of the skill - `client_tools: optional array of object { name, description, parameters }` Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. - `name: string` The name of the tool function - `description: optional string` Description of what the tool does - `parameters: optional map[unknown]` JSON Schema for the function parameters - `enable_thinking: optional string` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: optional boolean` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `input: optional string or array of TextContent or ImageContent or ToolCallContent or 5 more` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `string` - `array of TextContent or ImageContent or ToolCallContent or 5 more` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoning object { id, summary, encrypted_content, type }` The style of reasoning content returned by the OpenAI Responses API - `id: string` The unique identifier for this reasoning step. - `summary: array of object { index, text }` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content: optional string` The encrypted reasoning content. - `type: optional "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: optional number` Maximum number of steps the agent should take to process the request. - `messages: optional array of MessageCreate or ApprovalCreate or object { tool_returns, group_id, otid, type }` The messages to be sent to the agent. - `MessageCreate object { content, role, batch_item_id, 5 more }` Request to create a message - `content: array of LettaMessageContentUnion or string` The content of the message. - `array of LettaMessageContentUnion` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `ToolCallContent object { id, input, name, 2 more }` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `string` - `role: "user" or "system" or "assistant"` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `group_id: optional string` The multi-agent group that the message was sent in - `name: optional string` The name of the participant. - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `type: optional "message"` The message type to be created. - `"message"` - `ApprovalCreate object { approval_request_id, approvals, approve, 4 more }` Input to approve or deny a tool call request - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `approve: optional boolean` Whether the tool has been approved - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturnCreate object { tool_returns, group_id, otid, type }` Submit tool return(s) from client-side tool execution. This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case. - `tool_returns: array of ToolReturn` List of tool returns from client-side execution - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `type: optional "tool_return"` The message type to be created. - `"tool_return"` - `override_model: optional string` Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. - `override_system: optional string` Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. - `return_logprobs: optional boolean` If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). - `return_token_ids: optional boolean` If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. ### Letta Response - `LettaResponse object { messages, stop_reason, usage, 2 more }` Response object from an agent interaction, consisting of the new messages generated by the agent and usage statistics. The type of the returned messages can be either `Message` or `LettaMessage`, depending on what was specified in the request. Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned by the agent. usage (LettaUsageStatistics): The usage statistics - `messages: array of Message` The messages returned by the agent. - `SystemMessage object { id, content, date, 8 more }` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `UserMessage object { id, content, date, 8 more }` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ReasoningMessage object { id, date, reasoning, 10 more }` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` - `HiddenReasoningMessage object { id, date, state, 9 more }` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ToolCallMessage object { id, date, tool_call, 9 more }` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ToolReturnMessage object { id, date, status, 13 more }` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err: optional boolean` - `message_type: optional "tool_return_message"` The type of the message. - `"tool_return_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `stderr: optional array of string` - `stdout: optional array of string` - `step_id: optional string` - `tool_returns: optional array of ToolReturn` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `AssistantMessage object { id, content, date, 8 more }` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ApprovalRequestMessage object { id, date, tool_call, 9 more }` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `ToolCallDelta object { arguments, name, tool_call_id }` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ApprovalResponseMessage object { id, date, approval_request_id, 11 more }` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `SummaryMessage object { id, date, summary, 9 more }` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: optional number` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: optional number` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: optional boolean` - `message_type: optional "summary_message"` - `"summary_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `EventMessage object { id, date, event_data, 9 more }` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: map[unknown]` - `event_type: "compaction"` - `"compaction"` - `is_err: optional boolean` - `message_type: optional "event_message"` - `"event_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `stop_reason: object { stop_reason, message_type }` The stop reason from Letta indicating why agent loop stopped execution. - `stop_reason: StopReasonType` The reason why execution stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `message_type: optional "stop_reason"` The type of the message. - `"stop_reason"` - `usage: object { cache_write_tokens, cached_input_tokens, completion_tokens, 7 more }` The usage statistics of the agent. - `cache_write_tokens: optional number` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: optional number` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: optional number` The number of tokens generated by the agent. - `context_tokens: optional number` Estimate of tokens currently in the context window. - `message_type: optional "usage_statistics"` - `"usage_statistics"` - `prompt_tokens: optional number` The number of tokens in the prompt. - `reasoning_tokens: optional number` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: optional array of string` The background task run IDs associated with the agent interaction - `step_count: optional number` The number of steps taken by the agent. - `total_tokens: optional number` The total number of tokens processed by the agent. - `logprobs: optional object { content, refusal }` Log probabilities of the output tokens from the last LLM call. Only present if return_logprobs was enabled. - `content: optional array of object { token, logprob, top_logprobs, bytes }` - `token: string` - `logprob: number` - `top_logprobs: array of object { token, logprob, bytes }` - `token: string` - `logprob: number` - `bytes: optional array of number` - `bytes: optional array of number` - `refusal: optional array of object { token, logprob, top_logprobs, bytes }` - `token: string` - `logprob: number` - `top_logprobs: array of object { token, logprob, bytes }` - `token: string` - `logprob: number` - `bytes: optional array of number` - `bytes: optional array of number` - `turns: optional array of object { role, content, output_ids, 2 more }` Token data for all LLM generations in multi-turn agent interaction. Includes token IDs and logprobs for each assistant turn, plus tool result content. Only present if return_token_ids was enabled. Used for RL training with loss masking. - `role: "assistant" or "tool"` Role of this turn: 'assistant' for LLM generations (trainable), 'tool' for tool results (non-trainable). - `"assistant"` - `"tool"` - `content: optional string` Text content. For tool turns, client tokenizes this with loss_mask=0. - `output_ids: optional array of number` Token IDs from SGLang native endpoint. Only present for assistant turns. - `output_token_logprobs: optional array of array of unknown` Logprobs from SGLang: [[logprob, token_id, top_logprob_or_null], ...]. Only present for assistant turns. - `tool_name: optional string` Name of the tool called. Only present for tool turns. ### Letta Streaming Request - `LettaStreamingRequest object { assistant_message_tool_kwarg, assistant_message_tool_name, background, 17 more }` - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `assistant_message_tool_name: optional string` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `background: optional boolean` Whether to process the request in the background (only used when streaming=true). - `client_skills: optional array of object { description, location, name }` Client-side skills available in the environment. These are rendered in the system prompt's available skills section alongside agent-scoped skills from MemFS. - `description: string` Description of what the skill does - `location: string` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: string` The name of the skill - `client_tools: optional array of object { name, description, parameters }` Client-side tools that the agent can call. When the agent calls a client-side tool, execution pauses and returns control to the client to execute the tool and provide the result via a ToolReturn. - `name: string` The name of the tool function - `description: optional string` Description of what the tool does - `parameters: optional map[unknown]` JSON Schema for the function parameters - `enable_thinking: optional string` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: optional boolean` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_pings: optional boolean` Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `input: optional string or array of TextContent or ImageContent or ToolCallContent or 5 more` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `string` - `array of TextContent or ImageContent or ToolCallContent or 5 more` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `SummarizedReasoning object { id, summary, encrypted_content, type }` The style of reasoning content returned by the OpenAI Responses API - `id: string` The unique identifier for this reasoning step. - `summary: array of object { index, text }` Summaries of the reasoning content. - `index: number` The index of the summary part. - `text: string` The text of the summary part. - `encrypted_content: optional string` The encrypted reasoning content. - `type: optional "summarized_reasoning"` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: optional number` Maximum number of steps the agent should take to process the request. - `messages: optional array of MessageCreate or ApprovalCreate or object { tool_returns, group_id, otid, type }` The messages to be sent to the agent. - `MessageCreate object { content, role, batch_item_id, 5 more }` Request to create a message - `content: array of LettaMessageContentUnion or string` The content of the message. - `array of LettaMessageContentUnion` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `ToolCallContent object { id, input, name, 2 more }` - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `string` - `role: "user" or "system" or "assistant"` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: optional string` The id of the LLMBatchItem that this message is associated with - `group_id: optional string` The multi-agent group that the message was sent in - `name: optional string` The name of the participant. - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `sender_id: optional string` The id of the sender of the message, can be an identity id or agent id - `type: optional "message"` The message type to be created. - `"message"` - `ApprovalCreate object { approval_request_id, approvals, approve, 4 more }` Input to approve or deny a tool call request - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `approve: optional boolean` Whether the tool has been approved - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturnCreate object { tool_returns, group_id, otid, type }` Submit tool return(s) from client-side tool execution. This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case. - `tool_returns: array of ToolReturn` List of tool returns from client-side execution - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `group_id: optional string` The multi-agent group that the message was sent in - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `type: optional "tool_return"` The message type to be created. - `"tool_return"` - `override_model: optional string` Model handle to use for this request instead of the agent's default model. This allows sending a message to a different model without changing the agent's configuration. - `override_system: optional string` Optional per-request system prompt override. When set, this is passed directly to the underlying LLM request and bypasses the persisted/compiled system message for that request. - `return_logprobs: optional boolean` If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang). - `return_token_ids: optional boolean` If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns 'turns' field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking. - `stream_tokens: optional boolean` Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). - `streaming: optional boolean` If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. ### Letta Streaming Response - `LettaStreamingResponse = SystemMessage or UserMessage or ReasoningMessage or 10 more` Streaming response type for Server-Sent Events (SSE) endpoints. Each event in the stream will be one of these types. - `SystemMessage object { id, content, date, 8 more }` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `UserMessage object { id, content, date, 8 more }` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ReasoningMessage object { id, date, reasoning, 10 more }` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` - `HiddenReasoningMessage object { id, date, state, 9 more }` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ToolCallMessage object { id, date, tool_call, 9 more }` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ToolReturnMessage object { id, date, status, 13 more }` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err: optional boolean` - `message_type: optional "tool_return_message"` The type of the message. - `"tool_return_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `stderr: optional array of string` - `stdout: optional array of string` - `step_id: optional string` - `tool_returns: optional array of ToolReturn` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `AssistantMessage object { id, content, date, 8 more }` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ApprovalRequestMessage object { id, date, tool_call, 9 more }` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `ToolCallDelta object { arguments, name, tool_call_id }` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ApprovalResponseMessage object { id, date, approval_request_id, 11 more }` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `Ping object { id, date, is_err, 7 more }` A ping message used as a keepalive to prevent SSE streams from timing out during long running requests. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format - `id: string` - `date: string` - `is_err: optional boolean` - `message_type: optional "ping"` The type of the message. Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests. - `"ping"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ErrorMessage object { error_type, message, message_type, 3 more }` Error messages are used to notify the client of an error that occurred during the agent's execution. - `error_type: string` The type of error. - `message: string` The error message. - `message_type: "error_message"` The type of the message. - `"error_message"` - `run_id: string` The ID of the run. - `detail: optional string` An optional error detail. - `seq_id: optional number` The sequence ID for cursor-based pagination. - `StopReason object { stop_reason, message_type }` The stop reason from Letta indicating why agent loop stopped execution. - `stop_reason: StopReasonType` The reason why execution stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `message_type: optional "stop_reason"` The type of the message. - `"stop_reason"` - `UsageStatistics object { cache_write_tokens, cached_input_tokens, completion_tokens, 7 more }` Usage statistics for the agent interaction. Attributes: completion_tokens (int): The number of tokens generated by the agent. prompt_tokens (int): The number of tokens in the prompt. total_tokens (int): The total number of tokens processed by the agent. step_count (int): The number of steps taken by the agent. cached_input_tokens (Optional[int]): The number of input tokens served from cache. None if not reported. cache_write_tokens (Optional[int]): The number of input tokens written to cache. None if not reported. reasoning_tokens (Optional[int]): The number of reasoning/thinking tokens generated. None if not reported. - `cache_write_tokens: optional number` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: optional number` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: optional number` The number of tokens generated by the agent. - `context_tokens: optional number` Estimate of tokens currently in the context window. - `message_type: optional "usage_statistics"` - `"usage_statistics"` - `prompt_tokens: optional number` The number of tokens in the prompt. - `reasoning_tokens: optional number` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: optional array of string` The background task run IDs associated with the agent interaction - `step_count: optional number` The number of steps taken by the agent. - `total_tokens: optional number` The total number of tokens processed by the agent. ### Letta User Message Content Union - `LettaUserMessageContentUnion = TextContent or ImageContent` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` ### Message - `Message = SystemMessage or UserMessage or ReasoningMessage or 8 more` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `SystemMessage object { id, content, date, 8 more }` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `UserMessage object { id, content, date, 8 more }` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ReasoningMessage object { id, date, reasoning, 10 more }` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` - `HiddenReasoningMessage object { id, date, state, 9 more }` Representation of an agent's internal reasoning where reasoning content has been hidden from the response. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent - `id: string` - `date: string` - `state: "redacted" or "omitted"` - `"redacted"` - `"omitted"` - `hidden_reasoning: optional string` - `is_err: optional boolean` - `message_type: optional "hidden_reasoning_message"` The type of the message. - `"hidden_reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ToolCallMessage object { id, date, tool_call, 9 more }` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ToolReturnMessage object { id, date, status, 13 more }` A message representing the return value of a tool call (generated by Letta executing the requested tool). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support - `id: string` - `date: string` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: string` - `is_err: optional boolean` - `message_type: optional "tool_return_message"` The type of the message. - `"tool_return_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `stderr: optional array of string` - `stdout: optional array of string` - `step_id: optional string` - `tool_returns: optional array of ToolReturn` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `ImageContent object { source, type }` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` - `AssistantMessage object { id, content, date, 8 more }` A message sent by the LLM in response to user input. Used in the LLM context. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts) - `id: string` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the agent (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "assistant_message"` The type of the message. - `"assistant_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `ApprovalRequestMessage object { id, date, tool_call, 9 more }` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `ToolCallDelta object { arguments, name, tool_call_id }` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `ApprovalResponseMessage object { id, date, approval_request_id, 11 more }` A message representing a response form the user indicating whether a tool has been approved to run. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status - `id: string` - `date: string` - `approval_request_id: optional string` The message ID of the approval request - `approvals: optional array of ApprovalReturn or ToolReturn` The list of approval responses - `ApprovalReturn object { approve, tool_call_id, reason, type }` - `approve: boolean` Whether the tool has been approved - `tool_call_id: string` The ID of the tool call that corresponds to this approval - `reason: optional string` An optional explanation for the provided approval status - `type: optional "approval"` The message type to be created. - `"approval"` - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `approve: optional boolean` Whether the tool has been approved - `is_err: optional boolean` - `message_type: optional "approval_response_message"` The type of the message. - `"approval_response_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `reason: optional string` An optional explanation for the provided approval status - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `SummaryMessage object { id, date, summary, 9 more }` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: optional number` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: optional number` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: optional boolean` - `message_type: optional "summary_message"` - `"summary_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `EventMessage object { id, date, event_data, 9 more }` A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window. - `id: string` - `date: string` - `event_data: map[unknown]` - `event_type: "compaction"` - `"compaction"` - `is_err: optional boolean` - `message_type: optional "event_message"` - `"event_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Message Role - `MessageRole = "assistant" or "user" or "tool" or 4 more` - `"assistant"` - `"user"` - `"tool"` - `"function"` - `"system"` - `"approval"` - `"summary"` ### Message Type - `MessageType = "system_message" or "user_message" or "assistant_message" or 8 more` - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` ### Omitted Reasoning Content - `OmittedReasoningContent object { signature, type }` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "omitted_reasoning"` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` ### Reasoning Content - `ReasoningContent object { is_native, reasoning, signature, type }` Sent via the Anthropic Messages API - `is_native: boolean` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: string` The intermediate reasoning or thought process content. - `signature: optional string` A unique identifier for this reasoning step. - `type: optional "reasoning"` Indicates this is a reasoning/intermediate step. - `"reasoning"` ### Reasoning Message - `ReasoningMessage object { id, date, reasoning, 10 more }` Representation of an agent's internal reasoning. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step - `id: string` - `date: string` - `reasoning: string` - `is_err: optional boolean` - `message_type: optional "reasoning_message"` The type of the message. - `"reasoning_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `signature: optional string` - `source: optional "reasoner_model" or "non_reasoner_model"` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: optional string` ### Redacted Reasoning Content - `RedactedReasoningContent object { data, type }` Sent via the Anthropic Messages API - `data: string` The redacted or filtered intermediate reasoning content. - `type: optional "redacted_reasoning"` Indicates this is a redacted thinking step. - `"redacted_reasoning"` ### Run - `Run object { id, agent_id, background, 14 more }` Representation of a run - a conversation or processing session for an agent. Runs track when agents process messages and maintain the relationship between agents, steps, and messages. - `id: string` The human-friendly ID of the Run - `agent_id: string` The unique identifier of the agent associated with the run. - `background: optional boolean` Whether the run was created in background mode. - `base_template_id: optional string` The base template ID that the run belongs to. - `callback_error: optional string` Optional error message from attempting to POST the callback endpoint. - `callback_sent_at: optional string` Timestamp when the callback was last attempted. - `callback_status_code: optional number` HTTP status code returned by the callback endpoint. - `callback_url: optional string` If set, POST to this URL when the run completes. - `completed_at: optional string` The timestamp when the run was completed. - `conversation_id: optional string` The unique identifier of the conversation associated with the run. - `created_at: optional string` The timestamp when the run was created. - `metadata: optional map[unknown]` Additional metadata for the run. - `request_config: optional object { assistant_message_tool_kwarg, assistant_message_tool_name, include_return_message_types, use_assistant_message }` The request configuration for the run. - `assistant_message_tool_kwarg: optional string` The name of the message argument in the designated message tool. - `assistant_message_tool_name: optional string` The name of the designated message tool. - `include_return_message_types: optional array of MessageType` Only return specified message types in the response. If `None` (default) returns all messages. - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `"summary_message"` - `"event_message"` - `use_assistant_message: optional boolean` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. - `status: optional "created" or "running" or "completed" or 2 more` The current status of the run. - `"created"` - `"running"` - `"completed"` - `"failed"` - `"cancelled"` - `stop_reason: optional StopReasonType` The reason why the run was stopped. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `total_duration_ns: optional number` Total run duration in nanoseconds - `ttft_ns: optional number` Time to first token for a run in nanoseconds ### Summary Message - `SummaryMessage object { id, date, summary, 9 more }` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: string` - `date: string` - `summary: string` - `compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }` Statistics about a memory compaction operation. - `context_window: number` The model's context window size - `messages_count_after: number` Number of messages after compaction - `messages_count_before: number` Number of messages before compaction - `trigger: string` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: optional number` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: optional number` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: optional boolean` - `message_type: optional "summary_message"` - `"summary_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### System Message - `SystemMessage object { id, content, date, 8 more }` A message generated by the system. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system - `id: string` - `content: string` The message content sent by the system - `date: string` - `is_err: optional boolean` - `message_type: optional "system_message"` The type of the message. - `"system_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Text Content - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` ### Tool Call - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` ### Tool Call Content - `ToolCallContent object { id, input, name, 2 more }` - `id: string` A unique identifier for this specific tool call instance. - `input: map[unknown]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: string` The name of the tool being called. - `signature: optional string` Stores a unique identifier for any reasoning associated with this tool call. - `type: optional "tool_call"` Indicates this content represents a tool call event. - `"tool_call"` ### Tool Call Delta - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` ### Tool Call Message - `ToolCallMessage object { id, date, tool_call, 9 more }` A message representing a request to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "tool_call_message"` The type of the message. - `"tool_call_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` ### Tool Return - `ToolReturn object { status, tool_call_id, tool_return, 3 more }` - `status: "success" or "error"` - `"success"` - `"error"` - `tool_call_id: string` - `tool_return: array of TextContent or ImageContent or string` The tool return value - either a string or list of content parts (text/image) - `array of TextContent or ImageContent` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `stderr: optional array of string` - `stdout: optional array of string` - `type: optional "tool"` The message type to be created. - `"tool"` ### Tool Return Content - `ToolReturnContent object { content, is_error, tool_call_id, type }` - `content: string` The content returned by the tool execution. - `is_error: boolean` Indicates whether the tool execution resulted in an error. - `tool_call_id: string` References the ID of the ToolCallContent that initiated this tool call. - `type: optional "tool_return"` Indicates this content represents a tool return event. - `"tool_return"` ### Update Assistant Message - `UpdateAssistantMessage object { content, message_type }` - `content: array of LettaAssistantMessageContentUnion or string` The message content sent by the assistant (can be a string or an array of content parts) - `array of LettaAssistantMessageContentUnion` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `string` - `message_type: optional "assistant_message"` - `"assistant_message"` ### Update Reasoning Message - `UpdateReasoningMessage object { reasoning, message_type }` - `reasoning: string` - `message_type: optional "reasoning_message"` - `"reasoning_message"` ### Update System Message - `UpdateSystemMessage object { content, message_type }` - `content: string` The message content sent by the system (can be a string or an array of multi-modal content parts) - `message_type: optional "system_message"` - `"system_message"` ### Update User Message - `UpdateUserMessage object { content, message_type }` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `message_type: optional "user_message"` - `"user_message"` ### User Message - `UserMessage object { id, content, date, 8 more }` A message sent by the user. Never streamed back on a response, only used for cursor pagination. Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts) - `id: string` - `content: array of LettaUserMessageContentUnion or string` The message content sent by the user (can be a string or an array of multi-modal content parts) - `array of LettaUserMessageContentUnion` - `TextContent object { text, signature, type }` - `text: string` The text content of the message. - `signature: optional string` Stores a unique identifier for any reasoning associated with this text content. - `type: optional "text"` The type of the message. - `"text"` - `ImageContent object { source, type }` - `source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }` The source of the image. - `URL object { url, type }` - `url: string` The URL of the image. - `type: optional "url"` The source type for the image. - `"url"` - `Base64 object { data, media_type, detail, type }` - `data: string` The base64 encoded image data. - `media_type: string` The media type for the image. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: optional "base64"` The source type for the image. - `"base64"` - `Letta object { file_id, data, detail, 2 more }` - `file_id: string` The unique identifier of the image file persisted in storage. - `data: optional string` The base64 encoded image data. - `detail: optional string` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: optional string` The media type for the image. - `type: optional "letta"` The source type for the image. - `"letta"` - `type: optional "image"` The type of the message. - `"image"` - `string` - `date: string` - `is_err: optional boolean` - `message_type: optional "user_message"` The type of the message. - `"user_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` ### Message Cancel Response - `MessageCancelResponse = map[unknown]` # Schedule ## Schedule Agent Message **post** `/v1/agents/{agent_id}/schedule` Schedule a message to be sent by the agent at a specified time or on a recurring basis. ### Path Parameters - `agent_id: string` ### Body Parameters - `messages: array of object { content, role, name, 3 more }` - `content: array of object { text, signature, type } or object { source, type } or string` - `array of object { text, signature, type } or object { source, type }` - `object { text, signature, type }` - `text: string` - `signature: optional string` - `type: optional "text"` - `"text"` - `object { source, type }` - `source: object { data, media_type, detail, type }` - `data: string` - `media_type: string` - `detail: optional string` - `type: optional "base64"` - `"base64"` - `type: "image"` - `"image"` - `string` - `role: "user" or "assistant" or "system"` - `"user"` - `"assistant"` - `"system"` - `name: optional string` - `otid: optional string` - `sender_id: optional string` - `type: optional "message"` - `"message"` - `schedule: object { scheduled_at, type } or object { cron_expression, type }` - `object { scheduled_at, type }` - `scheduled_at: number` - `type: optional "one-time"` - `"one-time"` - `object { cron_expression, type }` - `cron_expression: string` - `type: "recurring"` - `"recurring"` - `callback_url: optional string` - `include_return_message_types: optional array of "system_message" or "user_message" or "assistant_message" or 6 more` - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `max_steps: optional number` ### Returns - `id: string` - `next_scheduled_at: optional string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/schedule \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{ "messages": [ { "content": [ { "text": "text" } ], "role": "user" } ], "schedule": { "scheduled_at": 0 } }' ``` #### Response ```json { "id": "id", "next_scheduled_at": "next_scheduled_at" } ``` ## List Scheduled Agent Messages **get** `/v1/agents/{agent_id}/schedule` List all scheduled messages for a specific agent. ### Path Parameters - `agent_id: string` ### Query Parameters - `after: optional string` - `limit: optional string` ### Returns - `has_next_page: boolean` - `scheduled_messages: array of object { id, agent_id, message, 2 more }` - `id: string` - `agent_id: string` - `message: object { messages, callback_url, include_return_message_types, max_steps }` - `messages: array of object { content, role, name, 3 more }` - `content: array of object { text, signature, type } or object { source, type } or string` - `array of object { text, signature, type } or object { source, type }` - `object { text, signature, type }` - `text: string` - `signature: optional string` - `type: optional "text"` - `"text"` - `object { source, type }` - `source: object { data, media_type, detail, type }` - `data: string` - `media_type: string` - `detail: optional string` - `type: optional "base64"` - `"base64"` - `type: "image"` - `"image"` - `string` - `role: "user" or "assistant" or "system"` - `"user"` - `"assistant"` - `"system"` - `name: optional string` - `otid: optional string` - `sender_id: optional string` - `type: optional "message"` - `"message"` - `callback_url: optional string` - `include_return_message_types: optional array of "system_message" or "user_message" or "assistant_message" or 6 more` - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `max_steps: optional number` - `next_scheduled_time: string` - `schedule: object { scheduled_at, type } or object { cron_expression, type }` - `object { scheduled_at, type }` - `scheduled_at: number` - `type: optional "one-time"` - `"one-time"` - `object { cron_expression, type }` - `cron_expression: string` - `type: "recurring"` - `"recurring"` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/schedule \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "has_next_page": true, "scheduled_messages": [ { "id": "id", "agent_id": "agent_id", "message": { "messages": [ { "content": [ { "text": "text", "signature": "signature", "type": "text" } ], "role": "user", "name": "name", "otid": "otid", "sender_id": "sender_id", "type": "message" } ], "callback_url": "https://example.com", "include_return_message_types": [ "system_message" ], "max_steps": 0 }, "next_scheduled_time": "next_scheduled_time", "schedule": { "scheduled_at": 0, "type": "one-time" } } ] } ``` ## Retrieve Scheduled Agent Message **get** `/v1/agents/{agent_id}/schedule/{scheduled_message_id}` Retrieve a scheduled message by its ID for a specific agent. ### Path Parameters - `agent_id: string` - `scheduled_message_id: string` ### Returns - `id: string` - `agent_id: string` - `message: object { messages, callback_url, include_return_message_types, max_steps }` - `messages: array of object { content, role, name, 3 more }` - `content: array of object { text, signature, type } or object { source, type } or string` - `array of object { text, signature, type } or object { source, type }` - `object { text, signature, type }` - `text: string` - `signature: optional string` - `type: optional "text"` - `"text"` - `object { source, type }` - `source: object { data, media_type, detail, type }` - `data: string` - `media_type: string` - `detail: optional string` - `type: optional "base64"` - `"base64"` - `type: "image"` - `"image"` - `string` - `role: "user" or "assistant" or "system"` - `"user"` - `"assistant"` - `"system"` - `name: optional string` - `otid: optional string` - `sender_id: optional string` - `type: optional "message"` - `"message"` - `callback_url: optional string` - `include_return_message_types: optional array of "system_message" or "user_message" or "assistant_message" or 6 more` - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `max_steps: optional number` - `next_scheduled_time: string` - `schedule: object { scheduled_at, type } or object { cron_expression, type }` - `object { scheduled_at, type }` - `scheduled_at: number` - `type: optional "one-time"` - `"one-time"` - `object { cron_expression, type }` - `cron_expression: string` - `type: "recurring"` - `"recurring"` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/schedule/$SCHEDULED_MESSAGE_ID \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "message": { "messages": [ { "content": [ { "text": "text", "signature": "signature", "type": "text" } ], "role": "user", "name": "name", "otid": "otid", "sender_id": "sender_id", "type": "message" } ], "callback_url": "https://example.com", "include_return_message_types": [ "system_message" ], "max_steps": 0 }, "next_scheduled_time": "next_scheduled_time", "schedule": { "scheduled_at": 0, "type": "one-time" } } ``` ## Delete Scheduled Agent Message **delete** `/v1/agents/{agent_id}/schedule/{scheduled_message_id}` Delete a scheduled message by its ID for a specific agent. ### Path Parameters - `agent_id: string` - `scheduled_message_id: string` ### Returns - `success: true` - `true` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/schedule/$SCHEDULED_MESSAGE_ID \ -X DELETE \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "success": true } ``` ## Domain Types ### Schedule Create Response - `ScheduleCreateResponse object { id, next_scheduled_at }` - `id: string` - `next_scheduled_at: optional string` ### Schedule List Response - `ScheduleListResponse object { has_next_page, scheduled_messages }` - `has_next_page: boolean` - `scheduled_messages: array of object { id, agent_id, message, 2 more }` - `id: string` - `agent_id: string` - `message: object { messages, callback_url, include_return_message_types, max_steps }` - `messages: array of object { content, role, name, 3 more }` - `content: array of object { text, signature, type } or object { source, type } or string` - `array of object { text, signature, type } or object { source, type }` - `object { text, signature, type }` - `text: string` - `signature: optional string` - `type: optional "text"` - `"text"` - `object { source, type }` - `source: object { data, media_type, detail, type }` - `data: string` - `media_type: string` - `detail: optional string` - `type: optional "base64"` - `"base64"` - `type: "image"` - `"image"` - `string` - `role: "user" or "assistant" or "system"` - `"user"` - `"assistant"` - `"system"` - `name: optional string` - `otid: optional string` - `sender_id: optional string` - `type: optional "message"` - `"message"` - `callback_url: optional string` - `include_return_message_types: optional array of "system_message" or "user_message" or "assistant_message" or 6 more` - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `max_steps: optional number` - `next_scheduled_time: string` - `schedule: object { scheduled_at, type } or object { cron_expression, type }` - `object { scheduled_at, type }` - `scheduled_at: number` - `type: optional "one-time"` - `"one-time"` - `object { cron_expression, type }` - `cron_expression: string` - `type: "recurring"` - `"recurring"` ### Schedule Retrieve Response - `ScheduleRetrieveResponse object { id, agent_id, message, 2 more }` - `id: string` - `agent_id: string` - `message: object { messages, callback_url, include_return_message_types, max_steps }` - `messages: array of object { content, role, name, 3 more }` - `content: array of object { text, signature, type } or object { source, type } or string` - `array of object { text, signature, type } or object { source, type }` - `object { text, signature, type }` - `text: string` - `signature: optional string` - `type: optional "text"` - `"text"` - `object { source, type }` - `source: object { data, media_type, detail, type }` - `data: string` - `media_type: string` - `detail: optional string` - `type: optional "base64"` - `"base64"` - `type: "image"` - `"image"` - `string` - `role: "user" or "assistant" or "system"` - `"user"` - `"assistant"` - `"system"` - `name: optional string` - `otid: optional string` - `sender_id: optional string` - `type: optional "message"` - `"message"` - `callback_url: optional string` - `include_return_message_types: optional array of "system_message" or "user_message" or "assistant_message" or 6 more` - `"system_message"` - `"user_message"` - `"assistant_message"` - `"reasoning_message"` - `"hidden_reasoning_message"` - `"tool_call_message"` - `"tool_return_message"` - `"approval_request_message"` - `"approval_response_message"` - `max_steps: optional number` - `next_scheduled_time: string` - `schedule: object { scheduled_at, type } or object { cron_expression, type }` - `object { scheduled_at, type }` - `scheduled_at: number` - `type: optional "one-time"` - `"one-time"` - `object { cron_expression, type }` - `cron_expression: string` - `type: "recurring"` - `"recurring"` ### Schedule Delete Response - `ScheduleDeleteResponse object { success }` - `success: true` - `true` # Blocks ## Retrieve Block For Agent **get** `/v1/agents/{agent_id}/core-memory/blocks/{block_label}` Retrieve a core memory block from an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `block_label: string` ### Returns - `BlockResponse object { id, value, base_template_id, 16 more }` - `id: string` The id of the block. - `value: string` Value of the block. - `base_template_id: optional string` (Deprecated) The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` (Deprecated) The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` (Deprecated) The id of the entity within the template. - `hidden: optional boolean` (Deprecated) If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` (Deprecated) Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` (Deprecated) Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` (Deprecated) The id of the template. - `template_name: optional string` (Deprecated) The name of the block template (if it is a template). ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/core-memory/blocks/$BLOCK_LABEL \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "id": "id", "value": "value", "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ``` ## Update Block For Agent **patch** `/v1/agents/{agent_id}/core-memory/blocks/{block_label}` Updates a core memory block of an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `block_label: string` ### Body Parameters - `base_template_id: optional string` The base template id of the block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags to associate with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `value: optional string` Value of the block. ### Returns - `BlockResponse object { id, value, base_template_id, 16 more }` - `id: string` The id of the block. - `value: string` Value of the block. - `base_template_id: optional string` (Deprecated) The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` (Deprecated) The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` (Deprecated) The id of the entity within the template. - `hidden: optional boolean` (Deprecated) If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` (Deprecated) Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` (Deprecated) Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` (Deprecated) The id of the template. - `template_name: optional string` (Deprecated) The name of the block template (if it is a template). ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/core-memory/blocks/$BLOCK_LABEL \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "id", "value": "value", "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ``` ## List Blocks For Agent **get** `/v1/agents/{agent_id}/core-memory/blocks` Retrieve the core memory blocks of a specific agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `after: optional string` Cursor for pagination (block ID). Returns results relative to this ID in the specified sort order. Expected format: 'block-' - `before: optional string` Cursor for pagination (block ID). Returns results relative to this ID in the specified sort order. Expected format: 'block-' - `limit: optional number` Maximum number of blocks to return - `order: optional "asc" or "desc"` Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` ### Returns - `id: string` The id of the block. - `value: string` Value of the block. - `base_template_id: optional string` (Deprecated) The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` (Deprecated) The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` (Deprecated) The id of the entity within the template. - `hidden: optional boolean` (Deprecated) If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` (Deprecated) Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` (Deprecated) Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` (Deprecated) The id of the template. - `template_name: optional string` (Deprecated) The name of the block template (if it is a template). ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/core-memory/blocks \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "id": "id", "value": "value", "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ] ``` ## Attach Block To Agent **patch** `/v1/agents/{agent_id}/core-memory/blocks/attach/{block_id}` Attach a core memory block to an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `block_id: string` The ID of the block in the format 'block-' ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/core-memory/blocks/attach/$BLOCK_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Detach Block From Agent **patch** `/v1/agents/{agent_id}/core-memory/blocks/detach/{block_id}` Detach a core memory block from an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `block_id: string` The ID of the block in the format 'block-' ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/core-memory/blocks/detach/$BLOCK_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Domain Types ### Block - `Block object { value, id, base_template_id, 16 more }` A Block represents a reserved section of the LLM's context window. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. ### Block Update - `BlockUpdate object { base_template_id, deployment_id, description, 13 more }` Update a block - `base_template_id: optional string` The base template id of the block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags to associate with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `value: optional string` Value of the block. # Tools ## List Tools For Agent **get** `/v1/agents/{agent_id}/tools` Get tools from an existing agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `after: optional string` Cursor for pagination (tool ID). Returns results relative to this ID in the specified sort order. Expected format: 'tool-' - `before: optional string` Cursor for pagination (tool ID). Returns results relative to this ID in the specified sort order. Expected format: 'tool-' - `limit: optional number` Maximum number of tools to return - `order: optional "asc" or "desc"` Sort order for tools by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` ### Returns - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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"` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/tools \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ] ``` ## Attach Tool To Agent **patch** `/v1/agents/{agent_id}/tools/attach/{tool_id}` Attach a tool to an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `tool_id: string` The ID of the tool in the format 'tool-' ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/tools/attach/$TOOL_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Detach Tool From Agent **patch** `/v1/agents/{agent_id}/tools/detach/{tool_id}` Detach a tool from an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `tool_id: string` The ID of the tool in the format 'tool-' ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/tools/detach/$TOOL_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Update Approval For Tool **patch** `/v1/agents/{agent_id}/tools/approval/{tool_name}` Modify the approval requirement for a tool attached to an agent. Accepts requires_approval via request body (preferred) or query parameter (deprecated). ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `tool_name: string` ### Query Parameters - `requires_approval: optional boolean` Whether the tool requires approval before execution ### Body Parameters - `requires_approval: boolean` Whether the tool requires approval before execution ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/tools/approval/$TOOL_NAME \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{ "requires_approval": true }' ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Run Tool For Agent **post** `/v1/agents/{agent_id}/tools/{tool_name}/run` Trigger a tool by name on a specific agent, providing the necessary arguments. This endpoint executes a tool that is attached to the agent, using the agent's state and environment variables for execution context. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `tool_name: string` ### Body Parameters - `args: optional map[unknown]` Arguments to pass to the tool ### Returns - `ToolExecutionResult object { status, agent_state, func_return, 3 more }` - `status: "success" or "error"` The status of the tool execution and return object - `"success"` - `"error"` - `agent_state: optional 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. - `id: string` The id of the agent. Assigned by the database. - `agent_type: AgentType` The type of agent. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. - `func_return: optional unknown` The function return object - `sandbox_config_fingerprint: optional string` The fingerprint of the config for the sandbox - `stderr: optional array of string` Captured stderr from the function invocation - `stdout: optional array of string` Captured stdout (prints, logs) from function invocation ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/tools/$TOOL_NAME/run \ -X POST \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "status": "success", "agent_state": { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" }, "func_return": {}, "sandbox_config_fingerprint": "sandbox_config_fingerprint", "stderr": [ "string" ], "stdout": [ "string" ] } ``` ## Domain Types ### Tool Execute Request - `ToolExecuteRequest object { args }` Request to execute a tool. - `args: optional map[unknown]` Arguments to pass to the tool ### Tool Execution Result - `ToolExecutionResult object { status, agent_state, func_return, 3 more }` - `status: "success" or "error"` The status of the tool execution and return object - `"success"` - `"error"` - `agent_state: optional 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. - `id: string` The id of the agent. Assigned by the database. - `agent_type: AgentType` The type of agent. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. - `func_return: optional unknown` The function return object - `sandbox_config_fingerprint: optional string` The fingerprint of the config for the sandbox - `stderr: optional array of string` Captured stderr from the function invocation - `stdout: optional array of string` Captured stdout (prints, logs) from function invocation # Folders ## Attach Folder To Agent **patch** `/v1/agents/{agent_id}/folders/attach/{folder_id}` Attach a folder to an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `folder_id: string` The ID of the source in the format 'source-' ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/folders/attach/$FOLDER_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## Detach Folder From Agent **patch** `/v1/agents/{agent_id}/folders/detach/{folder_id}` Detach a folder from an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `folder_id: string` The ID of the source in the format 'source-' ### Returns - `AgentState object { id, agent_type, blocks, 42 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. - `"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 of Block` The memory blocks used by the agent. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `llm_config: LlmConfig` 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" or "anthropic" or "google_ai" or 27 more` The endpoint type for the model. - `"openai"` - `"anthropic"` - `"google_ai"` - `"google_vertex"` - `"azure"` - `"groq"` - `"ollama"` - `"webui"` - `"webui-legacy"` - `"lmstudio"` - `"lmstudio-legacy"` - `"lmstudio-chatcompletions"` - `"llamacpp"` - `"koboldcpp"` - `"vllm"` - `"hugging-face"` - `"minimax"` - `"moonshot"` - `"moonshot_coding"` - `"mistral"` - `"together"` - `"bedrock"` - `"deepseek"` - `"xai"` - `"zai"` - `"zai_coding"` - `"baseten"` - `"fireworks"` - `"openrouter"` - `"chatgpt_oauth"` - `compatibility_type: optional "gguf" or "mlx"` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: optional string` A human-friendly display name for the model. - `effort: optional "low" or "medium" or "high" or 2 more` The effort level for Anthropic models that support it (Opus 4.5+). Controls token spending and thinking behavior. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `enable_reasoner: optional boolean` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: optional number` 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: optional string` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: optional 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: optional number` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: optional string` The endpoint for the model. - `model_wrapper: optional string` The wrapper for the model. - `parallel_tool_calls: optional boolean` Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False. - `provider_category: optional ProviderCategory` The provider category for the model. - `"base"` - `"byok"` - `provider_name: optional string` The provider name for the model. - `put_inner_thoughts_in_kwargs: optional boolean` 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: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `TextResponseFormat object { type }` Response format for plain text responses. - `type: optional "text"` The type of the response format. - `"text"` - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `json_schema: map[unknown]` The JSON schema of the response. - `type: optional "json_schema"` The type of the response format. - `"json_schema"` - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `type: optional "json_object"` The type of the response format. - `"json_object"` - `return_logprobs: optional boolean` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: optional boolean` Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: optional number` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: optional string` The cost tier for the model (cloud only). - `tool_call_parser: optional string` SGLang tool call parser name (e.g. 'glm47', 'qwen25', 'hermes'). Used by the SGLang native adapter to parse tool calls from raw model output. - `top_logprobs: optional number` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: object { blocks, agent_type, file_blocks, 2 more }` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: array of Block` Memory blocks contained in the agent's in-context memory - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `agent_type: optional AgentType or string` Agent type controlling prompt rendering. - `AgentType = "memgpt_agent" or "memgpt_v2_agent" or "letta_v1_agent" or 6 more` Enum to represent the type of agent. - `string` - `file_blocks: optional array of object { file_id, is_open, source_id, 20 more }` 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` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: string` Value of the block. - `id: optional string` The human-friendly ID of the Block - `base_template_id: optional string` The base template id of the block. - `created_by_id: optional string` The id of the user that made this Block. - `deployment_id: optional string` The id of the deployment. - `description: optional string` Description of the block. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the block will be hidden. - `is_template: optional boolean` Whether the block is a template (e.g. saved human/persona options). - `label: optional string` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: optional string` 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. - `last_updated_by_id: optional string` The id of the user that last updated this Block. - `limit: optional number` Character limit of the block. - `metadata: optional map[unknown]` Metadata of the block. - `preserve_on_migration: optional boolean` Preserve the block on template migration. - `project_id: optional string` The associated project id. - `read_only: optional boolean` Whether the agent has read-only access to the block. - `tags: optional array of string` The tags associated with the block. - `template_id: optional string` The id of the template. - `template_name: optional string` Name of the block if it is a template. - `git_enabled: optional boolean` Whether this agent uses git-backed memory with structured labels. - `prompt_template: optional string` Deprecated. Ignored for performance. - `name: string` The name of the agent. - `sources: array of object { id, embedding_config, name, 8 more }` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` - `system: string` The system prompt used by the agent. - `tags: array of string` The tags associated with the agent. - `tools: array of Tool` The tools used by the agent. - `id: string` The human-friendly ID of the Tool - `args_json_schema: optional map[unknown]` The args JSON schema of the function. - `created_by_id: optional string` The id of the user that made this Tool. - `default_requires_approval: optional boolean` Default value for whether or not executing this tool requires approval. - `description: optional string` The description of the tool. - `enable_parallel_execution: optional boolean` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: optional map[unknown]` The JSON schema of the function. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata_: optional map[unknown]` A dictionary of additional metadata for the tool. - `name: optional string` The name of the function. - `npm_requirements: optional array of NpmRequirement` Optional list of npm packages required by this tool. - `name: string` Name of the npm package. - `version: optional string` Optional version of the package, following semantic versioning. - `pip_requirements: optional array of PipRequirement` Optional list of pip packages required by this tool. - `name: string` Name of the pip package. - `version: optional string` Optional version of the package, following semantic versioning. - `project_id: optional string` The project id of the tool. - `return_char_limit: optional number` The maximum number of characters in the response. - `source_code: optional string` The source code of the function. - `source_type: optional string` The type of the source code. - `tags: optional array of string` Metadata tags. - `tool_type: optional ToolType` The type of the tool. - `"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: optional string` The base template id of the agent. - `compaction_settings: optional object { clip_chars, mode, model, 4 more }` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: optional number` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: optional "all" or "sliding_window" or "self_compact_all" or "self_compact_sliding_window"` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: optional string` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` Optional model settings used to override defaults for the summarizer model. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openai"` The type of the provider. - `"openai"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "anthropic"` The type of the provider. - `"anthropic"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_ai"` The type of the provider. - `"google_ai"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "google_vertex"` The type of the provider. - `"google_vertex"` - `response_schema: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response schema for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking_config: optional object { include_thoughts, thinking_budget }` The thinking configuration for the model. - `include_thoughts: optional boolean` Whether to include thoughts in the model's response. - `thinking_budget: optional number` The thinking budget for the model. - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "azure"` The type of the provider. - `"azure"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "xai"` The type of the provider. - `"xai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "groq"` The type of the provider. - `"groq"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "deepseek"` The type of the provider. - `"deepseek"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "together"` The type of the provider. - `"together"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "bedrock"` The type of the provider. - `"bedrock"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `prompt: optional string` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: optional boolean` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: optional number` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `deployment_id: optional string` The id of the deployment. - `description: optional string` The description of the agent. - `embedding: optional string` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: optional EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `enable_sleeptime: optional boolean` If set to True, memory management will move to a background agent thread. - `entity_id: optional string` The id of the entity within the template. - `hidden: optional boolean` If set to True, the agent will be hidden. - `identities: optional array of object { id, agent_ids, block_ids, 5 more }` The identities associated with this agent. - `id: string` The human-friendly ID of the Identity - `agent_ids: array of string` The IDs of the agents associated with the identity. - `block_ids: array of string` The IDs of the blocks associated with the identity. - `identifier_key: string` External, user-generated identifier key of the identity. - `identity_type: "org" or "user" or "other"` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: string` The name of the identity. - `project_id: optional string` The project id of the identity, if applicable. - `properties: optional array of object { key, type, value }` List of properties associated with the identity - `key: string` The key of the property - `type: "string" or "number" or "boolean" or "json"` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: string or number or boolean or map[unknown]` The value of the property - `string` - `number` - `boolean` - `map[unknown]` - `identity_ids: optional array of string` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: optional string` The timestamp when the agent last completed a run. - `last_run_duration_ms: optional number` The duration in milliseconds of the agent's last run. - `last_stop_reason: optional StopReasonType` The stop reason from the agent's last run. - `"end_turn"` - `"error"` - `"llm_api_error"` - `"invalid_llm_response"` - `"invalid_tool_call"` - `"max_steps"` - `"max_tokens_exceeded"` - `"no_tool_call"` - `"tool_rule"` - `"cancelled"` - `"insufficient_credits"` - `"requires_approval"` - `"context_window_overflow_in_system_prompt"` - `last_updated_by_id: optional string` The id of the user that made this object. - `managed_group: optional object { id, agent_ids, description, 15 more }` The multi-agent group that this agent manages - `id: string` The id of the group. Assigned by the database. - `agent_ids: array of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `max_files_open: optional number` 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: optional 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: optional array of string` The ids of the messages in the agent's in-context memory. - `metadata: optional map[unknown]` The metadata of the agent. - `model: optional string` The model handle used by the agent (format: provider/model-name). - `model_settings: optional OpenAIModelSettings or object { max_output_tokens, parallel_tool_calls, provider_type, 5 more } or AnthropicModelSettings or 14 more` The model settings used by the agent. - `OpenAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 4 more }` - `Sglang object { max_output_tokens, parallel_tool_calls, provider_type, 5 more }` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "sglang"` The type of the provider. - `"sglang"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "minimal" or "low" or 3 more` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `tool_call_parser: optional string` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `AnthropicModelSettings object { effort, max_output_tokens, parallel_tool_calls, 6 more }` - `GoogleAIModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `GoogleVertexModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` - `AzureModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Azure OpenAI model configuration (OpenAI-compatible). - `XaiModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` xAI model configuration (OpenAI-compatible). - `Moonshot object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot"` The type of the provider. - `"moonshot"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `Zai object { max_output_tokens, parallel_tool_calls, provider_type, 3 more }` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "zai"` The type of the provider. - `"zai"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `thinking: optional object { clear_thinking, type }` The thinking configuration for GLM-4.5+ models. - `clear_thinking: optional boolean` If False, preserved thinking is used (recommended for agents). - `type: optional "enabled" or "disabled"` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `MoonshotCoding object { effort, max_output_tokens, parallel_tool_calls, 6 more }` Kimi Code model configuration (Anthropic-compatible). - `effort: optional "low" or "medium" or "high" or 2 more` Effort level for supported Anthropic models (controls token spending). 'xhigh' and 'max' are available on Opus 4.6+. Not setting this gives similar performance to 'high'. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "moonshot_coding"` The type of the provider. - `"moonshot_coding"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `strict: optional boolean` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: optional number` The temperature of the model. - `thinking: optional object { budget_tokens, type }` The thinking configuration for the model. - `budget_tokens: optional number` The maximum number of tokens the model can use for extended thinking. - `type: optional "enabled" or "disabled"` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: optional "low" or "medium" or "high"` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `GroqModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Groq model configuration (OpenAI-compatible). - `DeepseekModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Deepseek model configuration (OpenAI-compatible). - `TogetherModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` Together AI model configuration (OpenAI-compatible). - `BedrockModelSettings object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` AWS Bedrock model configuration. - `Baseten object { max_output_tokens, parallel_tool_calls, provider_type, temperature }` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "baseten"` The type of the provider. - `"baseten"` - `temperature: optional number` The temperature of the model. - `Openrouter object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "openrouter"` The type of the provider. - `"openrouter"` - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format for the model. - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `temperature: optional number` The temperature of the model. - `ChatgptOAuth object { max_output_tokens, parallel_tool_calls, provider_type, 2 more }` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: optional number` The maximum number of tokens the model can generate. - `parallel_tool_calls: optional boolean` Whether to enable parallel tool calling. - `provider_type: optional "chatgpt_oauth"` The type of the provider. - `"chatgpt_oauth"` - `reasoning: optional object { reasoning_effort }` The reasoning configuration for the model. - `reasoning_effort: optional "none" or "low" or "medium" or 2 more` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: optional number` The temperature of the model. - `multi_agent_group: optional object { id, agent_ids, description, 15 more }` 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 of string` - `description: string` - `manager_type: "round_robin" or "supervisor" or "dynamic" or 3 more` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: optional string` The base template id. - `deployment_id: optional string` The id of the deployment. - `hidden: optional boolean` If set to True, the group will be hidden. - `last_processed_message_id: optional string` - `manager_agent_id: optional string` - `max_message_buffer_length: optional number` 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: optional number` - `min_message_buffer_length: optional number` 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: optional string` The associated project id. - `shared_block_ids: optional array of string` - `sleeptime_agent_frequency: optional number` - `template_id: optional string` The id of the template. - `termination_token: optional string` - `turns_counter: optional number` - `pending_approval: optional ApprovalRequestMessage` A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution). Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call - `id: string` - `date: string` - `tool_call: ToolCall or ToolCallDelta` The tool call that has been requested by the llm to run - `ToolCall object { arguments, name, tool_call_id }` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `arguments: optional string` - `name: optional string` - `tool_call_id: optional string` - `is_err: optional boolean` - `message_type: optional "approval_request_message"` The type of the message. - `"approval_request_message"` - `name: optional string` - `otid: optional string` The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs. - `run_id: optional string` - `sender_id: optional string` - `seq_id: optional number` - `step_id: optional string` - `tool_calls: optional array of ToolCall or ToolCallDelta` The tool calls that have been requested by the llm to run, which are pending approval - `array of ToolCall` - `arguments: string` - `name: string` - `tool_call_id: string` - `ToolCallDelta object { arguments, name, tool_call_id }` - `per_file_view_window_char_limit: optional number` 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: optional string` The id of the project the agent belongs to. - `response_format: optional TextResponseFormat or JsonSchemaResponseFormat or JsonObjectResponseFormat` The response format used by the agent - `TextResponseFormat object { type }` Response format for plain text responses. - `JsonSchemaResponseFormat object { json_schema, type }` Response format for JSON schema-based responses. - `JsonObjectResponseFormat object { type }` Response format for JSON object responses. - `secrets: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `template_id: optional string` The id of the template the agent belongs to. - `timezone: optional string` The timezone of the agent (IANA format). - `tool_exec_environment_variables: optional array of AgentEnvironmentVariable` 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: optional string` The human-friendly ID of the Agent-env - `created_at: optional string` The timestamp when the object was created. - `created_by_id: optional string` The id of the user that made this object. - `description: optional string` An optional description of the environment variable. - `last_updated_by_id: optional string` The id of the user that made this object. - `updated_at: optional string` The timestamp when the object was last updated. - `value_enc: optional string` Encrypted secret value (stored as encrypted string) - `tool_rules: optional array of ChildToolRule or InitToolRule or TerminalToolRule or 6 more` The list of tool rules. - `ChildToolRule object { children, tool_name, child_arg_nodes, 2 more }` A ToolRule represents a tool that can be invoked by the agent. - `children: array of 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: optional array of object { name, args }` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: string` The name of the child tool to invoke next. - `args: optional map[unknown]` 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: optional string` Optional template string (ignored). - `type: optional "constrain_child_tools"` - `"constrain_child_tools"` - `InitToolRule object { 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: optional map[unknown]` 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "run_first"` - `"run_first"` - `TerminalToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "exit_loop"` - `"exit_loop"` - `ConditionalToolRule object { 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: map[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: optional string` The default child tool to be called. If None, any tool can be called. - `prompt_template: optional string` Optional template string (ignored). - `require_output_mapping: optional boolean` Whether to throw an error when output doesn't match any case - `type: optional "conditional"` - `"conditional"` - `ContinueToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "continue_loop"` - `"continue_loop"` - `RequiredBeforeExitToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "required_before_exit"` - `"required_before_exit"` - `MaxCountPerStepToolRule object { 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: optional string` Optional template string (ignored). - `type: optional "max_count_per_step"` - `"max_count_per_step"` - `ParentToolRule object { 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 of 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: optional string` Optional template string (ignored). - `type: optional "parent_last_tool"` - `"parent_last_tool"` - `RequiresApprovalToolRule object { 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: optional string` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: optional "requires_approval"` - `"requires_approval"` - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/folders/detach/$FOLDER_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "llm_config": { "context_window": 0, "model": "model", "model_endpoint_type": "openai", "compatibility_type": "gguf", "display_name": "display_name", "effort": "low", "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": "none", "response_format": { "type": "text" }, "return_logprobs": true, "return_token_ids": true, "strict": true, "temperature": 0, "tier": "tier", "tool_call_parser": "tool_call_parser", "top_logprobs": 0, "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, "tags": [ "string" ], "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, "tags": [ "string" ], "template_id": "template_id", "template_name": "template_name" } ], "git_enabled": true, "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" } ], "project_id": "project_id", "return_char_limit": 1, "source_code": "source_code", "source_type": "source_type", "tags": [ "string" ], "tool_type": "custom" } ], "base_template_id": "base_template_id", "compaction_settings": { "clip_chars": 0, "mode": "all", "model": "model", "model_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "prompt": "prompt", "prompt_acknowledgement": true, "sliding_window_percentage": 0 }, "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "deployment_id": "deployment_id", "description": "description", "embedding": "embedding", "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" }, "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_settings": { "max_output_tokens": 0, "parallel_tool_calls": true, "provider_type": "openai", "reasoning": { "reasoning_effort": "none" }, "response_format": { "type": "text" }, "strict": true, "temperature": 0 }, "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 }, "pending_approval": { "id": "id", "date": "2019-12-27T18:11:19.117Z", "tool_call": { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" }, "is_err": true, "message_type": "approval_request_message", "name": "name", "otid": "otid", "run_id": "run_id", "sender_id": "sender_id", "seq_id": 0, "step_id": "step_id", "tool_calls": [ { "arguments": "arguments", "name": "name", "tool_call_id": "tool_call_id" } ] }, "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" } ``` ## List Folders For Agent **get** `/v1/agents/{agent_id}/folders` Get the folders associated with an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `after: optional string` Cursor for pagination (source ID). Returns results relative to this ID in the specified sort order. Expected format: 'source-' - `before: optional string` Cursor for pagination (source ID). Returns results relative to this ID in the specified sort order. Expected format: 'source-' - `limit: optional number` Maximum number of sources to return - `order: optional "asc" or "desc"` Sort order for sources by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` ### Returns - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/folders \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "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" } ] ``` ## Domain Types ### Folder List Response - `FolderListResponse object { id, embedding_config, name, 8 more }` (Deprecated: Use Folder) Representation of a source, which is a collection of files and passages. - `id: string` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `name: string` The name of the source. - `created_at: optional string` The timestamp when the source was created. - `created_by_id: optional string` The id of the user that made this Tool. - `description: optional string` The description of the source. - `instructions: optional string` Instructions for how to use the source. - `last_updated_by_id: optional string` The id of the user that made this Tool. - `metadata: optional map[unknown]` Metadata associated with the source. - `updated_at: optional string` The timestamp when the source was last updated. - `vector_db_provider: optional VectorDBProvider` The vector database provider used for this source's passages - `"native"` - `"tpuf"` - `"pinecone"` # Files ## Close All Files For Agent **patch** `/v1/agents/{agent_id}/files/close-all` Closes all currently open files for a given agent. This endpoint updates the file state for the agent so that no files are marked as open. Typically used to reset the working memory view for the agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/files/close-all \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ "string" ] ``` ## Open File For Agent **patch** `/v1/agents/{agent_id}/files/{file_id}/open` Opens a specific file for a given agent. This endpoint marks a specific file as open in the agent's file state. The file will be included in the agent's working memory view. Returns a list of file names that were closed due to LRU eviction. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `file_id: string` The ID of the file in the format 'file-' ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/files/$FILE_ID/open \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ "string" ] ``` ## Close File For Agent **patch** `/v1/agents/{agent_id}/files/{file_id}/close` Closes a specific file for a given agent. This endpoint marks a specific file as closed in the agent's file state. The file will be removed from the agent's working memory view. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `file_id: string` The ID of the file in the format 'file-' ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/files/$FILE_ID/close \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## List Files For Agent **get** `/v1/agents/{agent_id}/files` Get the files attached to an agent with their open/closed status. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `after: optional string` Cursor for pagination (file ID). Returns results relative to this ID in the specified sort order. Expected format: 'file-' - `before: optional string` Cursor for pagination (file ID). Returns results relative to this ID in the specified sort order. Expected format: 'file-' - `cursor: optional string` Pagination cursor from previous response (deprecated, use before/after) - `is_open: optional boolean` Filter by open status (true for open files, false for closed files) - `limit: optional number` Maximum number of files to return - `order: optional "asc" or "desc"` Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: optional "created_at"` Field to sort by - `"created_at"` ### Returns - `files: array of object { id, file_id, file_name, 7 more }` List of file attachments for the agent - `id: string` Unique identifier of the file-agent relationship - `file_id: string` Unique identifier of the file - `file_name: string` Name of the file - `folder_id: string` Unique identifier of the folder/source - `folder_name: string` Name of the folder/source - `is_open: boolean` Whether the file is currently open in the agent's context - `end_line: optional number` Ending line number if file was opened with line range - `last_accessed_at: optional string` Timestamp of last access by the agent - `start_line: optional number` Starting line number if file was opened with line range - `visible_content: optional string` Portion of the file visible to the agent if open - `has_more: boolean` Whether more results exist after this page - `next_cursor: optional string` Cursor for fetching the next page (file-agent relationship ID) ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/files \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "files": [ { "id": "id", "file_id": "file_id", "file_name": "file_name", "folder_id": "folder_id", "folder_name": "folder_name", "is_open": true, "end_line": 0, "last_accessed_at": "2019-12-27T18:11:19.117Z", "start_line": 0, "visible_content": "visible_content" } ], "has_more": true, "next_cursor": "next_cursor" } ``` ## Domain Types ### File Close All Response - `FileCloseAllResponse = array of string` ### File Open Response - `FileOpenResponse = array of string` ### File Close Response - `FileCloseResponse = unknown` ### File List Response - `FileListResponse object { id, file_id, file_name, 7 more }` Response model for agent file attachments showing file status in agent context - `id: string` Unique identifier of the file-agent relationship - `file_id: string` Unique identifier of the file - `file_name: string` Name of the file - `folder_id: string` Unique identifier of the folder/source - `folder_name: string` Name of the folder/source - `is_open: boolean` Whether the file is currently open in the agent's context - `end_line: optional number` Ending line number if file was opened with line range - `last_accessed_at: optional string` Timestamp of last access by the agent - `start_line: optional number` Starting line number if file was opened with line range - `visible_content: optional string` Portion of the file visible to the agent if open # Archives ## Attach Archive To Agent **patch** `/v1/agents/{agent_id}/archives/attach/{archive_id}` Attach an archive to an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `archive_id: string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/archives/attach/$ARCHIVE_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## Detach Archive From Agent **patch** `/v1/agents/{agent_id}/archives/detach/{archive_id}` Detach an archive from an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `archive_id: string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/archives/detach/$ARCHIVE_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## Domain Types ### Archive Attach Response - `ArchiveAttachResponse = unknown` ### Archive Detach Response - `ArchiveDetachResponse = unknown` # Passages ## List Passages **get** `/v1/agents/{agent_id}/archival-memory` Retrieve the memories in an agent's archival memory store (paginated query). ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `after: optional string` Unique ID of the memory to start the query range at. - `ascending: optional boolean` Whether to sort passages oldest to newest (True, default) or newest to oldest (False) - `before: optional string` Unique ID of the memory to end the query range at. - `limit: optional number` How many results to include in the response. - `search: optional string` Search passages by text ### Returns - `embedding: array of number` The embedding of the passage. - `embedding_config: EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `text: string` The text of the passage. - `id: optional string` The human-friendly ID of the Passage - `archive_id: optional string` The unique identifier of the archive containing this passage. - `created_at: optional string` The creation date of the passage. - `created_by_id: optional string` The id of the user that made this object. - `file_id: optional string` The unique identifier of the file associated with the passage. - `file_name: optional string` The name of the file (only for source passages). - `is_deleted: optional boolean` Whether this passage is deleted or not. - `last_updated_by_id: optional string` The id of the user that made this object. - `metadata: optional map[unknown]` The metadata of the passage. - `source_id: optional string` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: optional array of string` Tags associated with this passage. - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/archival-memory \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json [ { "embedding": [ 0 ], "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" }, "text": "text", "id": "passage-123e4567-e89b-12d3-a456-426614174000", "archive_id": "archive_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "file_id": "file_id", "file_name": "file_name", "is_deleted": true, "last_updated_by_id": "last_updated_by_id", "metadata": { "foo": "bar" }, "source_id": "source_id", "tags": [ "string" ], "updated_at": "2019-12-27T18:11:19.117Z" } ] ``` ## Create Passage **post** `/v1/agents/{agent_id}/archival-memory` Insert a memory into an agent's archival memory store. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Body Parameters - `text: string` Text to write to archival memory. - `created_at: optional string` Optional timestamp for the memory (defaults to current UTC time). - `tags: optional array of string` Optional list of tags to attach to the memory. ### Returns - `embedding: array of number` The embedding of the passage. - `embedding_config: EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `text: string` The text of the passage. - `id: optional string` The human-friendly ID of the Passage - `archive_id: optional string` The unique identifier of the archive containing this passage. - `created_at: optional string` The creation date of the passage. - `created_by_id: optional string` The id of the user that made this object. - `file_id: optional string` The unique identifier of the file associated with the passage. - `file_name: optional string` The name of the file (only for source passages). - `is_deleted: optional boolean` Whether this passage is deleted or not. - `last_updated_by_id: optional string` The id of the user that made this object. - `metadata: optional map[unknown]` The metadata of the passage. - `source_id: optional string` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: optional array of string` Tags associated with this passage. - `updated_at: optional string` The timestamp when the object was last updated. ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/archival-memory \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $LETTA_API_KEY" \ -d '{ "text": "text" }' ``` #### Response ```json [ { "embedding": [ 0 ], "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" }, "text": "text", "id": "passage-123e4567-e89b-12d3-a456-426614174000", "archive_id": "archive_id", "created_at": "2019-12-27T18:11:19.117Z", "created_by_id": "created_by_id", "file_id": "file_id", "file_name": "file_name", "is_deleted": true, "last_updated_by_id": "last_updated_by_id", "metadata": { "foo": "bar" }, "source_id": "source_id", "tags": [ "string" ], "updated_at": "2019-12-27T18:11:19.117Z" } ] ``` ## Delete Passage **delete** `/v1/agents/{agent_id}/archival-memory/{memory_id}` Delete a memory from an agent's archival memory store. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `memory_id: string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/archival-memory/$MEMORY_ID \ -X DELETE \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## Search Archival Memory **get** `/v1/agents/{agent_id}/archival-memory/search` Search archival memory using semantic (embedding-based) search with optional temporal filtering. This endpoint allows manual triggering of archival memory searches, enabling users to query an agent's archival memory store directly via the API. The search uses the same functionality as the agent's archival_memory_search tool but is accessible for external API usage. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' ### Query Parameters - `query: string` String to search for using semantic similarity - `end_datetime: optional string` Filter results to passages created before this datetime - `start_datetime: optional string` Filter results to passages created after this datetime - `tag_match_mode: optional "any" or "all"` How to match tags - 'any' to match passages with any of the tags, 'all' to match only passages with all tags - `"any"` - `"all"` - `tags: optional array of string` Optional list of tags to filter search results - `top_k: optional number` Maximum number of results to return. Uses system default if not specified ### Returns - `count: number` Total number of results returned - `results: array of object { id, content, timestamp, tags }` List of search results matching the query - `id: string` Unique identifier of the archival memory passage - `content: string` Text content of the archival memory passage - `timestamp: string` Timestamp of when the memory was created, formatted in agent's timezone - `tags: optional array of string` List of tags associated with this memory ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/archival-memory/search \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json { "count": 0, "results": [ { "id": "id", "content": "content", "timestamp": "timestamp", "tags": [ "string" ] } ] } ``` ## Domain Types ### Passage List Response - `PassageListResponse = array of Passage` - `embedding: array of number` The embedding of the passage. - `embedding_config: EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `text: string` The text of the passage. - `id: optional string` The human-friendly ID of the Passage - `archive_id: optional string` The unique identifier of the archive containing this passage. - `created_at: optional string` The creation date of the passage. - `created_by_id: optional string` The id of the user that made this object. - `file_id: optional string` The unique identifier of the file associated with the passage. - `file_name: optional string` The name of the file (only for source passages). - `is_deleted: optional boolean` Whether this passage is deleted or not. - `last_updated_by_id: optional string` The id of the user that made this object. - `metadata: optional map[unknown]` The metadata of the passage. - `source_id: optional string` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: optional array of string` Tags associated with this passage. - `updated_at: optional string` The timestamp when the object was last updated. ### Passage Create Response - `PassageCreateResponse = array of Passage` - `embedding: array of number` The embedding of the passage. - `embedding_config: EmbeddingConfig` Configuration for embedding model connection and processing parameters. - `embedding_dim: number` The dimension of the embedding. - `embedding_endpoint_type: "openai" or "anthropic" or "bedrock" or 16 more` The endpoint type for the model. - `"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: optional string` The Azure deployment for the model. - `azure_endpoint: optional string` The Azure endpoint for the model. - `azure_version: optional string` The Azure version for the model. - `batch_size: optional number` The maximum batch size for processing embeddings. - `embedding_chunk_size: optional number` The chunk size of the embedding. - `embedding_endpoint: optional string` The endpoint for the model (`None` if local). - `handle: optional string` The handle for this config, in the format provider/model-name. - `text: string` The text of the passage. - `id: optional string` The human-friendly ID of the Passage - `archive_id: optional string` The unique identifier of the archive containing this passage. - `created_at: optional string` The creation date of the passage. - `created_by_id: optional string` The id of the user that made this object. - `file_id: optional string` The unique identifier of the file associated with the passage. - `file_name: optional string` The name of the file (only for source passages). - `is_deleted: optional boolean` Whether this passage is deleted or not. - `last_updated_by_id: optional string` The id of the user that made this object. - `metadata: optional map[unknown]` The metadata of the passage. - `source_id: optional string` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: optional array of string` Tags associated with this passage. - `updated_at: optional string` The timestamp when the object was last updated. ### Passage Delete Response - `PassageDeleteResponse = unknown` ### Passage Search Response - `PassageSearchResponse object { count, results }` - `count: number` Total number of results returned - `results: array of object { id, content, timestamp, tags }` List of search results matching the query - `id: string` Unique identifier of the archival memory passage - `content: string` Text content of the archival memory passage - `timestamp: string` Timestamp of when the memory was created, formatted in agent's timezone - `tags: optional array of string` List of tags associated with this memory # Identities ## Attach Identity To Agent **patch** `/v1/agents/{agent_id}/identities/attach/{identity_id}` Attach an identity to an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `identity_id: string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/identities/attach/$IDENTITY_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## Detach Identity From Agent **patch** `/v1/agents/{agent_id}/identities/detach/{identity_id}` Detach an identity from an agent. ### Path Parameters - `agent_id: string` The ID of the agent in the format 'agent-' - `identity_id: string` ### Example ```http curl https://api.letta.com/v1/agents/$AGENT_ID/identities/detach/$IDENTITY_ID \ -X PATCH \ -H "Authorization: Bearer $LETTA_API_KEY" ``` #### Response ```json {} ``` ## Domain Types ### Identity Attach Response - `IdentityAttachResponse = unknown` ### Identity Detach Response - `IdentityDetachResponse = unknown`