# Agents ## List Agents `agents.list(AgentListParams**kwargs) -> SyncArrayPage[AgentState]` **get** `/v1/agents/` Get a list of all agents. ### Parameters - `after: Optional[str]` Cursor for pagination - `ascending: Optional[bool]` Whether to sort agents oldest to newest (True) or newest to oldest (False, default) - `base_template_id: Optional[str]` Search agents by base template ID - `before: Optional[str]` Cursor for pagination - `created_by_id: Optional[str]` Filter agents by the user who created them. - `identifier_keys: Optional[Sequence[str]]` Search agents by identifier keys - `identity_id: Optional[str]` Search agents by identity ID - `include: Optional[List[Literal["agent.blocks", "agent.identities", "agent.managed_group", 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[Sequence[str]]` 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[int]` Limit for pagination - `match_all_tags: Optional[bool]` If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags. - `name: Optional[str]` Name of the agent - `order: Optional[Literal["asc", "desc"]]` Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: Optional[Literal["created_at", "updated_at", "last_run_completion"]]` Field to sort by - `"created_at"` - `"updated_at"` - `"last_run_completion"` - `project_id: Optional[str]` Search agents by project ID - this will default to your default project on cloud - `query_text: Optional[str]` Search agents by name - `sort_by: Optional[str]` Field to sort by. Options: 'created_at' (default), 'last_run_completion' - `tags: Optional[Sequence[str]]` List of tags to filter agents by - `template_id: Optional[str]` Search agents by template ID ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) page = client.agents.list() page = page.items[0] print(page.id) ``` #### 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 `agents.create(AgentCreateParams**kwargs) -> AgentState` **post** `/v1/agents/` Create an agent. ### 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[str]` Deprecated: No longer used. The base template id of the agent. - `block_ids: Optional[Sequence[str]]` The ids of the blocks used by the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `context_window_limit: Optional[int]` The context window limit used by the agent. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` The embedding model handle used by the agent (format: provider/model-name). - `embedding_chunk_size: Optional[int]` Deprecated: No longer used. The embedding chunk size used by the agent. - `embedding_config: Optional[EmbeddingConfigParam]` Configuration for embedding model connection and processing parameters. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `enable_reasoner: Optional[bool]` Deprecated: Use `model` field to configure reasoning instead. Whether to enable internal extended thinking step for a reasoner model. - `enable_sleeptime: Optional[bool]` If set to True, memory management will move to a background agent thread. - `folder_ids: Optional[Sequence[str]]` The ids of the folders used by the agent. - `from_template: Optional[str]` Deprecated: please use the 'create agents from a template' endpoint instead. - `hidden: Optional[bool]` Deprecated: No longer used. If set to True, the agent will be hidden. - `identity_ids: Optional[Sequence[str]]` The ids of the identities associated with this agent. - `include_base_tool_rules: Optional[bool]` If true, attaches the Letta base tool rules (e.g. deny all tools not explicitly allowed). - `include_base_tools: Optional[bool]` If true, attaches the Letta core tools (e.g. core_memory related functions). - `include_default_source: Optional[bool]` If true, automatically creates and attaches a default data source for this agent. - `initial_message_sequence: Optional[Iterable[MessageCreateParam]]` The initial set of messages to put in the agent's in-context memory. - `content: Union[List[LettaMessageContentUnion], str]` The content of the message. - `List[LettaMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `str` - `role: Literal["user", "system", "assistant"]` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `group_id: Optional[str]` The multi-agent group that the message was sent in - `name: Optional[str]` The name of the participant. - `otid: Optional[str]` 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[str]` The id of the sender of the message, can be an identity id or agent id - `type: Optional[Literal["message"]]` The message type to be created. - `"message"` - `llm_config: Optional[LlmConfigParam]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `max_files_open: Optional[int]` 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[int]` Deprecated: Use `model` field to configure reasoning tokens instead. The maximum number of tokens to generate for reasoning step. - `max_tokens: Optional[int]` Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step. - `memory_blocks: Optional[Iterable[CreateBlockParam]]` The blocks to create in the agent's in-context memory. - `label: str` Label of the block. - `value: str` Value of the block. - `base_template_id: Optional[str]` The base template id of the block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[Sequence[str]]` The tags to associate with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `memory_variables: Optional[Dict[str, str]]` Deprecated: Only relevant for creating agents from a template. Use the 'create agents from a template' endpoint instead. - `message_buffer_autoclear: Optional[bool]` 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[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle for the agent to use (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings for the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `name: Optional[str]` The name of the agent. - `parallel_tool_calls: Optional[bool]` 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[int]` 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[str]` 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[str]` Deprecated: No longer used. The id of the project the agent belongs to. - `reasoning: Optional[bool]` Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent. - `response_format: Optional[ResponseFormat]` Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[Dict[str, str]]` The environment variables for tool execution specific to this agent. - `source_ids: Optional[Sequence[str]]` Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent. - `system: Optional[str]` The system prompt used by the agent. - `tags: Optional[Sequence[str]]` The tags associated with the agent. - `template: Optional[bool]` Deprecated: No longer used. - `template_id: Optional[str]` Deprecated: No longer used. The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[Dict[str, str]]` Deprecated: Use `secrets` field instead. Environment variables for tool execution. - `tool_ids: Optional[Sequence[str]]` The ids of the tools used by the agent. - `tool_rules: Optional[Iterable[ToolRule]]` The tool rules governing the agent. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `tools: Optional[Sequence[str]]` The tools used by the agent. ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.create() print(agent_state.id) ``` #### 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 `agents.update(stragent_id, AgentUpdateParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}` Update an existing agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `base_template_id: Optional[str]` The base template id of the agent. - `block_ids: Optional[Sequence[str]]` The ids of the blocks used by the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `context_window_limit: Optional[int]` The context window limit used by the agent. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` The embedding model handle used by the agent (format: provider/model-name). - `embedding_config: Optional[EmbeddingConfigParam]` Configuration for embedding model connection and processing parameters. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `enable_sleeptime: Optional[bool]` If set to True, memory management will move to a background agent thread. - `folder_ids: Optional[Sequence[str]]` The ids of the folders used by the agent. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identity_ids: Optional[Sequence[str]]` The ids of the identities associated with this agent. - `last_run_completion: Optional[Union[str, datetime, null]]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[LlmConfigParam]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `max_files_open: Optional[int]` 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[int]` Deprecated: Use `model` field to configure max output tokens instead. The maximum number of tokens to generate, including reasoning step. - `message_buffer_autoclear: Optional[bool]` 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[Sequence[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings for the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `name: Optional[str]` The name of the agent. - `parallel_tool_calls: Optional[bool]` 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[int]` 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[str]` The id of the project the agent belongs to. - `reasoning: Optional[bool]` Deprecated: Use `model` field to configure reasoning instead. Whether to enable reasoning for this agent. - `response_format: Optional[ResponseFormat]` Deprecated: Use `model_settings` field to configure response format instead. The response format for the agent. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[Dict[str, str]]` The environment variables for tool execution specific to this agent. - `source_ids: Optional[Sequence[str]]` Deprecated: Use `folder_ids` field instead. The ids of the sources used by the agent. - `system: Optional[str]` The system prompt used by the agent. - `tags: Optional[Sequence[str]]` The tags associated with the agent. - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[Dict[str, str]]` Deprecated: use `secrets` field instead - `tool_ids: Optional[Sequence[str]]` The ids of the tools used by the agent. - `tool_rules: Optional[Iterable[ToolRule]]` The tool rules governing the agent. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.update( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.retrieve(stragent_id, AgentRetrieveParams**kwargs) -> AgentState` **get** `/v1/agents/{agent_id}` Get the state of the agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `include: Optional[List[Literal["agent.blocks", "agent.identities", "agent.managed_group", 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[Sequence[str]]` 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 - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.retrieve( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.delete(stragent_id) -> object` **delete** `/v1/agents/{agent_id}` Delete an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' ### Returns - `object` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent = client.agents.delete( "agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent) ``` #### Response ```json {} ``` ## Export Agent `agents.export_file(stragent_id, AgentExportFileParams**kwargs) -> AgentExportFileResponse` **get** `/v1/agents/{agent_id}/export` Export the serialized JSON representation of an agent, formatted with indentation. ### Parameters - `agent_id: str` - `conversation_id: Optional[str]` Conversation ID to export. If provided, uses messages from this conversation instead of the agent's global message history. - `max_steps: Optional[int]` - `scrub_messages: Optional[bool]` If True, excludes all messages from the export. Useful for sharing agent configs without conversation history. - `use_legacy_format: Optional[bool]` 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. ### Returns - `str` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.export_file( agent_id="agent_id", ) print(response) ``` #### Response ```json "string" ``` ## Import Agent `agents.import_file(AgentImportFileParams**kwargs) -> AgentImportFileResponse` **post** `/v1/agents/import` Import a serialized agent file and recreate the agent(s) in the system. Returns the IDs of all imported agents. ### Parameters - `file: FileTypes` - `append_copy_suffix: Optional[bool]` If set to True, appends "_copy" to the end of the agent name. - `embedding: Optional[str]` Embedding handle to override with. - `env_vars_json: Optional[str]` Environment variables as a JSON string to pass to the agent for tool execution. Use 'secrets' instead. - `model: Optional[str]` Model handle to override the agent's default model. This allows the imported agent to use a different model while keeping other defaults (e.g., context size) from the original configuration. - `name: Optional[str]` If provided, overrides the agent name with this value. - `override_embedding_handle: Optional[str]` Override import with specific embedding handle. Use 'embedding' instead. - `override_existing_tools: Optional[bool]` If set to True, existing tools can get their source code overwritten by the uploaded tool definitions. Note that Letta core tools can never be updated externally. - `override_model_handle: Optional[str]` Model handle to override the agent's default model. Use 'model' instead. - `override_name: Optional[str]` If provided, overrides the agent name with this value. Use 'name' instead. - `project_id: Optional[str]` The project ID to associate the uploaded agent with. This is now passed via headers. - `secrets: Optional[str]` Secrets as a JSON string to pass to the agent for tool execution. - `strip_messages: Optional[bool]` If set to True, strips all messages from the agent before importing. - `x_override_embedding_model: Optional[str]` ### Returns - `class AgentImportFileResponse: …` Response model for imported agents - `agent_ids: List[str]` List of IDs of the imported agents ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.import_file( file=b"Example data", ) print(response.agent_ids) ``` #### Response ```json { "agent_ids": [ "string" ] } ``` ## Recompile Agent `agents.recompile(stragent_id, AgentRecompileParams**kwargs) -> AgentRecompileResponse` **post** `/v1/agents/{agent_id}/recompile` Manually trigger system prompt recompilation for an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `dry_run: Optional[bool]` If True, do not persist changes; still returns the compiled system prompt. - `update_timestamp: Optional[bool]` If True, update the in-context memory last edit timestamp embedded in the system prompt. ### Returns - `str` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.recompile( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json "string" ``` ## Domain Types ### Agent Environment Variable - `class AgentEnvironmentVariable: …` - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) ### Agent State - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Agent Type - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 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 - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` ### Azure Model Settings - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. ### Bedrock Model Settings - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. ### Child Tool Rule - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` ### Conditional Tool Rule - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` ### Continue Tool Rule - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` ### Deepseek Model Settings - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. ### Google AI Model Settings - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. ### Google Vertex Model Settings - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. ### Groq Model Settings - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. ### Init Tool Rule - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` ### Json Object Response Format - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` ### Json Schema Response Format - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` ### Letta Message Content Union - `LettaMessageContentUnion` Sent via the Anthropic Messages API - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` ### Max Count Per Step Tool Rule - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` ### Message Create - `class MessageCreate: …` Request to create a message - `content: Union[List[LettaMessageContentUnion], str]` The content of the message. - `List[LettaMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `str` - `role: Literal["user", "system", "assistant"]` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `group_id: Optional[str]` The multi-agent group that the message was sent in - `name: Optional[str]` The name of the participant. - `otid: Optional[str]` 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[str]` The id of the sender of the message, can be an identity id or agent id - `type: Optional[Literal["message"]]` The message type to be created. - `"message"` ### OpenAI Model Settings - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. ### Parent Tool Rule - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` ### Required Before Exit Tool Rule - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` ### Requires Approval Tool Rule - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` ### Terminal Tool Rule - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` ### Text Response Format - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` ### Together Model Settings - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. ### Xai Model Settings - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `temperature: Optional[float]` The temperature of the model. ### Agent Export File Response - `str` ### Agent Import File Response - `class AgentImportFileResponse: …` Response model for imported agents - `agent_ids: List[str]` List of IDs of the imported agents ### Agent Recompile Response - `str` # Messages ## List Messages `agents.messages.list(stragent_id, MessageListParams**kwargs) -> SyncArrayPage[Message]` **get** `/v1/agents/{agent_id}/messages` Retrieve message history for an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `after: Optional[str]` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `assistant_message_tool_kwarg: Optional[str]` The name of the message argument. - `assistant_message_tool_name: Optional[str]` The name of the designated message tool. - `before: Optional[str]` Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-' - `conversation_id: Optional[str]` Conversation ID to filter messages by. - `group_id: Optional[str]` Group ID to filter messages by. - `include_err: Optional[bool]` Whether to include error messages and error statuses. For debugging purposes only. - `include_return_message_types: Optional[List[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[int]` Maximum number of messages to return - `order: Optional[Literal["asc", "desc"]]` Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: Optional[Literal["created_at"]]` Field to sort by - `"created_at"` - `use_assistant_message: Optional[bool]` Whether to use assistant messages ### Returns - `Message` 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 - `class SystemMessage: …` 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: str` - `content: str` The message content sent by the system - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["system_message"]]` The type of the message. - `"system_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class UserMessage: …` 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: str` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["user_message"]]` The type of the message. - `"user_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ReasoningMessage: …` 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: str` - `date: datetime` - `reasoning: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["reasoning_message"]]` The type of the message. - `"reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `signature: Optional[str]` - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: Optional[str]` - `class HiddenReasoningMessage: …` 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: str` - `date: datetime` - `state: Literal["redacted", "omitted"]` - `"redacted"` - `"omitted"` - `hidden_reasoning: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["hidden_reasoning_message"]]` The type of the message. - `"hidden_reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ToolCallMessage: …` 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: str` - `date: datetime` - `tool_call: ToolCall` - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_call_message"]]` The type of the message. - `"tool_call_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ToolReturnMessage: …` 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: str` - `date: datetime` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_return_message"]]` The type of the message. - `"tool_return_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `step_id: Optional[str]` - `tool_returns: Optional[List[ToolReturn]]` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `class AssistantMessage: …` 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: str` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the agent (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["assistant_message"]]` The type of the message. - `"assistant_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class 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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `class ToolCallDelta: …` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ApprovalResponseMessage: …` 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: str` - `date: datetime` - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `approve: Optional[bool]` Whether the tool has been approved - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_response_message"]]` The type of the message. - `"approval_response_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `run_id: Optional[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class SummaryMessage: …` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: str` - `date: datetime` - `summary: str` - `compaction_stats: Optional[CompactionStats]` Statistics about a memory compaction operation. - `context_window: int` The model's context window size - `messages_count_after: int` Number of messages after compaction - `messages_count_before: int` Number of messages before compaction - `trigger: str` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: Optional[int]` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: Optional[int]` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: Optional[bool]` - `message_type: Optional[Literal["summary_message"]]` - `"summary_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class EventMessage: …` 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: str` - `date: datetime` - `event_data: Dict[str, object]` - `event_type: Literal["compaction"]` - `"compaction"` - `is_err: Optional[bool]` - `message_type: Optional[Literal["event_message"]]` - `"event_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) page = client.agents.messages.list( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) page = page.items[0] print(page) ``` #### 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 `agents.messages.create(stragent_id, MessageCreateParams**kwargs) -> LettaResponse` **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 ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `assistant_message_tool_kwarg: Optional[str]` 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[str]` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `background: Optional[bool]` Whether to process the request in the background (only used when streaming=true). - `client_skills: Optional[Iterable[ClientSkill]]` 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: str` Description of what the skill does - `location: str` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: str` The name of the skill - `client_tools: Optional[Iterable[ClientTool]]` 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: str` The name of the tool function - `description: Optional[str]` Description of what the tool does - `parameters: Optional[Dict[str, object]]` JSON Schema for the function parameters - `enable_thinking: Optional[str]` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: Optional[bool]` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_pings: Optional[bool]` Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). - `include_return_message_types: Optional[List[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[Union[str, Iterable[InputUnionMember1], null]]` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `str` - `Iterable[InputUnionMember1]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `class InputUnionMember1SummarizedReasoningContent: …` The style of reasoning content returned by the OpenAI Responses API - `id: str` The unique identifier for this reasoning step. - `summary: Iterable[InputUnionMember1SummarizedReasoningContentSummary]` Summaries of the reasoning content. - `index: int` The index of the summary part. - `text: str` The text of the summary part. - `encrypted_content: Optional[str]` The encrypted reasoning content. - `type: Optional[Literal["summarized_reasoning"]]` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: Optional[int]` Maximum number of steps the agent should take to process the request. - `messages: Optional[Iterable[Message]]` The messages to be sent to the agent. - `class MessageCreate: …` Request to create a message - `content: Union[List[LettaMessageContentUnion], str]` The content of the message. - `List[LettaMessageContentUnion]` - `class TextContent: …` - `class ImageContent: …` - `class ToolCallContent: …` - `class ToolReturnContent: …` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `class OmittedReasoningContent: …` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `str` - `role: Literal["user", "system", "assistant"]` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `group_id: Optional[str]` The multi-agent group that the message was sent in - `name: Optional[str]` The name of the participant. - `otid: Optional[str]` 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[str]` The id of the sender of the message, can be an identity id or agent id - `type: Optional[Literal["message"]]` The message type to be created. - `"message"` - `class ApprovalCreate: …` Input to approve or deny a tool call request - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `approve: Optional[bool]` Whether the tool has been approved - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class MessageToolReturnCreate: …` 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: Iterable[ToolReturnParam]` List of tool returns from client-side execution - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[Literal["tool_return"]]` The message type to be created. - `"tool_return"` - `override_model: Optional[str]` 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[str]` 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[bool]` 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[bool]` 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[bool]` Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). - `streaming: Optional[Literal[false]]` If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response. - `false` - `top_logprobs: Optional[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: Optional[bool]` 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 - `class LettaResponse: …` 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: List[Message]` The messages returned by the agent. - `class SystemMessage: …` 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: str` - `content: str` The message content sent by the system - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["system_message"]]` The type of the message. - `"system_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class UserMessage: …` 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: str` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["user_message"]]` The type of the message. - `"user_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ReasoningMessage: …` 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: str` - `date: datetime` - `reasoning: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["reasoning_message"]]` The type of the message. - `"reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `signature: Optional[str]` - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: Optional[str]` - `class HiddenReasoningMessage: …` 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: str` - `date: datetime` - `state: Literal["redacted", "omitted"]` - `"redacted"` - `"omitted"` - `hidden_reasoning: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["hidden_reasoning_message"]]` The type of the message. - `"hidden_reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ToolCallMessage: …` 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: str` - `date: datetime` - `tool_call: ToolCall` - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_call_message"]]` The type of the message. - `"tool_call_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ToolReturnMessage: …` 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: str` - `date: datetime` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_return_message"]]` The type of the message. - `"tool_return_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `step_id: Optional[str]` - `tool_returns: Optional[List[ToolReturn]]` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `class AssistantMessage: …` 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: str` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the agent (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["assistant_message"]]` The type of the message. - `"assistant_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class 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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `class ToolCallDelta: …` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ApprovalResponseMessage: …` 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: str` - `date: datetime` - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `approve: Optional[bool]` Whether the tool has been approved - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_response_message"]]` The type of the message. - `"approval_response_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `run_id: Optional[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class SummaryMessage: …` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: str` - `date: datetime` - `summary: str` - `compaction_stats: Optional[CompactionStats]` Statistics about a memory compaction operation. - `context_window: int` The model's context window size - `messages_count_after: int` Number of messages after compaction - `messages_count_before: int` Number of messages before compaction - `trigger: str` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: Optional[int]` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: Optional[int]` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: Optional[bool]` - `message_type: Optional[Literal["summary_message"]]` - `"summary_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class EventMessage: …` 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: str` - `date: datetime` - `event_data: Dict[str, object]` - `event_type: Literal["compaction"]` - `"compaction"` - `is_err: Optional[bool]` - `message_type: Optional[Literal["event_message"]]` - `"event_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `stop_reason: StopReason` 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[Literal["stop_reason"]]` The type of the message. - `"stop_reason"` - `usage: Usage` The usage statistics of the agent. - `cache_write_tokens: Optional[int]` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: Optional[int]` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: Optional[int]` The number of tokens generated by the agent. - `context_tokens: Optional[int]` Estimate of tokens currently in the context window. - `message_type: Optional[Literal["usage_statistics"]]` - `"usage_statistics"` - `prompt_tokens: Optional[int]` The number of tokens in the prompt. - `reasoning_tokens: Optional[int]` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: Optional[List[str]]` The background task run IDs associated with the agent interaction - `step_count: Optional[int]` The number of steps taken by the agent. - `total_tokens: Optional[int]` The total number of tokens processed by the agent. - `logprobs: Optional[Logprobs]` Log probabilities of the output tokens from the last LLM call. Only present if return_logprobs was enabled. - `content: Optional[List[LogprobsContent]]` - `token: str` - `logprob: float` - `top_logprobs: List[LogprobsContentTopLogprob]` - `token: str` - `logprob: float` - `bytes: Optional[List[int]]` - `bytes: Optional[List[int]]` - `refusal: Optional[List[LogprobsRefusal]]` - `token: str` - `logprob: float` - `top_logprobs: List[LogprobsRefusalTopLogprob]` - `token: str` - `logprob: float` - `bytes: Optional[List[int]]` - `bytes: Optional[List[int]]` - `turns: Optional[List[Turn]]` 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: Literal["assistant", "tool"]` Role of this turn: 'assistant' for LLM generations (trainable), 'tool' for tool results (non-trainable). - `"assistant"` - `"tool"` - `content: Optional[str]` Text content. For tool turns, client tokenizes this with loss_mask=0. - `output_ids: Optional[List[int]]` Token IDs from SGLang native endpoint. Only present for assistant turns. - `output_token_logprobs: Optional[List[List[object]]]` Logprobs from SGLang: [[logprob, token_id, top_logprob_or_null], ...]. Only present for assistant turns. - `tool_name: Optional[str]` Name of the tool called. Only present for tool turns. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) for message in client.agents.messages.create( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ): print(message) ``` #### 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 `agents.messages.stream(stragent_id, MessageStreamParams**kwargs) -> LettaStreamingResponse` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `assistant_message_tool_kwarg: Optional[str]` 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[str]` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `background: Optional[bool]` Whether to process the request in the background (only used when streaming=true). - `client_skills: Optional[Iterable[ClientSkill]]` 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: str` Description of what the skill does - `location: str` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: str` The name of the skill - `client_tools: Optional[Iterable[ClientTool]]` 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: str` The name of the tool function - `description: Optional[str]` Description of what the tool does - `parameters: Optional[Dict[str, object]]` JSON Schema for the function parameters - `enable_thinking: Optional[str]` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: Optional[bool]` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_pings: Optional[bool]` Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). - `include_return_message_types: Optional[List[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[Union[str, Iterable[InputUnionMember1], null]]` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `str` - `Iterable[InputUnionMember1]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `class InputUnionMember1SummarizedReasoningContent: …` The style of reasoning content returned by the OpenAI Responses API - `id: str` The unique identifier for this reasoning step. - `summary: Iterable[InputUnionMember1SummarizedReasoningContentSummary]` Summaries of the reasoning content. - `index: int` The index of the summary part. - `text: str` The text of the summary part. - `encrypted_content: Optional[str]` The encrypted reasoning content. - `type: Optional[Literal["summarized_reasoning"]]` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: Optional[int]` Maximum number of steps the agent should take to process the request. - `messages: Optional[Iterable[Message]]` The messages to be sent to the agent. - `class MessageCreate: …` Request to create a message - `content: Union[List[LettaMessageContentUnion], str]` The content of the message. - `List[LettaMessageContentUnion]` - `class TextContent: …` - `class ImageContent: …` - `class ToolCallContent: …` - `class ToolReturnContent: …` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `class OmittedReasoningContent: …` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `str` - `role: Literal["user", "system", "assistant"]` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `group_id: Optional[str]` The multi-agent group that the message was sent in - `name: Optional[str]` The name of the participant. - `otid: Optional[str]` 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[str]` The id of the sender of the message, can be an identity id or agent id - `type: Optional[Literal["message"]]` The message type to be created. - `"message"` - `class ApprovalCreate: …` Input to approve or deny a tool call request - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `approve: Optional[bool]` Whether the tool has been approved - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class MessageToolReturnCreate: …` 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: Iterable[ToolReturnParam]` List of tool returns from client-side execution - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[Literal["tool_return"]]` The message type to be created. - `"tool_return"` - `override_model: Optional[str]` 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[str]` 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[bool]` 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[bool]` 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[bool]` Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). - `streaming: Optional[bool]` If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response. - `top_logprobs: Optional[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: Optional[bool]` 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` Streaming response type for Server-Sent Events (SSE) endpoints. Each event in the stream will be one of these types. - `class SystemMessage: …` 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: str` - `content: str` The message content sent by the system - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["system_message"]]` The type of the message. - `"system_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class UserMessage: …` 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: str` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["user_message"]]` The type of the message. - `"user_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ReasoningMessage: …` 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: str` - `date: datetime` - `reasoning: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["reasoning_message"]]` The type of the message. - `"reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `signature: Optional[str]` - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: Optional[str]` - `class HiddenReasoningMessage: …` 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: str` - `date: datetime` - `state: Literal["redacted", "omitted"]` - `"redacted"` - `"omitted"` - `hidden_reasoning: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["hidden_reasoning_message"]]` The type of the message. - `"hidden_reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ToolCallMessage: …` 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: str` - `date: datetime` - `tool_call: ToolCall` - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_call_message"]]` The type of the message. - `"tool_call_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ToolReturnMessage: …` 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: str` - `date: datetime` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_return_message"]]` The type of the message. - `"tool_return_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `step_id: Optional[str]` - `tool_returns: Optional[List[ToolReturn]]` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `class AssistantMessage: …` 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: str` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the agent (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["assistant_message"]]` The type of the message. - `"assistant_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class 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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `class ToolCallDelta: …` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ApprovalResponseMessage: …` 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: str` - `date: datetime` - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `approve: Optional[bool]` Whether the tool has been approved - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_response_message"]]` The type of the message. - `"approval_response_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `run_id: Optional[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class LettaPing: …` 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: str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["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[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class LettaErrorMessage: …` Error messages are used to notify the client of an error that occurred during the agent's execution. - `error_type: str` The type of error. - `message: str` The error message. - `message_type: Literal["error_message"]` The type of the message. - `"error_message"` - `run_id: str` The ID of the run. - `detail: Optional[str]` An optional error detail. - `seq_id: Optional[int]` The sequence ID for cursor-based pagination. - `class LettaStopReason: …` 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[Literal["stop_reason"]]` The type of the message. - `"stop_reason"` - `class LettaUsageStatistics: …` 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[int]` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: Optional[int]` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: Optional[int]` The number of tokens generated by the agent. - `context_tokens: Optional[int]` Estimate of tokens currently in the context window. - `message_type: Optional[Literal["usage_statistics"]]` - `"usage_statistics"` - `prompt_tokens: Optional[int]` The number of tokens in the prompt. - `reasoning_tokens: Optional[int]` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: Optional[List[str]]` The background task run IDs associated with the agent interaction - `step_count: Optional[int]` The number of steps taken by the agent. - `total_tokens: Optional[int]` The total number of tokens processed by the agent. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) for message in client.agents.messages.stream( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ): print(message) ``` #### 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 `agents.messages.cancel(stragent_id, MessageCancelParams**kwargs) -> MessageCancelResponse` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `run_ids: Optional[Sequence[str]]` Optional list of run IDs to cancel ### Returns - `Dict[str, object]` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.messages.cancel( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json { "foo": "bar" } ``` ## Create Message Async `agents.messages.create_async(stragent_id, MessageCreateAsyncParams**kwargs) -> Run` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `assistant_message_tool_kwarg: Optional[str]` 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[str]` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `callback_url: Optional[str]` Optional callback URL to POST to when the job completes - `client_skills: Optional[Iterable[ClientSkill]]` 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: str` Description of what the skill does - `location: str` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: str` The name of the skill - `client_tools: Optional[Iterable[ClientTool]]` 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: str` The name of the tool function - `description: Optional[str]` Description of what the tool does - `parameters: Optional[Dict[str, object]]` JSON Schema for the function parameters - `enable_thinking: Optional[str]` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: Optional[bool]` 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[List[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[Union[str, Iterable[InputUnionMember1], null]]` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `str` - `Iterable[InputUnionMember1]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `class InputUnionMember1SummarizedReasoningContent: …` The style of reasoning content returned by the OpenAI Responses API - `id: str` The unique identifier for this reasoning step. - `summary: Iterable[InputUnionMember1SummarizedReasoningContentSummary]` Summaries of the reasoning content. - `index: int` The index of the summary part. - `text: str` The text of the summary part. - `encrypted_content: Optional[str]` The encrypted reasoning content. - `type: Optional[Literal["summarized_reasoning"]]` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: Optional[int]` Maximum number of steps the agent should take to process the request. - `messages: Optional[Iterable[Message]]` The messages to be sent to the agent. - `class MessageCreate: …` Request to create a message - `content: Union[List[LettaMessageContentUnion], str]` The content of the message. - `List[LettaMessageContentUnion]` - `class TextContent: …` - `class ImageContent: …` - `class ToolCallContent: …` - `class ToolReturnContent: …` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `class OmittedReasoningContent: …` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `str` - `role: Literal["user", "system", "assistant"]` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `group_id: Optional[str]` The multi-agent group that the message was sent in - `name: Optional[str]` The name of the participant. - `otid: Optional[str]` 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[str]` The id of the sender of the message, can be an identity id or agent id - `type: Optional[Literal["message"]]` The message type to be created. - `"message"` - `class ApprovalCreate: …` Input to approve or deny a tool call request - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `approve: Optional[bool]` Whether the tool has been approved - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class MessageToolReturnCreate: …` 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: Iterable[ToolReturnParam]` List of tool returns from client-side execution - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[Literal["tool_return"]]` The message type to be created. - `"tool_return"` - `override_model: Optional[str]` 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[str]` 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[bool]` 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[bool]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: Optional[bool]` 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 - `class Run: …` 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: str` The human-friendly ID of the Run - `agent_id: str` The unique identifier of the agent associated with the run. - `background: Optional[bool]` Whether the run was created in background mode. - `base_template_id: Optional[str]` The base template ID that the run belongs to. - `callback_error: Optional[str]` Optional error message from attempting to POST the callback endpoint. - `callback_sent_at: Optional[datetime]` Timestamp when the callback was last attempted. - `callback_status_code: Optional[int]` HTTP status code returned by the callback endpoint. - `callback_url: Optional[str]` If set, POST to this URL when the run completes. - `completed_at: Optional[datetime]` The timestamp when the run was completed. - `conversation_id: Optional[str]` The unique identifier of the conversation associated with the run. - `created_at: Optional[datetime]` The timestamp when the run was created. - `metadata: Optional[Dict[str, object]]` Additional metadata for the run. - `request_config: Optional[RequestConfig]` The request configuration for the run. - `assistant_message_tool_kwarg: Optional[str]` The name of the message argument in the designated message tool. - `assistant_message_tool_name: Optional[str]` The name of the designated message tool. - `include_return_message_types: Optional[List[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[bool]` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. - `status: Optional[Literal["created", "running", "completed", 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[int]` Total run duration in nanoseconds - `ttft_ns: Optional[int]` Time to first token for a run in nanoseconds ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) run = client.agents.messages.create_async( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(run.id) ``` #### 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 `agents.messages.reset(stragent_id, MessageResetParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}/reset-messages` Resets the messages for an agent ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `add_default_initial_messages: Optional[bool]` If true, adds the default initial messages after resetting. ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.messages.reset( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.messages.compact(stragent_id, MessageCompactParams**kwargs) -> CompactionResponse` **post** `/v1/agents/{agent_id}/summarize` Summarize an agent's conversation history. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). ### Returns - `class CompactionResponse: …` - `num_messages_after: int` - `num_messages_before: int` - `summary: str` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) compaction_response = client.agents.messages.compact( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(compaction_response.num_messages_after) ``` #### Response ```json { "num_messages_after": 0, "num_messages_before": 0, "summary": "summary" } ``` ## Domain Types ### Approval Create - `class ApprovalCreate: …` Input to approve or deny a tool call request - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `approve: Optional[bool]` Whether the tool has been approved - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` ### Approval Request Message - `class 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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` ### Approval Response Message - `class ApprovalResponseMessage: …` 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: str` - `date: datetime` - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `approve: Optional[bool]` Whether the tool has been approved - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_response_message"]]` The type of the message. - `"approval_response_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `run_id: Optional[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Approval Return - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` ### Assistant Message - `class AssistantMessage: …` 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: str` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the agent (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["assistant_message"]]` The type of the message. - `"assistant_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Event Message - `class EventMessage: …` 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: str` - `date: datetime` - `event_data: Dict[str, object]` - `event_type: Literal["compaction"]` - `"compaction"` - `is_err: Optional[bool]` - `message_type: Optional[Literal["event_message"]]` - `"event_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Hidden Reasoning Message - `class HiddenReasoningMessage: …` 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: str` - `date: datetime` - `state: Literal["redacted", "omitted"]` - `"redacted"` - `"omitted"` - `hidden_reasoning: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["hidden_reasoning_message"]]` The type of the message. - `"hidden_reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Image Content - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` ### Internal Message - `class InternalMessage: …` 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: str` The human-friendly ID of the Message - `role: MessageRole` The role of the participant. - `"assistant"` - `"user"` - `"tool"` - `"function"` - `"system"` - `"approval"` - `"summary"` - `agent_id: Optional[str]` The unique identifier of the agent. - `approval_request_id: Optional[str]` The id of the approval request if this message is associated with a tool call request. - `approvals: Optional[List[Approval]]` The list of approvals for this message. - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ApprovalLettaSchemasMessageToolReturnOutput: …` - `status: Literal["success", "error"]` The status of the tool call - `"success"` - `"error"` - `func_response: Optional[Union[str, List[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1], null]]` The function response - either a string or list of content parts (text/image) - `str` - `List[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `stderr: Optional[List[str]]` Captured stderr from the tool invocation - `stdout: Optional[List[str]]` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id: Optional[object]` The ID for the tool call - `approve: Optional[bool]` Whether tool call is approved. - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `content: Optional[List[Content]]` The content of the message. - `class TextContent: …` - `class ImageContent: …` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `class ContentSummarizedReasoningContent: …` The style of reasoning content returned by the OpenAI Responses API - `id: str` The unique identifier for this reasoning step. - `summary: List[ContentSummarizedReasoningContentSummary]` Summaries of the reasoning content. - `index: int` The index of the summary part. - `text: str` The text of the summary part. - `encrypted_content: Optional[str]` The encrypted reasoning content. - `type: Optional[Literal["summarized_reasoning"]]` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `conversation_id: Optional[str]` The conversation this message belongs to - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `denial_reason: Optional[str]` The reason the tool call request was denied. - `group_id: Optional[str]` The multi-agent group that the message was sent in - `is_err: Optional[bool]` Whether this message is part of an error step. Used only for debugging purposes. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `model: Optional[str]` The model used to make the function call. - `name: Optional[str]` For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called. - `otid: Optional[str]` The offline threading id associated with this message - `run_id: Optional[str]` The id of the run that this message was created in. - `sender_id: Optional[str]` The id of the sender of the message, can be an identity id or agent id - `step_id: Optional[str]` The id of the step that this message was created in. - `tool_call_id: Optional[str]` The ID of the tool call. Only applicable for role tool. - `tool_calls: Optional[List[ToolCall]]` The list of tool calls requested. Only applicable for role assistant. - `id: str` - `function: ToolCallFunction` The function that the model called. - `arguments: str` - `name: str` - `type: Literal["function"]` - `"function"` - `tool_returns: Optional[List[ToolReturn]]` Tool execution return information for prior tool calls - `status: Literal["success", "error"]` The status of the tool call - `"success"` - `"error"` - `func_response: Optional[Union[str, List[ToolReturnFuncResponseUnionMember1], null]]` The function response - either a string or list of content parts (text/image) - `str` - `List[ToolReturnFuncResponseUnionMember1]` - `class TextContent: …` - `class ImageContent: …` - `stderr: Optional[List[str]]` Captured stderr from the tool invocation - `stdout: Optional[List[str]]` Captured stdout (e.g. prints, logs) from the tool invocation - `tool_call_id: Optional[object]` The ID for the tool call - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Job Status - `Literal["created", "running", "completed", 4 more]` Status of the job. - `"created"` - `"running"` - `"completed"` - `"failed"` - `"pending"` - `"cancelled"` - `"expired"` ### Job Type - `Literal["job", "run", "batch"]` - `"job"` - `"run"` - `"batch"` ### Letta Assistant Message Content Union - `class LettaAssistantMessageContentUnion: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` ### Letta Request - `class LettaRequest: …` - `assistant_message_tool_kwarg: Optional[str]` 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[str]` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `client_skills: Optional[List[ClientSkill]]` 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: str` Description of what the skill does - `location: str` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: str` The name of the skill - `client_tools: Optional[List[ClientTool]]` 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: str` The name of the tool function - `description: Optional[str]` Description of what the tool does - `parameters: Optional[Dict[str, object]]` JSON Schema for the function parameters - `enable_thinking: Optional[str]` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: Optional[bool]` 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[List[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[Union[str, List[InputUnionMember1], null]]` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `str` - `List[InputUnionMember1]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `class InputUnionMember1SummarizedReasoningContent: …` The style of reasoning content returned by the OpenAI Responses API - `id: str` The unique identifier for this reasoning step. - `summary: List[InputUnionMember1SummarizedReasoningContentSummary]` Summaries of the reasoning content. - `index: int` The index of the summary part. - `text: str` The text of the summary part. - `encrypted_content: Optional[str]` The encrypted reasoning content. - `type: Optional[Literal["summarized_reasoning"]]` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: Optional[int]` Maximum number of steps the agent should take to process the request. - `messages: Optional[List[Message]]` The messages to be sent to the agent. - `class MessageCreate: …` Request to create a message - `content: Union[List[LettaMessageContentUnion], str]` The content of the message. - `List[LettaMessageContentUnion]` - `class TextContent: …` - `class ImageContent: …` - `class ToolCallContent: …` - `class ToolReturnContent: …` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `class OmittedReasoningContent: …` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `str` - `role: Literal["user", "system", "assistant"]` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `group_id: Optional[str]` The multi-agent group that the message was sent in - `name: Optional[str]` The name of the participant. - `otid: Optional[str]` 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[str]` The id of the sender of the message, can be an identity id or agent id - `type: Optional[Literal["message"]]` The message type to be created. - `"message"` - `class ApprovalCreate: …` Input to approve or deny a tool call request - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `approve: Optional[bool]` Whether the tool has been approved - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class MessageToolReturnCreate: …` 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: List[ToolReturn]` List of tool returns from client-side execution - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[Literal["tool_return"]]` The message type to be created. - `"tool_return"` - `override_model: Optional[str]` 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[str]` 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[bool]` 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[bool]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: Optional[bool]` 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 - `class LettaResponse: …` 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: List[Message]` The messages returned by the agent. - `class SystemMessage: …` 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: str` - `content: str` The message content sent by the system - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["system_message"]]` The type of the message. - `"system_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class UserMessage: …` 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: str` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["user_message"]]` The type of the message. - `"user_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ReasoningMessage: …` 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: str` - `date: datetime` - `reasoning: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["reasoning_message"]]` The type of the message. - `"reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `signature: Optional[str]` - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: Optional[str]` - `class HiddenReasoningMessage: …` 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: str` - `date: datetime` - `state: Literal["redacted", "omitted"]` - `"redacted"` - `"omitted"` - `hidden_reasoning: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["hidden_reasoning_message"]]` The type of the message. - `"hidden_reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ToolCallMessage: …` 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: str` - `date: datetime` - `tool_call: ToolCall` - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_call_message"]]` The type of the message. - `"tool_call_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ToolReturnMessage: …` 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: str` - `date: datetime` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_return_message"]]` The type of the message. - `"tool_return_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `step_id: Optional[str]` - `tool_returns: Optional[List[ToolReturn]]` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `class AssistantMessage: …` 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: str` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the agent (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["assistant_message"]]` The type of the message. - `"assistant_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class 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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `class ToolCallDelta: …` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ApprovalResponseMessage: …` 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: str` - `date: datetime` - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `approve: Optional[bool]` Whether the tool has been approved - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_response_message"]]` The type of the message. - `"approval_response_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `run_id: Optional[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class SummaryMessage: …` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: str` - `date: datetime` - `summary: str` - `compaction_stats: Optional[CompactionStats]` Statistics about a memory compaction operation. - `context_window: int` The model's context window size - `messages_count_after: int` Number of messages after compaction - `messages_count_before: int` Number of messages before compaction - `trigger: str` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: Optional[int]` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: Optional[int]` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: Optional[bool]` - `message_type: Optional[Literal["summary_message"]]` - `"summary_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class EventMessage: …` 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: str` - `date: datetime` - `event_data: Dict[str, object]` - `event_type: Literal["compaction"]` - `"compaction"` - `is_err: Optional[bool]` - `message_type: Optional[Literal["event_message"]]` - `"event_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `stop_reason: StopReason` 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[Literal["stop_reason"]]` The type of the message. - `"stop_reason"` - `usage: Usage` The usage statistics of the agent. - `cache_write_tokens: Optional[int]` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: Optional[int]` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: Optional[int]` The number of tokens generated by the agent. - `context_tokens: Optional[int]` Estimate of tokens currently in the context window. - `message_type: Optional[Literal["usage_statistics"]]` - `"usage_statistics"` - `prompt_tokens: Optional[int]` The number of tokens in the prompt. - `reasoning_tokens: Optional[int]` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: Optional[List[str]]` The background task run IDs associated with the agent interaction - `step_count: Optional[int]` The number of steps taken by the agent. - `total_tokens: Optional[int]` The total number of tokens processed by the agent. - `logprobs: Optional[Logprobs]` Log probabilities of the output tokens from the last LLM call. Only present if return_logprobs was enabled. - `content: Optional[List[LogprobsContent]]` - `token: str` - `logprob: float` - `top_logprobs: List[LogprobsContentTopLogprob]` - `token: str` - `logprob: float` - `bytes: Optional[List[int]]` - `bytes: Optional[List[int]]` - `refusal: Optional[List[LogprobsRefusal]]` - `token: str` - `logprob: float` - `top_logprobs: List[LogprobsRefusalTopLogprob]` - `token: str` - `logprob: float` - `bytes: Optional[List[int]]` - `bytes: Optional[List[int]]` - `turns: Optional[List[Turn]]` 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: Literal["assistant", "tool"]` Role of this turn: 'assistant' for LLM generations (trainable), 'tool' for tool results (non-trainable). - `"assistant"` - `"tool"` - `content: Optional[str]` Text content. For tool turns, client tokenizes this with loss_mask=0. - `output_ids: Optional[List[int]]` Token IDs from SGLang native endpoint. Only present for assistant turns. - `output_token_logprobs: Optional[List[List[object]]]` Logprobs from SGLang: [[logprob, token_id, top_logprob_or_null], ...]. Only present for assistant turns. - `tool_name: Optional[str]` Name of the tool called. Only present for tool turns. ### Letta Streaming Request - `class LettaStreamingRequest: …` - `assistant_message_tool_kwarg: Optional[str]` 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[str]` The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward. - `background: Optional[bool]` Whether to process the request in the background (only used when streaming=true). - `client_skills: Optional[List[ClientSkill]]` 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: str` Description of what the skill does - `location: str` Path or location hint for the skill (e.g. skills/my-skill/SKILL.md) - `name: str` The name of the skill - `client_tools: Optional[List[ClientTool]]` 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: str` The name of the tool function - `description: Optional[str]` Description of what the tool does - `parameters: Optional[Dict[str, object]]` JSON Schema for the function parameters - `enable_thinking: Optional[str]` If set to True, enables reasoning before responses or tool calls from the agent. - `include_compaction_messages: Optional[bool]` If True, compaction events emit structured `SummaryMessage` and `EventMessage` types. If False (default), compaction messages are not included in the response. - `include_pings: Optional[bool]` Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true). - `include_return_message_types: Optional[List[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[Union[str, List[InputUnionMember1], null]]` Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}]. - `str` - `List[InputUnionMember1]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` - `class InputUnionMember1SummarizedReasoningContent: …` The style of reasoning content returned by the OpenAI Responses API - `id: str` The unique identifier for this reasoning step. - `summary: List[InputUnionMember1SummarizedReasoningContentSummary]` Summaries of the reasoning content. - `index: int` The index of the summary part. - `text: str` The text of the summary part. - `encrypted_content: Optional[str]` The encrypted reasoning content. - `type: Optional[Literal["summarized_reasoning"]]` Indicates this is a summarized reasoning step. - `"summarized_reasoning"` - `max_steps: Optional[int]` Maximum number of steps the agent should take to process the request. - `messages: Optional[List[Message]]` The messages to be sent to the agent. - `class MessageCreate: …` Request to create a message - `content: Union[List[LettaMessageContentUnion], str]` The content of the message. - `List[LettaMessageContentUnion]` - `class TextContent: …` - `class ImageContent: …` - `class ToolCallContent: …` - `class ToolReturnContent: …` - `class ReasoningContent: …` Sent via the Anthropic Messages API - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `class OmittedReasoningContent: …` A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `str` - `role: Literal["user", "system", "assistant"]` The role of the participant. - `"user"` - `"system"` - `"assistant"` - `batch_item_id: Optional[str]` The id of the LLMBatchItem that this message is associated with - `group_id: Optional[str]` The multi-agent group that the message was sent in - `name: Optional[str]` The name of the participant. - `otid: Optional[str]` 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[str]` The id of the sender of the message, can be an identity id or agent id - `type: Optional[Literal["message"]]` The message type to be created. - `"message"` - `class ApprovalCreate: …` Input to approve or deny a tool call request - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `approve: Optional[bool]` Whether the tool has been approved - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class MessageToolReturnCreate: …` 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: List[ToolReturn]` List of tool returns from client-side execution - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `group_id: Optional[str]` The multi-agent group that the message was sent in - `otid: Optional[str]` 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[Literal["tool_return"]]` The message type to be created. - `"tool_return"` - `override_model: Optional[str]` 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[str]` 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[bool]` 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[bool]` 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[bool]` Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true). - `streaming: Optional[bool]` If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response. - `top_logprobs: Optional[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `use_assistant_message: Optional[bool]` 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` Streaming response type for Server-Sent Events (SSE) endpoints. Each event in the stream will be one of these types. - `class SystemMessage: …` 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: str` - `content: str` The message content sent by the system - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["system_message"]]` The type of the message. - `"system_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class UserMessage: …` 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: str` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["user_message"]]` The type of the message. - `"user_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ReasoningMessage: …` 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: str` - `date: datetime` - `reasoning: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["reasoning_message"]]` The type of the message. - `"reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `signature: Optional[str]` - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: Optional[str]` - `class HiddenReasoningMessage: …` 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: str` - `date: datetime` - `state: Literal["redacted", "omitted"]` - `"redacted"` - `"omitted"` - `hidden_reasoning: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["hidden_reasoning_message"]]` The type of the message. - `"hidden_reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ToolCallMessage: …` 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: str` - `date: datetime` - `tool_call: ToolCall` - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_call_message"]]` The type of the message. - `"tool_call_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ToolReturnMessage: …` 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: str` - `date: datetime` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_return_message"]]` The type of the message. - `"tool_return_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `step_id: Optional[str]` - `tool_returns: Optional[List[ToolReturn]]` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `class AssistantMessage: …` 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: str` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the agent (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["assistant_message"]]` The type of the message. - `"assistant_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class 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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `class ToolCallDelta: …` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ApprovalResponseMessage: …` 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: str` - `date: datetime` - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `approve: Optional[bool]` Whether the tool has been approved - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_response_message"]]` The type of the message. - `"approval_response_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `run_id: Optional[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class LettaPing: …` 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: str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["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[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class LettaErrorMessage: …` Error messages are used to notify the client of an error that occurred during the agent's execution. - `error_type: str` The type of error. - `message: str` The error message. - `message_type: Literal["error_message"]` The type of the message. - `"error_message"` - `run_id: str` The ID of the run. - `detail: Optional[str]` An optional error detail. - `seq_id: Optional[int]` The sequence ID for cursor-based pagination. - `class LettaStopReason: …` 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[Literal["stop_reason"]]` The type of the message. - `"stop_reason"` - `class LettaUsageStatistics: …` 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[int]` The number of input tokens written to cache (Anthropic only). None if not reported by provider. - `cached_input_tokens: Optional[int]` The number of input tokens served from cache. None if not reported by provider. - `completion_tokens: Optional[int]` The number of tokens generated by the agent. - `context_tokens: Optional[int]` Estimate of tokens currently in the context window. - `message_type: Optional[Literal["usage_statistics"]]` - `"usage_statistics"` - `prompt_tokens: Optional[int]` The number of tokens in the prompt. - `reasoning_tokens: Optional[int]` The number of reasoning/thinking tokens generated. None if not reported by provider. - `run_ids: Optional[List[str]]` The background task run IDs associated with the agent interaction - `step_count: Optional[int]` The number of steps taken by the agent. - `total_tokens: Optional[int]` The total number of tokens processed by the agent. ### Letta User Message Content Union - `LettaUserMessageContentUnion` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` ### Message - `Message` 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 - `class SystemMessage: …` 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: str` - `content: str` The message content sent by the system - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["system_message"]]` The type of the message. - `"system_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class UserMessage: …` 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: str` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["user_message"]]` The type of the message. - `"user_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ReasoningMessage: …` 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: str` - `date: datetime` - `reasoning: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["reasoning_message"]]` The type of the message. - `"reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `signature: Optional[str]` - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: Optional[str]` - `class HiddenReasoningMessage: …` 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: str` - `date: datetime` - `state: Literal["redacted", "omitted"]` - `"redacted"` - `"omitted"` - `hidden_reasoning: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["hidden_reasoning_message"]]` The type of the message. - `"hidden_reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class ToolCallMessage: …` 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: str` - `date: datetime` - `tool_call: ToolCall` - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_call_message"]]` The type of the message. - `"tool_call_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ToolReturnMessage: …` 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: str` - `date: datetime` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_return_message"]]` The type of the message. - `"tool_return_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `step_id: Optional[str]` - `tool_returns: Optional[List[ToolReturn]]` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `class ImageContent: …` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` - `class AssistantMessage: …` 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: str` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the agent (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["assistant_message"]]` The type of the message. - `"assistant_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class 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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `class ToolCallDelta: …` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `class ApprovalResponseMessage: …` 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: str` - `date: datetime` - `approval_request_id: Optional[str]` The message ID of the approval request - `approvals: Optional[List[Approval]]` The list of approval responses - `class ApprovalReturn: …` - `approve: bool` Whether the tool has been approved - `tool_call_id: str` The ID of the tool call that corresponds to this approval - `reason: Optional[str]` An optional explanation for the provided approval status - `type: Optional[Literal["approval"]]` The message type to be created. - `"approval"` - `class ToolReturn: …` - `status: Literal["success", "error"]` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `approve: Optional[bool]` Whether the tool has been approved - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_response_message"]]` The type of the message. - `"approval_response_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` An optional explanation for the provided approval status - `run_id: Optional[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class SummaryMessage: …` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: str` - `date: datetime` - `summary: str` - `compaction_stats: Optional[CompactionStats]` Statistics about a memory compaction operation. - `context_window: int` The model's context window size - `messages_count_after: int` Number of messages after compaction - `messages_count_before: int` Number of messages before compaction - `trigger: str` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: Optional[int]` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: Optional[int]` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: Optional[bool]` - `message_type: Optional[Literal["summary_message"]]` - `"summary_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `class EventMessage: …` 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: str` - `date: datetime` - `event_data: Dict[str, object]` - `event_type: Literal["compaction"]` - `"compaction"` - `is_err: Optional[bool]` - `message_type: Optional[Literal["event_message"]]` - `"event_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Message Role - `Literal["assistant", "user", "tool", 4 more]` - `"assistant"` - `"user"` - `"tool"` - `"function"` - `"system"` - `"approval"` - `"summary"` ### Message Type - `Literal["system_message", "user_message", "assistant_message", 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 - `class OmittedReasoningContent: …` 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[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["omitted_reasoning"]]` Indicates this is an omitted reasoning step. - `"omitted_reasoning"` ### Reasoning Content - `class ReasoningContent: …` Sent via the Anthropic Messages API - `is_native: bool` Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning: str` The intermediate reasoning or thought process content. - `signature: Optional[str]` A unique identifier for this reasoning step. - `type: Optional[Literal["reasoning"]]` Indicates this is a reasoning/intermediate step. - `"reasoning"` ### Reasoning Message - `class ReasoningMessage: …` 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: str` - `date: datetime` - `reasoning: str` - `is_err: Optional[bool]` - `message_type: Optional[Literal["reasoning_message"]]` The type of the message. - `"reasoning_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `signature: Optional[str]` - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]` - `"reasoner_model"` - `"non_reasoner_model"` - `step_id: Optional[str]` ### Redacted Reasoning Content - `class RedactedReasoningContent: …` Sent via the Anthropic Messages API - `data: str` The redacted or filtered intermediate reasoning content. - `type: Optional[Literal["redacted_reasoning"]]` Indicates this is a redacted thinking step. - `"redacted_reasoning"` ### Run - `class Run: …` 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: str` The human-friendly ID of the Run - `agent_id: str` The unique identifier of the agent associated with the run. - `background: Optional[bool]` Whether the run was created in background mode. - `base_template_id: Optional[str]` The base template ID that the run belongs to. - `callback_error: Optional[str]` Optional error message from attempting to POST the callback endpoint. - `callback_sent_at: Optional[datetime]` Timestamp when the callback was last attempted. - `callback_status_code: Optional[int]` HTTP status code returned by the callback endpoint. - `callback_url: Optional[str]` If set, POST to this URL when the run completes. - `completed_at: Optional[datetime]` The timestamp when the run was completed. - `conversation_id: Optional[str]` The unique identifier of the conversation associated with the run. - `created_at: Optional[datetime]` The timestamp when the run was created. - `metadata: Optional[Dict[str, object]]` Additional metadata for the run. - `request_config: Optional[RequestConfig]` The request configuration for the run. - `assistant_message_tool_kwarg: Optional[str]` The name of the message argument in the designated message tool. - `assistant_message_tool_name: Optional[str]` The name of the designated message tool. - `include_return_message_types: Optional[List[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[bool]` Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects. - `status: Optional[Literal["created", "running", "completed", 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[int]` Total run duration in nanoseconds - `ttft_ns: Optional[int]` Time to first token for a run in nanoseconds ### Summary Message - `class SummaryMessage: …` A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider. - `id: str` - `date: datetime` - `summary: str` - `compaction_stats: Optional[CompactionStats]` Statistics about a memory compaction operation. - `context_window: int` The model's context window size - `messages_count_after: int` Number of messages after compaction - `messages_count_before: int` Number of messages before compaction - `trigger: str` What triggered the compaction (e.g., 'context_window_exceeded', 'post_step_context_check') - `context_tokens_after: Optional[int]` Token count after compaction (message tokens only, does not include tool definitions) - `context_tokens_before: Optional[int]` Token count before compaction (from LLM usage stats, includes full context sent to LLM) - `is_err: Optional[bool]` - `message_type: Optional[Literal["summary_message"]]` - `"summary_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### System Message - `class SystemMessage: …` 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: str` - `content: str` The message content sent by the system - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["system_message"]]` The type of the message. - `"system_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Text Content - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` ### Tool Call - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` ### Tool Call Content - `class ToolCallContent: …` - `id: str` A unique identifier for this specific tool call instance. - `input: Dict[str, object]` The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `name: str` The name of the tool being called. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this tool call. - `type: Optional[Literal["tool_call"]]` Indicates this content represents a tool call event. - `"tool_call"` ### Tool Call Delta - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` ### Tool Call Message - `class ToolCallMessage: …` 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: str` - `date: datetime` - `tool_call: ToolCall` - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["tool_call_message"]]` The type of the message. - `"tool_call_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` ### Tool Return - `class ToolReturn: …` - `status: Literal["success", "error"]` - `"success"` - `"error"` - `tool_call_id: str` - `tool_return: Union[List[ToolReturnUnionMember0], str]` The tool return value - either a string or list of content parts (text/image) - `List[ToolReturnUnionMember0]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `stderr: Optional[List[str]]` - `stdout: Optional[List[str]]` - `type: Optional[Literal["tool"]]` The message type to be created. - `"tool"` ### Tool Return Content - `class ToolReturnContent: …` - `content: str` The content returned by the tool execution. - `is_error: bool` Indicates whether the tool execution resulted in an error. - `tool_call_id: str` References the ID of the ToolCallContent that initiated this tool call. - `type: Optional[Literal["tool_return"]]` Indicates this content represents a tool return event. - `"tool_return"` ### Update Assistant Message - `class UpdateAssistantMessage: …` - `content: Union[List[LettaAssistantMessageContentUnion], str]` The message content sent by the assistant (can be a string or an array of content parts) - `List[LettaAssistantMessageContentUnion]` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `str` - `message_type: Optional[Literal["assistant_message"]]` - `"assistant_message"` ### Update Reasoning Message - `class UpdateReasoningMessage: …` - `reasoning: str` - `message_type: Optional[Literal["reasoning_message"]]` - `"reasoning_message"` ### Update System Message - `class UpdateSystemMessage: …` - `content: str` The message content sent by the system (can be a string or an array of multi-modal content parts) - `message_type: Optional[Literal["system_message"]]` - `"system_message"` ### Update User Message - `class UpdateUserMessage: …` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `message_type: Optional[Literal["user_message"]]` - `"user_message"` ### User Message - `class UserMessage: …` 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: str` - `content: Union[List[LettaUserMessageContentUnion], str]` The message content sent by the user (can be a string or an array of multi-modal content parts) - `List[LettaUserMessageContentUnion]` - `class TextContent: …` - `text: str` The text content of the message. - `signature: Optional[str]` Stores a unique identifier for any reasoning associated with this text content. - `type: Optional[Literal["text"]]` The type of the message. - `"text"` - `class ImageContent: …` - `source: Source` The source of the image. - `class SourceURLImage: …` - `url: str` The URL of the image. - `type: Optional[Literal["url"]]` The source type for the image. - `"url"` - `class SourceBase64Image: …` - `data: str` The base64 encoded image data. - `media_type: str` The media type for the image. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `type: Optional[Literal["base64"]]` The source type for the image. - `"base64"` - `class SourceLettaImage: …` - `file_id: str` The unique identifier of the image file persisted in storage. - `data: Optional[str]` The base64 encoded image data. - `detail: Optional[str]` What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide) - `media_type: Optional[str]` The media type for the image. - `type: Optional[Literal["letta"]]` The source type for the image. - `"letta"` - `type: Optional[Literal["image"]]` The type of the message. - `"image"` - `str` - `date: datetime` - `is_err: Optional[bool]` - `message_type: Optional[Literal["user_message"]]` The type of the message. - `"user_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` ### Message Cancel Response - `Dict[str, object]` # Schedule ## Schedule Agent Message `agents.schedule.create(stragent_id, ScheduleCreateParams**kwargs) -> ScheduleCreateResponse` **post** `/v1/agents/{agent_id}/schedule` Schedule a message to be sent by the agent at a specified time or on a recurring basis. ### Parameters - `agent_id: str` - `messages: Iterable[Message]` - `content: Union[Iterable[MessageContentUnionMember0], str]` - `Iterable[MessageContentUnionMember0]` - `class MessageContentUnionMember0UnionMember0: …` - `text: str` - `signature: Optional[str]` - `type: Optional[Literal["text"]]` - `"text"` - `class MessageContentUnionMember0UnionMember1: …` - `source: MessageContentUnionMember0UnionMember1Source` - `data: str` - `media_type: str` - `detail: Optional[str]` - `type: Optional[Literal["base64"]]` - `"base64"` - `type: Literal["image"]` - `"image"` - `str` - `role: Literal["user", "assistant", "system"]` - `"user"` - `"assistant"` - `"system"` - `name: Optional[str]` - `otid: Optional[str]` - `sender_id: Optional[str]` - `type: Optional[Literal["message"]]` - `"message"` - `schedule: Schedule` - `class ScheduleUnionMember0: …` - `scheduled_at: float` - `type: Optional[Literal["one-time"]]` - `"one-time"` - `class ScheduleUnionMember1: …` - `cron_expression: str` - `type: Literal["recurring"]` - `"recurring"` - `callback_url: Optional[str]` - `include_return_message_types: Optional[List[Literal["system_message", "user_message", "assistant_message", 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[float]` ### Returns - `class ScheduleCreateResponse: …` - `id: str` - `next_scheduled_at: Optional[str]` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) schedule = client.agents.schedule.create( agent_id="agent_id", messages=[{ "content": [{ "text": "text" }], "role": "user", }], schedule={ "scheduled_at": 0 }, ) print(schedule.id) ``` #### Response ```json { "id": "id", "next_scheduled_at": "next_scheduled_at" } ``` ## List Scheduled Agent Messages `agents.schedule.list(stragent_id, ScheduleListParams**kwargs) -> ScheduleListResponse` **get** `/v1/agents/{agent_id}/schedule` List all scheduled messages for a specific agent. ### Parameters - `agent_id: str` - `after: Optional[str]` - `limit: Optional[str]` ### Returns - `class ScheduleListResponse: …` - `has_next_page: bool` - `scheduled_messages: List[ScheduledMessage]` - `id: str` - `agent_id: str` - `message: ScheduledMessageMessage` - `messages: List[ScheduledMessageMessageMessage]` - `content: Union[List[ScheduledMessageMessageMessageContentUnionMember0], str]` - `List[ScheduledMessageMessageMessageContentUnionMember0]` - `class ScheduledMessageMessageMessageContentUnionMember0UnionMember0: …` - `text: str` - `signature: Optional[str]` - `type: Optional[Literal["text"]]` - `"text"` - `class ScheduledMessageMessageMessageContentUnionMember0UnionMember1: …` - `source: ScheduledMessageMessageMessageContentUnionMember0UnionMember1Source` - `data: str` - `media_type: str` - `detail: Optional[str]` - `type: Optional[Literal["base64"]]` - `"base64"` - `type: Literal["image"]` - `"image"` - `str` - `role: Literal["user", "assistant", "system"]` - `"user"` - `"assistant"` - `"system"` - `name: Optional[str]` - `otid: Optional[str]` - `sender_id: Optional[str]` - `type: Optional[Literal["message"]]` - `"message"` - `callback_url: Optional[str]` - `include_return_message_types: Optional[List[Literal["system_message", "user_message", "assistant_message", 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[float]` - `next_scheduled_time: Optional[str]` - `schedule: ScheduledMessageSchedule` - `class ScheduledMessageScheduleUnionMember0: …` - `scheduled_at: float` - `type: Optional[Literal["one-time"]]` - `"one-time"` - `class ScheduledMessageScheduleUnionMember1: …` - `cron_expression: str` - `type: Literal["recurring"]` - `"recurring"` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) schedules = client.agents.schedule.list( agent_id="agent_id", ) print(schedules.has_next_page) ``` #### 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 `agents.schedule.retrieve(strscheduled_message_id, ScheduleRetrieveParams**kwargs) -> ScheduleRetrieveResponse` **get** `/v1/agents/{agent_id}/schedule/{scheduled_message_id}` Retrieve a scheduled message by its ID for a specific agent. ### Parameters - `agent_id: str` - `scheduled_message_id: str` ### Returns - `class ScheduleRetrieveResponse: …` - `id: str` - `agent_id: str` - `message: Message` - `messages: List[MessageMessage]` - `content: Union[List[MessageMessageContentUnionMember0], str]` - `List[MessageMessageContentUnionMember0]` - `class MessageMessageContentUnionMember0UnionMember0: …` - `text: str` - `signature: Optional[str]` - `type: Optional[Literal["text"]]` - `"text"` - `class MessageMessageContentUnionMember0UnionMember1: …` - `source: MessageMessageContentUnionMember0UnionMember1Source` - `data: str` - `media_type: str` - `detail: Optional[str]` - `type: Optional[Literal["base64"]]` - `"base64"` - `type: Literal["image"]` - `"image"` - `str` - `role: Literal["user", "assistant", "system"]` - `"user"` - `"assistant"` - `"system"` - `name: Optional[str]` - `otid: Optional[str]` - `sender_id: Optional[str]` - `type: Optional[Literal["message"]]` - `"message"` - `callback_url: Optional[str]` - `include_return_message_types: Optional[List[Literal["system_message", "user_message", "assistant_message", 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[float]` - `next_scheduled_time: Optional[str]` - `schedule: Schedule` - `class ScheduleUnionMember0: …` - `scheduled_at: float` - `type: Optional[Literal["one-time"]]` - `"one-time"` - `class ScheduleUnionMember1: …` - `cron_expression: str` - `type: Literal["recurring"]` - `"recurring"` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) schedule = client.agents.schedule.retrieve( scheduled_message_id="scheduled_message_id", agent_id="agent_id", ) print(schedule.id) ``` #### 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 `agents.schedule.delete(strscheduled_message_id, ScheduleDeleteParams**kwargs) -> ScheduleDeleteResponse` **delete** `/v1/agents/{agent_id}/schedule/{scheduled_message_id}` Delete a scheduled message by its ID for a specific agent. ### Parameters - `agent_id: str` - `scheduled_message_id: str` ### Returns - `class ScheduleDeleteResponse: …` - `success: Literal[true]` - `true` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) schedule = client.agents.schedule.delete( scheduled_message_id="scheduled_message_id", agent_id="agent_id", ) print(schedule.success) ``` #### Response ```json { "success": true } ``` ## Domain Types ### Schedule Create Response - `class ScheduleCreateResponse: …` - `id: str` - `next_scheduled_at: Optional[str]` ### Schedule List Response - `class ScheduleListResponse: …` - `has_next_page: bool` - `scheduled_messages: List[ScheduledMessage]` - `id: str` - `agent_id: str` - `message: ScheduledMessageMessage` - `messages: List[ScheduledMessageMessageMessage]` - `content: Union[List[ScheduledMessageMessageMessageContentUnionMember0], str]` - `List[ScheduledMessageMessageMessageContentUnionMember0]` - `class ScheduledMessageMessageMessageContentUnionMember0UnionMember0: …` - `text: str` - `signature: Optional[str]` - `type: Optional[Literal["text"]]` - `"text"` - `class ScheduledMessageMessageMessageContentUnionMember0UnionMember1: …` - `source: ScheduledMessageMessageMessageContentUnionMember0UnionMember1Source` - `data: str` - `media_type: str` - `detail: Optional[str]` - `type: Optional[Literal["base64"]]` - `"base64"` - `type: Literal["image"]` - `"image"` - `str` - `role: Literal["user", "assistant", "system"]` - `"user"` - `"assistant"` - `"system"` - `name: Optional[str]` - `otid: Optional[str]` - `sender_id: Optional[str]` - `type: Optional[Literal["message"]]` - `"message"` - `callback_url: Optional[str]` - `include_return_message_types: Optional[List[Literal["system_message", "user_message", "assistant_message", 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[float]` - `next_scheduled_time: Optional[str]` - `schedule: ScheduledMessageSchedule` - `class ScheduledMessageScheduleUnionMember0: …` - `scheduled_at: float` - `type: Optional[Literal["one-time"]]` - `"one-time"` - `class ScheduledMessageScheduleUnionMember1: …` - `cron_expression: str` - `type: Literal["recurring"]` - `"recurring"` ### Schedule Retrieve Response - `class ScheduleRetrieveResponse: …` - `id: str` - `agent_id: str` - `message: Message` - `messages: List[MessageMessage]` - `content: Union[List[MessageMessageContentUnionMember0], str]` - `List[MessageMessageContentUnionMember0]` - `class MessageMessageContentUnionMember0UnionMember0: …` - `text: str` - `signature: Optional[str]` - `type: Optional[Literal["text"]]` - `"text"` - `class MessageMessageContentUnionMember0UnionMember1: …` - `source: MessageMessageContentUnionMember0UnionMember1Source` - `data: str` - `media_type: str` - `detail: Optional[str]` - `type: Optional[Literal["base64"]]` - `"base64"` - `type: Literal["image"]` - `"image"` - `str` - `role: Literal["user", "assistant", "system"]` - `"user"` - `"assistant"` - `"system"` - `name: Optional[str]` - `otid: Optional[str]` - `sender_id: Optional[str]` - `type: Optional[Literal["message"]]` - `"message"` - `callback_url: Optional[str]` - `include_return_message_types: Optional[List[Literal["system_message", "user_message", "assistant_message", 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[float]` - `next_scheduled_time: Optional[str]` - `schedule: Schedule` - `class ScheduleUnionMember0: …` - `scheduled_at: float` - `type: Optional[Literal["one-time"]]` - `"one-time"` - `class ScheduleUnionMember1: …` - `cron_expression: str` - `type: Literal["recurring"]` - `"recurring"` ### Schedule Delete Response - `class ScheduleDeleteResponse: …` - `success: Literal[true]` - `true` # Blocks ## Retrieve Block For Agent `agents.blocks.retrieve(strblock_label, BlockRetrieveParams**kwargs) -> BlockResponse` **get** `/v1/agents/{agent_id}/core-memory/blocks/{block_label}` Retrieve a core memory block from an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `block_label: str` ### Returns - `class BlockResponse: …` - `id: str` The id of the block. - `value: str` Value of the block. - `base_template_id: Optional[str]` (Deprecated) The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` (Deprecated) The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` (Deprecated) The id of the entity within the template. - `hidden: Optional[bool]` (Deprecated) If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` (Deprecated) Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` (Deprecated) Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` (Deprecated) The id of the template. - `template_name: Optional[str]` (Deprecated) The name of the block template (if it is a template). ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) block_response = client.agents.blocks.retrieve( block_label="block_label", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(block_response.id) ``` #### 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 `agents.blocks.update(strblock_label, BlockUpdateParams**kwargs) -> BlockResponse` **patch** `/v1/agents/{agent_id}/core-memory/blocks/{block_label}` Updates a core memory block of an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `block_label: str` - `base_template_id: Optional[str]` The base template id of the block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[Sequence[str]]` The tags to associate with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `value: Optional[str]` Value of the block. ### Returns - `class BlockResponse: …` - `id: str` The id of the block. - `value: str` Value of the block. - `base_template_id: Optional[str]` (Deprecated) The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` (Deprecated) The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` (Deprecated) The id of the entity within the template. - `hidden: Optional[bool]` (Deprecated) If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` (Deprecated) Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` (Deprecated) Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` (Deprecated) The id of the template. - `template_name: Optional[str]` (Deprecated) The name of the block template (if it is a template). ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) block_response = client.agents.blocks.update( block_label="block_label", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(block_response.id) ``` #### 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 `agents.blocks.list(stragent_id, BlockListParams**kwargs) -> SyncArrayPage[BlockResponse]` **get** `/v1/agents/{agent_id}/core-memory/blocks` Retrieve the core memory blocks of a specific agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `after: Optional[str]` Cursor for pagination (block ID). Returns results relative to this ID in the specified sort order. Expected format: 'block-' - `before: Optional[str]` Cursor for pagination (block ID). Returns results relative to this ID in the specified sort order. Expected format: 'block-' - `limit: Optional[int]` Maximum number of blocks to return - `order: Optional[Literal["asc", "desc"]]` Sort order for blocks by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: Optional[Literal["created_at"]]` Field to sort by - `"created_at"` ### Returns - `class BlockResponse: …` - `id: str` The id of the block. - `value: str` Value of the block. - `base_template_id: Optional[str]` (Deprecated) The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` (Deprecated) The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` (Deprecated) The id of the entity within the template. - `hidden: Optional[bool]` (Deprecated) If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` (Deprecated) Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` (Deprecated) Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` (Deprecated) The id of the template. - `template_name: Optional[str]` (Deprecated) The name of the block template (if it is a template). ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) page = client.agents.blocks.list( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) page = page.items[0] print(page.id) ``` #### 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 `agents.blocks.attach(strblock_id, BlockAttachParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}/core-memory/blocks/attach/{block_id}` Attach a core memory block to an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `block_id: str` The ID of the block in the format 'block-' ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.blocks.attach( block_id="block-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.blocks.detach(strblock_id, BlockDetachParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}/core-memory/blocks/detach/{block_id}` Detach a core memory block from an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `block_id: str` The ID of the block in the format 'block-' ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.blocks.detach( block_id="block-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 - `class Block: …` A Block represents a reserved section of the LLM's context window. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. ### Block Update - `class BlockUpdate: …` Update a block - `base_template_id: Optional[str]` The base template id of the block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags to associate with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `value: Optional[str]` Value of the block. # Tools ## List Tools For Agent `agents.tools.list(stragent_id, ToolListParams**kwargs) -> SyncArrayPage[Tool]` **get** `/v1/agents/{agent_id}/tools` Get tools from an existing agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `after: Optional[str]` Cursor for pagination (tool ID). Returns results relative to this ID in the specified sort order. Expected format: 'tool-' - `before: Optional[str]` Cursor for pagination (tool ID). Returns results relative to this ID in the specified sort order. Expected format: 'tool-' - `limit: Optional[int]` Maximum number of tools to return - `order: Optional[Literal["asc", "desc"]]` Sort order for tools by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: Optional[Literal["created_at"]]` Field to sort by - `"created_at"` ### Returns - `class Tool: …` Representation of a tool, which is a function that can be called by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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 ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) page = client.agents.tools.list( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) page = page.items[0] print(page.id) ``` #### 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 `agents.tools.attach(strtool_id, ToolAttachParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}/tools/attach/{tool_id}` Attach a tool to an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `tool_id: str` The ID of the tool in the format 'tool-' ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.tools.attach( tool_id="tool-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.tools.detach(strtool_id, ToolDetachParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}/tools/detach/{tool_id}` Detach a tool from an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `tool_id: str` The ID of the tool in the format 'tool-' ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.tools.detach( tool_id="tool-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.tools.update_approval(strtool_name, ToolUpdateApprovalParams**kwargs) -> AgentState` **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). ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `tool_name: str` - `requires_approval: bool` Whether the tool requires approval before execution - `requires_approval: bool` Whether the tool requires approval before execution ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.tools.update_approval( tool_name="tool_name", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", body_requires_approval=True, ) print(agent_state.id) ``` #### 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 `agents.tools.run(strtool_name, ToolRunParams**kwargs) -> ToolExecutionResult` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `tool_name: str` - `args: Optional[Dict[str, object]]` Arguments to pass to the tool ### Returns - `class ToolExecutionResult: …` - `status: Literal["success", "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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `func_return: Optional[object]` The function return object - `sandbox_config_fingerprint: Optional[str]` The fingerprint of the config for the sandbox - `stderr: Optional[List[str]]` Captured stderr from the function invocation - `stdout: Optional[List[str]]` Captured stdout (prints, logs) from function invocation ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) tool_execution_result = client.agents.tools.run( tool_name="tool_name", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(tool_execution_result.status) ``` #### 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 - `class ToolExecuteRequest: …` Request to execute a tool. - `args: Optional[Dict[str, object]]` Arguments to pass to the tool ### Tool Execution Result - `class ToolExecutionResult: …` - `status: Literal["success", "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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `func_return: Optional[object]` The function return object - `sandbox_config_fingerprint: Optional[str]` The fingerprint of the config for the sandbox - `stderr: Optional[List[str]]` Captured stderr from the function invocation - `stdout: Optional[List[str]]` Captured stdout (prints, logs) from function invocation # Folders ## Attach Folder To Agent `agents.folders.attach(strfolder_id, FolderAttachParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}/folders/attach/{folder_id}` Attach a folder to an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `folder_id: str` The ID of the source in the format 'source-' ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.folders.attach( folder_id="source-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.folders.detach(strfolder_id, FolderDetachParams**kwargs) -> AgentState` **patch** `/v1/agents/{agent_id}/folders/detach/{folder_id}` Detach a folder from an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `folder_id: str` The ID of the source in the format 'source-' ### Returns - `class 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: str` 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: List[Block]` The memory blocks used by the agent. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` 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: int` The context window size for the model. - `model: str` LLM model name. - `model_endpoint_type: Literal["openai", "anthropic", "google_ai", 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[Literal["gguf", "mlx"]]` The framework compatibility type for the model. - `"gguf"` - `"mlx"` - `display_name: Optional[str]` A human-friendly display name for the model. - `effort: Optional[Literal["low", "medium", "high", 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[bool]` Whether or not the model should use extended thinking if it is a 'reasoning' style model - `frequency_penalty: Optional[float]` 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[str]` The handle for this config, in the format provider/model-name. - `max_reasoning_tokens: Optional[int]` 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[int]` The maximum number of tokens to generate. If not set, the model will use its default value. - `model_endpoint: Optional[str]` The endpoint for the model. - `model_wrapper: Optional[str]` The wrapper for the model. - `parallel_tool_calls: Optional[bool]` 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[str]` The provider name for the model. - `put_inner_thoughts_in_kwargs: Optional[bool]` 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[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model's output. Supports text, json_object, and json_schema (structured outputs). Can be set via model_settings. - `class TextResponseFormat: …` Response format for plain text responses. - `type: Optional[Literal["text"]]` The type of the response format. - `"text"` - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `json_schema: Dict[str, object]` The JSON schema of the response. - `type: Optional[Literal["json_schema"]]` The type of the response format. - `"json_schema"` - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `type: Optional[Literal["json_object"]]` The type of the response format. - `"json_object"` - `return_logprobs: Optional[bool]` Whether to return log probabilities of the output tokens. Useful for RL training. - `return_token_ids: Optional[bool]` 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[bool]` Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas. - `temperature: Optional[float]` The temperature to use when generating text with the model. A higher temperature will result in more random text. - `tier: Optional[str]` The cost tier for the model (cloud only). - `tool_call_parser: Optional[str]` 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[int]` Number of most likely tokens to return at each position (0-20). Requires return_logprobs=True. - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `memory: Memory` Deprecated: Use `blocks` field instead. The in-context memory of the agent. - `blocks: List[Block]` Memory blocks contained in the agent's in-context memory - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_updated_by_id: Optional[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `agent_type: Optional[Union[AgentType, str, null]]` Agent type controlling prompt rendering. - `Literal["memgpt_agent", "memgpt_v2_agent", "letta_v1_agent", 6 more]` - `"memgpt_agent"` - `"memgpt_v2_agent"` - `"letta_v1_agent"` - `"react_agent"` - `"workflow_agent"` - `"split_thread_agent"` - `"sleeptime_agent"` - `"voice_convo_agent"` - `"voice_sleeptime_agent"` - `str` - `file_blocks: Optional[List[MemoryFileBlock]]` Special blocks representing the agent's in-context memory of an attached file - `file_id: str` Unique identifier of the file. - `is_open: bool` True if the agent currently has the file open. - `source_id: str` Deprecated: Use `folder_id` field instead. Unique identifier of the source. - `value: str` Value of the block. - `id: Optional[str]` The human-friendly ID of the Block - `base_template_id: Optional[str]` The base template id of the block. - `created_by_id: Optional[str]` The id of the user that made this Block. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` Description of the block. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the block will be hidden. - `is_template: Optional[bool]` Whether the block is a template (e.g. saved human/persona options). - `label: Optional[str]` Label of the block (e.g. 'human', 'persona') in the context window. - `last_accessed_at: Optional[datetime]` 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[str]` The id of the user that last updated this Block. - `limit: Optional[int]` Character limit of the block. - `metadata: Optional[Dict[str, object]]` Metadata of the block. - `preserve_on_migration: Optional[bool]` Preserve the block on template migration. - `project_id: Optional[str]` The associated project id. - `read_only: Optional[bool]` Whether the agent has read-only access to the block. - `tags: Optional[List[str]]` The tags associated with the block. - `template_id: Optional[str]` The id of the template. - `template_name: Optional[str]` Name of the block if it is a template. - `git_enabled: Optional[bool]` Whether this agent uses git-backed memory with structured labels. - `prompt_template: Optional[str]` Deprecated. Ignored for performance. - `name: str` The name of the agent. - `sources: List[Source]` Deprecated: Use `folders` field instead. The sources used by the agent. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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: str` The system prompt used by the agent. - `tags: List[str]` The tags associated with the agent. - `tools: List[Tool]` The tools used by the agent. - `id: str` The human-friendly ID of the Tool - `args_json_schema: Optional[Dict[str, object]]` The args JSON schema of the function. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `default_requires_approval: Optional[bool]` Default value for whether or not executing this tool requires approval. - `description: Optional[str]` The description of the tool. - `enable_parallel_execution: Optional[bool]` If set to True, then this tool will potentially be executed concurrently with other tools. Default False. - `json_schema: Optional[Dict[str, object]]` The JSON schema of the function. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` A dictionary of additional metadata for the tool. - `name: Optional[str]` The name of the function. - `npm_requirements: Optional[List[NpmRequirement]]` Optional list of npm packages required by this tool. - `name: str` Name of the npm package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `pip_requirements: Optional[List[PipRequirement]]` Optional list of pip packages required by this tool. - `name: str` Name of the pip package. - `version: Optional[str]` Optional version of the package, following semantic versioning. - `project_id: Optional[str]` The project id of the tool. - `return_char_limit: Optional[int]` The maximum number of characters in the response. - `source_code: Optional[str]` The source code of the function. - `source_type: Optional[str]` The type of the source code. - `tags: Optional[List[str]]` 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[str]` The base template id of the agent. - `compaction_settings: Optional[CompactionSettings]` Configuration for conversation compaction / summarization. Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle. - `clip_chars: Optional[int]` The maximum length of the summary in characters. If none, no clipping is performed. - `mode: Optional[Literal["all", "sliding_window", "self_compact_all", "self_compact_sliding_window"]]` The type of summarization technique use. - `"all"` - `"sliding_window"` - `"self_compact_all"` - `"self_compact_sliding_window"` - `model: Optional[str]` Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults. - `model_settings: Optional[CompactionSettingsModelSettings]` Optional model settings used to override defaults for the summarizer model. - `class OpenAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openai"]]` The type of the provider. - `"openai"` - `reasoning: Optional[Reasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[CompactionSettingsModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[CompactionSettingsModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["anthropic"]]` The type of the provider. - `"anthropic"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[Thinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GoogleAIModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_ai"]]` The type of the provider. - `"google_ai"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class GoogleVertexModelSettings: …` - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["google_vertex"]]` The type of the provider. - `"google_vertex"` - `response_schema: Optional[ResponseSchema]` The response schema for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking_config: Optional[ThinkingConfig]` The thinking configuration for the model. - `include_thoughts: Optional[bool]` Whether to include thoughts in the model's response. - `thinking_budget: Optional[int]` The thinking budget for the model. - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["azure"]]` The type of the provider. - `"azure"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["xai"]]` The type of the provider. - `"xai"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[CompactionSettingsModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class CompactionSettingsModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[CompactionSettingsModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["groq"]]` The type of the provider. - `"groq"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["deepseek"]]` The type of the provider. - `"deepseek"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["together"]]` The type of the provider. - `"together"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["bedrock"]]` The type of the provider. - `"bedrock"` - `response_format: Optional[ResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[CompactionSettingsModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class CompactionSettingsModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[CompactionSettingsModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `prompt: Optional[str]` The prompt to use for summarization. If None, uses mode-specific default. - `prompt_acknowledgement: Optional[bool]` Whether to include an acknowledgement post-prompt (helps prevent non-summary outputs). - `sliding_window_percentage: Optional[float]` The percentage of the context window to keep post-summarization (only used in sliding window modes). - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `deployment_id: Optional[str]` The id of the deployment. - `description: Optional[str]` The description of the agent. - `embedding: Optional[str]` 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[bool]` If set to True, memory management will move to a background agent thread. - `entity_id: Optional[str]` The id of the entity within the template. - `hidden: Optional[bool]` If set to True, the agent will be hidden. - `identities: Optional[List[Identity]]` The identities associated with this agent. - `id: str` The human-friendly ID of the Identity - `agent_ids: List[str]` The IDs of the agents associated with the identity. - `block_ids: List[str]` The IDs of the blocks associated with the identity. - `identifier_key: str` External, user-generated identifier key of the identity. - `identity_type: Literal["org", "user", "other"]` The type of the identity. - `"org"` - `"user"` - `"other"` - `name: str` The name of the identity. - `project_id: Optional[str]` The project id of the identity, if applicable. - `properties: Optional[List[IdentityProperty]]` List of properties associated with the identity - `key: str` The key of the property - `type: Literal["string", "number", "boolean", "json"]` The type of the property - `"string"` - `"number"` - `"boolean"` - `"json"` - `value: Union[str, float, bool, Dict[str, object]]` The value of the property - `str` - `float` - `bool` - `Dict[str, object]` - `identity_ids: Optional[List[str]]` Deprecated: Use `identities` field instead. The ids of the identities associated with this agent. - `last_run_completion: Optional[datetime]` The timestamp when the agent last completed a run. - `last_run_duration_ms: Optional[int]` 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[str]` The id of the user that made this object. - `managed_group: Optional[ManagedGroup]` The multi-agent group that this agent manages - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `max_files_open: Optional[int]` 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[bool]` 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[List[str]]` The ids of the messages in the agent's in-context memory. - `metadata: Optional[Dict[str, object]]` The metadata of the agent. - `model: Optional[str]` The model handle used by the agent (format: provider/model-name). - `model_settings: Optional[ModelSettings]` The model settings used by the agent. - `class OpenAIModelSettings: …` - `class ModelSettingsSgLangModelSettings: …` SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["sglang"]]` The type of the provider. - `"sglang"` - `reasoning: Optional[ModelSettingsSgLangModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "minimal", "low", 3 more]]` The reasoning effort to use when generating text reasoning models - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `response_format: Optional[ModelSettingsSgLangModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `tool_call_parser: Optional[str]` SGLang tool call parser name (for example 'glm47', 'qwen25', or 'hermes'). - `class AnthropicModelSettings: …` - `class GoogleAIModelSettings: …` - `class GoogleVertexModelSettings: …` - `class AzureModelSettings: …` Azure OpenAI model configuration (OpenAI-compatible). - `class XaiModelSettings: …` xAI model configuration (OpenAI-compatible). - `class ModelSettingsMoonshotModelSettings: …` Moonshot/Kimi model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot"]]` The type of the provider. - `"moonshot"` - `response_format: Optional[ModelSettingsMoonshotModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsZaiModelSettings: …` Z.ai (ZhipuAI) model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["zai"]]` The type of the provider. - `"zai"` - `response_format: Optional[ModelSettingsZaiModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsZaiModelSettingsThinking]` The thinking configuration for GLM-4.5+ models. - `clear_thinking: Optional[bool]` If False, preserved thinking is used (recommended for agents). - `type: Optional[Literal["enabled", "disabled"]]` Whether thinking is enabled or disabled. - `"enabled"` - `"disabled"` - `class ModelSettingsMoonshotCodingModelSettings: …` Kimi Code model configuration (Anthropic-compatible). - `effort: Optional[Literal["low", "medium", "high", 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[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["moonshot_coding"]]` The type of the provider. - `"moonshot_coding"` - `response_format: Optional[ModelSettingsMoonshotCodingModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `strict: Optional[bool]` Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas. - `temperature: Optional[float]` The temperature of the model. - `thinking: Optional[ModelSettingsMoonshotCodingModelSettingsThinking]` The thinking configuration for the model. - `budget_tokens: Optional[int]` The maximum number of tokens the model can use for extended thinking. - `type: Optional[Literal["enabled", "disabled"]]` The type of thinking to use. - `"enabled"` - `"disabled"` - `verbosity: Optional[Literal["low", "medium", "high"]]` Soft control for how verbose model output should be, used for GPT-5 models. - `"low"` - `"medium"` - `"high"` - `class GroqModelSettings: …` Groq model configuration (OpenAI-compatible). - `class DeepseekModelSettings: …` Deepseek model configuration (OpenAI-compatible). - `class TogetherModelSettings: …` Together AI model configuration (OpenAI-compatible). - `class BedrockModelSettings: …` AWS Bedrock model configuration. - `class ModelSettingsBasetenModelSettings: …` Baseten model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["baseten"]]` The type of the provider. - `"baseten"` - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsOpenRouterModelSettings: …` OpenRouter model configuration (OpenAI-compatible). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["openrouter"]]` The type of the provider. - `"openrouter"` - `response_format: Optional[ModelSettingsOpenRouterModelSettingsResponseFormat]` The response format for the model. - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `temperature: Optional[float]` The temperature of the model. - `class ModelSettingsChatGptoAuthModelSettings: …` ChatGPT OAuth model configuration (uses ChatGPT backend API). - `max_output_tokens: Optional[int]` The maximum number of tokens the model can generate. - `parallel_tool_calls: Optional[bool]` Whether to enable parallel tool calling. - `provider_type: Optional[Literal["chatgpt_oauth"]]` The type of the provider. - `"chatgpt_oauth"` - `reasoning: Optional[ModelSettingsChatGptoAuthModelSettingsReasoning]` The reasoning configuration for the model. - `reasoning_effort: Optional[Literal["none", "low", "medium", 2 more]]` The reasoning effort level for GPT-5.x and o-series models. - `"none"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `temperature: Optional[float]` The temperature of the model. - `multi_agent_group: Optional[MultiAgentGroup]` Deprecated: Use `managed_group` field instead. The multi-agent group that this agent manages. - `id: str` The id of the group. Assigned by the database. - `agent_ids: List[str]` - `description: str` - `manager_type: Literal["round_robin", "supervisor", "dynamic", 3 more]` - `"round_robin"` - `"supervisor"` - `"dynamic"` - `"sleeptime"` - `"voice_sleeptime"` - `"swarm"` - `base_template_id: Optional[str]` The base template id. - `deployment_id: Optional[str]` The id of the deployment. - `hidden: Optional[bool]` If set to True, the group will be hidden. - `last_processed_message_id: Optional[str]` - `manager_agent_id: Optional[str]` - `max_message_buffer_length: Optional[int]` 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[int]` - `min_message_buffer_length: Optional[int]` 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[str]` The associated project id. - `shared_block_ids: Optional[List[str]]` - `sleeptime_agent_frequency: Optional[int]` - `template_id: Optional[str]` The id of the template. - `termination_token: Optional[str]` - `turns_counter: Optional[int]` - `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: str` - `date: datetime` - `tool_call: ToolCall` The tool call that has been requested by the llm to run - `class ToolCall: …` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `arguments: Optional[str]` - `name: Optional[str]` - `tool_call_id: Optional[str]` - `is_err: Optional[bool]` - `message_type: Optional[Literal["approval_request_message"]]` The type of the message. - `"approval_request_message"` - `name: Optional[str]` - `otid: Optional[str]` 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[str]` - `sender_id: Optional[str]` - `seq_id: Optional[int]` - `step_id: Optional[str]` - `tool_calls: Optional[ToolCalls]` The tool calls that have been requested by the llm to run, which are pending approval - `List[ToolCall]` - `arguments: str` - `name: str` - `tool_call_id: str` - `class ToolCallDelta: …` - `per_file_view_window_char_limit: Optional[int]` 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[str]` The id of the project the agent belongs to. - `response_format: Optional[ResponseFormat]` The response format used by the agent - `class TextResponseFormat: …` Response format for plain text responses. - `class JsonSchemaResponseFormat: …` Response format for JSON schema-based responses. - `class JsonObjectResponseFormat: …` Response format for JSON object responses. - `secrets: Optional[List[AgentEnvironmentVariable]]` The environment variables for tool execution specific to this agent. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `template_id: Optional[str]` The id of the template the agent belongs to. - `timezone: Optional[str]` The timezone of the agent (IANA format). - `tool_exec_environment_variables: Optional[List[AgentEnvironmentVariable]]` Deprecated: use `secrets` field instead. - `agent_id: str` The ID of the agent this environment variable belongs to. - `key: str` The name of the environment variable. - `value: str` The value of the environment variable. - `id: Optional[str]` The human-friendly ID of the Agent-env - `created_at: Optional[datetime]` The timestamp when the object was created. - `created_by_id: Optional[str]` The id of the user that made this object. - `description: Optional[str]` An optional description of the environment variable. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. - `value_enc: Optional[str]` Encrypted secret value (stored as encrypted string) - `tool_rules: Optional[List[ToolRule]]` The list of tool rules. - `class ChildToolRule: …` A ToolRule represents a tool that can be invoked by the agent. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `child_arg_nodes: Optional[List[ChildArgNode]]` Optional list of typed child argument overrides. Each node must reference a child in 'children'. - `name: str` The name of the child tool to invoke next. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). - `type: Optional[Literal["constrain_child_tools"]]` - `"constrain_child_tools"` - `class InitToolRule: …` Represents the initial tool rule configuration. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `args: Optional[Dict[str, object]]` 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[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["run_first"]]` - `"run_first"` - `class TerminalToolRule: …` Represents a terminal tool rule configuration where if this tool gets called, it must end the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["exit_loop"]]` - `"exit_loop"` - `class ConditionalToolRule: …` A ToolRule that conditionally maps to different child tools based on the output. - `child_output_mapping: Dict[str, str]` The output case to check for mapping - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `default_child: Optional[str]` The default child tool to be called. If None, any tool can be called. - `prompt_template: Optional[str]` Optional template string (ignored). - `require_output_mapping: Optional[bool]` Whether to throw an error when output doesn't match any case - `type: Optional[Literal["conditional"]]` - `"conditional"` - `class ContinueToolRule: …` Represents a tool rule configuration where if this tool gets called, it must continue the agent loop. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["continue_loop"]]` - `"continue_loop"` - `class RequiredBeforeExitToolRule: …` Represents a tool rule configuration where this tool must be called before the agent loop can exit. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["required_before_exit"]]` - `"required_before_exit"` - `class MaxCountPerStepToolRule: …` Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step. - `max_count_limit: int` The max limit for the total number of times this tool can be invoked in a single step. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["max_count_per_step"]]` - `"max_count_per_step"` - `class ParentToolRule: …` A ToolRule that only allows a child tool to be called if the parent has been called. - `children: List[str]` The children tools that can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). - `type: Optional[Literal["parent_last_tool"]]` - `"parent_last_tool"` - `class RequiresApprovalToolRule: …` Represents a tool rule configuration which requires approval before the tool can be invoked. - `tool_name: str` The name of the tool. Must exist in the database for the user's organization. - `prompt_template: Optional[str]` Optional template string (ignored). Rendering uses fast built-in formatting for performance. - `type: Optional[Literal["requires_approval"]]` - `"requires_approval"` - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) agent_state = client.agents.folders.detach( folder_id="source-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(agent_state.id) ``` #### 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 `agents.folders.list(stragent_id, FolderListParams**kwargs) -> SyncArrayPage[FolderListResponse]` **get** `/v1/agents/{agent_id}/folders` Get the folders associated with an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `after: Optional[str]` Cursor for pagination (source ID). Returns results relative to this ID in the specified sort order. Expected format: 'source-' - `before: Optional[str]` Cursor for pagination (source ID). Returns results relative to this ID in the specified sort order. Expected format: 'source-' - `limit: Optional[int]` Maximum number of sources to return - `order: Optional[Literal["asc", "desc"]]` Sort order for sources by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: Optional[Literal["created_at"]]` Field to sort by - `"created_at"` ### Returns - `class FolderListResponse: …` (Deprecated: Use Folder) Representation of a source, which is a collection of files and passages. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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 ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) page = client.agents.folders.list( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) page = page.items[0] print(page.id) ``` #### 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 - `class FolderListResponse: …` (Deprecated: Use Folder) Representation of a source, which is a collection of files and passages. - `id: str` The human-friendly ID of the Source - `embedding_config: EmbeddingConfig` The embedding configuration used by the source. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `name: str` The name of the source. - `created_at: Optional[datetime]` The timestamp when the source was created. - `created_by_id: Optional[str]` The id of the user that made this Tool. - `description: Optional[str]` The description of the source. - `instructions: Optional[str]` Instructions for how to use the source. - `last_updated_by_id: Optional[str]` The id of the user that made this Tool. - `metadata: Optional[Dict[str, object]]` Metadata associated with the source. - `updated_at: Optional[datetime]` 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 `agents.files.close_all(stragent_id) -> FileCloseAllResponse` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' ### Returns - `List[str]` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.files.close_all( "agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json [ "string" ] ``` ## Open File For Agent `agents.files.open(strfile_id, FileOpenParams**kwargs) -> FileOpenResponse` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `file_id: str` The ID of the file in the format 'file-' ### Returns - `List[str]` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.files.open( file_id="file-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json [ "string" ] ``` ## Close File For Agent `agents.files.close(strfile_id, FileCloseParams**kwargs) -> object` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `file_id: str` The ID of the file in the format 'file-' ### Returns - `object` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.files.close( file_id="file-123e4567-e89b-42d3-8456-426614174000", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json {} ``` ## List Files For Agent `agents.files.list(stragent_id, FileListParams**kwargs) -> SyncNextFilesPage[FileListResponse]` **get** `/v1/agents/{agent_id}/files` Get the files attached to an agent with their open/closed status. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `after: Optional[str]` Cursor for pagination (file ID). Returns results relative to this ID in the specified sort order. Expected format: 'file-' - `before: Optional[str]` Cursor for pagination (file ID). Returns results relative to this ID in the specified sort order. Expected format: 'file-' - `cursor: Optional[str]` Pagination cursor from previous response (deprecated, use before/after) - `is_open: Optional[bool]` Filter by open status (true for open files, false for closed files) - `limit: Optional[int]` Maximum number of files to return - `order: Optional[Literal["asc", "desc"]]` Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest first - `"asc"` - `"desc"` - `order_by: Optional[Literal["created_at"]]` Field to sort by - `"created_at"` ### Returns - `class FileListResponse: …` Response model for agent file attachments showing file status in agent context - `id: str` Unique identifier of the file-agent relationship - `file_id: str` Unique identifier of the file - `file_name: str` Name of the file - `folder_id: str` Unique identifier of the folder/source - `folder_name: str` Name of the folder/source - `is_open: bool` Whether the file is currently open in the agent's context - `end_line: Optional[int]` Ending line number if file was opened with line range - `last_accessed_at: Optional[datetime]` Timestamp of last access by the agent - `start_line: Optional[int]` Starting line number if file was opened with line range - `visible_content: Optional[str]` Portion of the file visible to the agent if open ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) page = client.agents.files.list( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) page = page.files[0] print(page.id) ``` #### 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 - `List[str]` ### File Open Response - `List[str]` ### File List Response - `class FileListResponse: …` Response model for agent file attachments showing file status in agent context - `id: str` Unique identifier of the file-agent relationship - `file_id: str` Unique identifier of the file - `file_name: str` Name of the file - `folder_id: str` Unique identifier of the folder/source - `folder_name: str` Name of the folder/source - `is_open: bool` Whether the file is currently open in the agent's context - `end_line: Optional[int]` Ending line number if file was opened with line range - `last_accessed_at: Optional[datetime]` Timestamp of last access by the agent - `start_line: Optional[int]` Starting line number if file was opened with line range - `visible_content: Optional[str]` Portion of the file visible to the agent if open # Archives ## Attach Archive To Agent `agents.archives.attach(strarchive_id, ArchiveAttachParams**kwargs) -> object` **patch** `/v1/agents/{agent_id}/archives/attach/{archive_id}` Attach an archive to an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `archive_id: str` ### Returns - `object` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.archives.attach( archive_id="archive_id", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json {} ``` ## Detach Archive From Agent `agents.archives.detach(strarchive_id, ArchiveDetachParams**kwargs) -> object` **patch** `/v1/agents/{agent_id}/archives/detach/{archive_id}` Detach an archive from an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `archive_id: str` ### Returns - `object` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.archives.detach( archive_id="archive_id", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json {} ``` # Passages ## List Passages `agents.passages.list(stragent_id, PassageListParams**kwargs) -> PassageListResponse` **get** `/v1/agents/{agent_id}/archival-memory` Retrieve the memories in an agent's archival memory store (paginated query). ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `after: Optional[str]` Unique ID of the memory to start the query range at. - `ascending: Optional[bool]` Whether to sort passages oldest to newest (True, default) or newest to oldest (False) - `before: Optional[str]` Unique ID of the memory to end the query range at. - `limit: Optional[int]` How many results to include in the response. - `search: Optional[str]` Search passages by text ### Returns - `List[Passage]` - `embedding: Optional[List[float]]` The embedding of the passage. - `embedding_config: Optional[EmbeddingConfig]` Configuration for embedding model connection and processing parameters. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `text: str` The text of the passage. - `id: Optional[str]` The human-friendly ID of the Passage - `archive_id: Optional[str]` The unique identifier of the archive containing this passage. - `created_at: Optional[datetime]` The creation date of the passage. - `created_by_id: Optional[str]` The id of the user that made this object. - `file_id: Optional[str]` The unique identifier of the file associated with the passage. - `file_name: Optional[str]` The name of the file (only for source passages). - `is_deleted: Optional[bool]` Whether this passage is deleted or not. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `metadata: Optional[Dict[str, object]]` The metadata of the passage. - `source_id: Optional[str]` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: Optional[List[str]]` Tags associated with this passage. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) passages = client.agents.passages.list( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(passages) ``` #### 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 `agents.passages.create(stragent_id, PassageCreateParams**kwargs) -> PassageCreateResponse` **post** `/v1/agents/{agent_id}/archival-memory` Insert a memory into an agent's archival memory store. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `text: str` Text to write to archival memory. - `created_at: Optional[Union[str, datetime, null]]` Optional timestamp for the memory (defaults to current UTC time). - `tags: Optional[Sequence[str]]` Optional list of tags to attach to the memory. ### Returns - `List[Passage]` - `embedding: Optional[List[float]]` The embedding of the passage. - `embedding_config: Optional[EmbeddingConfig]` Configuration for embedding model connection and processing parameters. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `text: str` The text of the passage. - `id: Optional[str]` The human-friendly ID of the Passage - `archive_id: Optional[str]` The unique identifier of the archive containing this passage. - `created_at: Optional[datetime]` The creation date of the passage. - `created_by_id: Optional[str]` The id of the user that made this object. - `file_id: Optional[str]` The unique identifier of the file associated with the passage. - `file_name: Optional[str]` The name of the file (only for source passages). - `is_deleted: Optional[bool]` Whether this passage is deleted or not. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `metadata: Optional[Dict[str, object]]` The metadata of the passage. - `source_id: Optional[str]` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: Optional[List[str]]` Tags associated with this passage. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) passages = client.agents.passages.create( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", text="text", ) print(passages) ``` #### 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 `agents.passages.delete(strmemory_id, PassageDeleteParams**kwargs) -> object` **delete** `/v1/agents/{agent_id}/archival-memory/{memory_id}` Delete a memory from an agent's archival memory store. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `memory_id: str` ### Returns - `object` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) passage = client.agents.passages.delete( memory_id="memory_id", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(passage) ``` #### Response ```json {} ``` ## Search Archival Memory `agents.passages.search(stragent_id, PassageSearchParams**kwargs) -> PassageSearchResponse` **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. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `query: str` String to search for using semantic similarity - `end_datetime: Optional[Union[str, datetime, null]]` Filter results to passages created before this datetime - `start_datetime: Optional[Union[str, datetime, null]]` Filter results to passages created after this datetime - `tag_match_mode: Optional[Literal["any", "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[Sequence[str]]` Optional list of tags to filter search results - `top_k: Optional[int]` Maximum number of results to return. Uses system default if not specified ### Returns - `class PassageSearchResponse: …` - `count: int` Total number of results returned - `results: List[Result]` List of search results matching the query - `id: str` Unique identifier of the archival memory passage - `content: str` Text content of the archival memory passage - `timestamp: str` Timestamp of when the memory was created, formatted in agent's timezone - `tags: Optional[List[str]]` List of tags associated with this memory ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.passages.search( agent_id="agent-123e4567-e89b-42d3-8456-426614174000", query="query", ) print(response.count) ``` #### Response ```json { "count": 0, "results": [ { "id": "id", "content": "content", "timestamp": "timestamp", "tags": [ "string" ] } ] } ``` ## Domain Types ### Passage List Response - `List[Passage]` - `embedding: Optional[List[float]]` The embedding of the passage. - `embedding_config: Optional[EmbeddingConfig]` Configuration for embedding model connection and processing parameters. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `text: str` The text of the passage. - `id: Optional[str]` The human-friendly ID of the Passage - `archive_id: Optional[str]` The unique identifier of the archive containing this passage. - `created_at: Optional[datetime]` The creation date of the passage. - `created_by_id: Optional[str]` The id of the user that made this object. - `file_id: Optional[str]` The unique identifier of the file associated with the passage. - `file_name: Optional[str]` The name of the file (only for source passages). - `is_deleted: Optional[bool]` Whether this passage is deleted or not. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `metadata: Optional[Dict[str, object]]` The metadata of the passage. - `source_id: Optional[str]` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: Optional[List[str]]` Tags associated with this passage. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Passage Create Response - `List[Passage]` - `embedding: Optional[List[float]]` The embedding of the passage. - `embedding_config: Optional[EmbeddingConfig]` Configuration for embedding model connection and processing parameters. - `embedding_dim: int` The dimension of the embedding. - `embedding_endpoint_type: Literal["openai", "anthropic", "bedrock", 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: str` The model for the embedding. - `azure_deployment: Optional[str]` The Azure deployment for the model. - `azure_endpoint: Optional[str]` The Azure endpoint for the model. - `azure_version: Optional[str]` The Azure version for the model. - `batch_size: Optional[int]` The maximum batch size for processing embeddings. - `embedding_chunk_size: Optional[int]` The chunk size of the embedding. - `embedding_endpoint: Optional[str]` The endpoint for the model (`None` if local). - `handle: Optional[str]` The handle for this config, in the format provider/model-name. - `text: str` The text of the passage. - `id: Optional[str]` The human-friendly ID of the Passage - `archive_id: Optional[str]` The unique identifier of the archive containing this passage. - `created_at: Optional[datetime]` The creation date of the passage. - `created_by_id: Optional[str]` The id of the user that made this object. - `file_id: Optional[str]` The unique identifier of the file associated with the passage. - `file_name: Optional[str]` The name of the file (only for source passages). - `is_deleted: Optional[bool]` Whether this passage is deleted or not. - `last_updated_by_id: Optional[str]` The id of the user that made this object. - `metadata: Optional[Dict[str, object]]` The metadata of the passage. - `source_id: Optional[str]` Deprecated: Use `folder_id` field instead. The data source of the passage. - `tags: Optional[List[str]]` Tags associated with this passage. - `updated_at: Optional[datetime]` The timestamp when the object was last updated. ### Passage Search Response - `class PassageSearchResponse: …` - `count: int` Total number of results returned - `results: List[Result]` List of search results matching the query - `id: str` Unique identifier of the archival memory passage - `content: str` Text content of the archival memory passage - `timestamp: str` Timestamp of when the memory was created, formatted in agent's timezone - `tags: Optional[List[str]]` List of tags associated with this memory # Identities ## Attach Identity To Agent `agents.identities.attach(stridentity_id, IdentityAttachParams**kwargs) -> object` **patch** `/v1/agents/{agent_id}/identities/attach/{identity_id}` Attach an identity to an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `identity_id: str` ### Returns - `object` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.identities.attach( identity_id="identity_id", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json {} ``` ## Detach Identity From Agent `agents.identities.detach(stridentity_id, IdentityDetachParams**kwargs) -> object` **patch** `/v1/agents/{agent_id}/identities/detach/{identity_id}` Detach an identity from an agent. ### Parameters - `agent_id: str` The ID of the agent in the format 'agent-' - `identity_id: str` ### Returns - `object` ### Example ```python import os from letta_client import Letta client = Letta( api_key=os.environ.get("LETTA_API_KEY"), # This is the default and can be omitted ) response = client.agents.identities.detach( identity_id="identity_id", agent_id="agent-123e4567-e89b-42d3-8456-426614174000", ) print(response) ``` #### Response ```json {} ```