Agents
List Agents
Create Agent
Update Agent
Retrieve Agent
Delete Agent
Export Agent
Import Agent
Recompile Agent
ModelsExpand Collapse
AgentState { id, agent_type, blocks, 42 more }
Representation of an agent’s state. This is the state of the agent at a given time, and is persisted in the DB backend. The state has all the information needed to recreate a persisted agent.
Deprecated: Use model field instead. The LLM configuration used by the agent.
model_endpoint_type: "openai" | "anthropic" | "google_ai" | 27 more
The endpoint type for the model.
enable_reasoner?: boolean
Whether or not the model should use extended thinking if it is a ‘reasoning’ style model
frequency_penalty?: number | null
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.
max_reasoning_tokens?: number
Configurable thinking budget for extended thinking. Used for enable_reasoner and also for Google Vertex models like Gemini 2.5 Flash. Minimum value is 1024 when used with enable_reasoner.
max_tokens?: number | null
The maximum number of tokens to generate. If not set, the model will use its default value.
Deprecatedparallel_tool_calls?: boolean | null
Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False.
put_inner_thoughts_in_kwargs?: boolean | null
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.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
return_logprobs?: boolean
Whether to return log probabilities of the output tokens. Useful for RL training.
return_token_ids?: boolean
Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider.
strict?: boolean
Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.
temperature?: number
The temperature to use when generating text with the model. A higher temperature will result in more random text.
tool_call_parser?: string | null
SGLang tool call parser name (e.g. ‘glm47’, ‘qwen25’, ‘hermes’). Used by the SGLang native adapter to parse tool calls from raw model output.
Deprecatedmemory: Memory { blocks, agent_type, file_blocks, 2 more }
Deprecated: Use blocks field instead. The in-context memory of the agent.
file_blocks?: Array<FileBlock>
Special blocks representing the agent’s in-context memory of an attached file
Deprecatedsources: Array<Source>
Deprecated: Use folders field instead. The sources used by the agent.
embedding_config: EmbeddingConfig { embedding_dim, embedding_endpoint_type, embedding_model, 7 more }
compaction_settings?: CompactionSettings | null
Configuration for conversation compaction / summarization.
Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle.
clip_chars?: number | null
The maximum length of the summary in characters. If none, no clipping is performed.
model?: string | null
Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults.
model_settings?: OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more } | SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more } | AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more } | 14 more | null
Optional model settings used to override defaults for the summarizer model.
OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more }
SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GoogleAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
GoogleVertexModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AzureModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Azure OpenAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
XaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
xAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Moonshot/Kimi model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
ZaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Z.ai (ZhipuAI) model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotCodingModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
Kimi Code model configuration (Anthropic-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GroqModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Groq model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
DeepseekModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Deepseek model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
TogetherModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Together AI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
BedrockModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
AWS Bedrock model configuration.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
OpenRouterModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
OpenRouter model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
embedding?: string | null
The embedding model handle used by the agent (format: provider/model-name).
Deprecatedembedding_config?: EmbeddingConfig { embedding_dim, embedding_endpoint_type, embedding_model, 7 more } | null
enable_sleeptime?: boolean | null
If set to True, memory management will move to a background agent thread.
identities?: Array<Identity>
Deprecatedidentity_ids?: Array<string>
Deprecated: Use identities field instead. The ids of the identities associated with this agent.
last_run_completion?: string | null
The timestamp when the agent last completed a run.
managed_group?: ManagedGroup | null
The multi-agent group that this agent manages
max_message_buffer_length?: number | null
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_files_open?: number | null
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?: boolean
If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case.
model_settings?: OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more } | SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more } | AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more } | 14 more | null
The model settings used by the agent.
OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more }
SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GoogleAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
GoogleVertexModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AzureModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Azure OpenAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
XaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
xAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Moonshot/Kimi model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
ZaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Z.ai (ZhipuAI) model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotCodingModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
Kimi Code model configuration (Anthropic-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GroqModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Groq model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
DeepseekModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Deepseek model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
TogetherModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Together AI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
BedrockModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
AWS Bedrock model configuration.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
OpenRouterModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
OpenRouter model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
Deprecatedmulti_agent_group?: MultiAgentGroup | null
Deprecated: Use managed_group field instead. The multi-agent group that this agent manages.
max_message_buffer_length?: number | null
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.
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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
The tool calls that have been requested by the llm to run, which are pending approval
Array<ToolCall { arguments, name, tool_call_id } >
per_file_view_window_char_limit?: number | null
The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
Deprecatedtool_exec_environment_variables?: Array<AgentEnvironmentVariable { agent_id, key, value, 7 more } >
Deprecated: use secrets field instead.
tool_rules?: Array<ChildToolRule { children, tool_name, child_arg_nodes, 2 more } | InitToolRule { tool_name, args, prompt_template, type } | TerminalToolRule { tool_name, prompt_template, type } | 6 more> | null
The list of tool rules.
ChildToolRule { children, tool_name, child_arg_nodes, 2 more }
InitToolRule { tool_name, args, prompt_template, type }
Represents the initial tool rule configuration.
args?: Record<string, unknown> | null
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.
ConditionalToolRule { child_output_mapping, tool_name, default_child, 3 more }
A ToolRule that conditionally maps to different child tools based on the output.
MaxCountPerStepToolRule { max_count_limit, tool_name, prompt_template, type }
Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step.
ParentToolRule { children, tool_name, prompt_template, type }
A ToolRule that only allows a child tool to be called if the parent has been called.
AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
AzureModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Azure OpenAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
BedrockModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
AWS Bedrock model configuration.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
DeepseekModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Deepseek model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
GoogleAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
GoogleVertexModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
GroqModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Groq model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
InitToolRule { tool_name, args, prompt_template, type }
Represents the initial tool rule configuration.
args?: Record<string, unknown> | null
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.
LettaMessageContentUnion = TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 4 more
Sent via the Anthropic Messages API
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolCallContent { id, input, name, 2 more }
ReasoningContent { is_native, reasoning, signature, type }
MessageCreate { content, role, batch_item_id, 5 more }
Request to create a message
The content of the message.
Array<LettaMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolCallContent { id, input, name, 2 more }
ReasoningContent { is_native, reasoning, signature, type }
OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
TogetherModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Together AI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
XaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
xAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AgentsMessages
List Messages
Create Message
Create Message Streaming
Cancel Message
Create Message Async
Reset Messages
Summarize Messages
ModelsExpand Collapse
ApprovalCreate { approval_request_id, approvals, approve, 4 more }
Input to approve or deny a tool call request
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
The list of approval responses
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ApprovalRequestMessage { id, date, tool_call, 9 more }
A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
The tool calls that have been requested by the llm to run, which are pending approval
Array<ToolCall { arguments, name, tool_call_id } >
ApprovalResponseMessage { id, date, approval_request_id, 11 more }
A message representing a response form the user indicating whether a tool has been approved to run.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
The list of approval responses
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
AssistantMessage { id, content, date, 8 more }
A message sent by the LLM in response to user input. Used in the LLM context.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)
The message content sent by the agent (can be a string or an array of content parts)
Array<LettaAssistantMessageContentUnion { text, signature, type } >
EventMessage { id, date, event_data, 9 more }
A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.
HiddenReasoningMessage { id, date, state, 9 more }
Representation of an agent’s internal reasoning where reasoning content has been hidden from the response.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal[“redacted”, “omitted”]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
InternalMessage { id, role, agent_id, 22 more }
Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.
Attributes:
id (str): The unique identifier of the message.
role (MessageRole): The role of the participant.
text (str): The text of the message.
user_id (str): The unique identifier of the user.
agent_id (str): The unique identifier of the agent.
model (str): The model used to make the function call.
name (str): The name of the participant.
created_at (datetime): The time the message was created.
tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.
tool_call_id (str): The id of the tool call.
step_id (str): The id of the step that this message was created in.
otid (str): The offline threading id associated with this message.
tool_returns (List[ToolReturn]): The list of tool returns requested.
group_id (str): The multi-agent group that the message was sent in.
sender_id (str): The id of the sender of the message, can be an identity id or agent id.
conversation_id (str): The conversation this message belongs to.t
approval_request_id?: string | null
The id of the approval request if this message is associated with a tool call request.
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | LettaSchemasMessageToolReturnOutput { status, func_response, stderr, 2 more } > | null
The list of approvals for this message.
LettaSchemasMessageToolReturnOutput { status, func_response, stderr, 2 more }
func_response?: string | Array<TextContent { text, signature, type } | ImageContent { source, type } > | null
The function response - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
content?: Array<TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 5 more> | null
The content of the message.
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolCallContent { id, input, name, 2 more }
ReasoningContent { is_native, reasoning, signature, type }
is_err?: boolean | null
Whether this message is part of an error step. Used only for debugging purposes.
name?: string | null
For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.
tool_returns?: Array<ToolReturn> | null
Tool execution return information for prior tool calls
func_response?: string | Array<TextContent { text, signature, type } | ImageContent { source, type } > | null
The function response - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
LettaRequest { assistant_message_tool_kwarg, assistant_message_tool_name, client_skills, 13 more }
Deprecatedassistant_message_tool_kwarg?: string
The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedassistant_message_tool_name?: string
The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
client_skills?: Array<ClientSkill> | null
Client-side skills available in the environment. These are rendered in the system prompt’s available skills section alongside agent-scoped skills from MemFS.
client_tools?: Array<ClientTool> | null
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.
Deprecatedenable_thinking?: string
If set to True, enables reasoning before responses or tool calls from the agent.
include_compaction_messages?: boolean
If True, compaction events emit structured SummaryMessage and EventMessage types. If False (default), compaction messages are not included in the response.
input?: string | Array<TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 5 more> | null
Syntactic sugar for a single user message. Equivalent to messages=[{‘role’: ‘user’, ‘content’: input}].
Array<TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 5 more>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolCallContent { id, input, name, 2 more }
ReasoningContent { is_native, reasoning, signature, type }
messages?: Array<MessageCreate { content, role, batch_item_id, 5 more } | ApprovalCreate { approval_request_id, approvals, approve, 4 more } | ToolReturnCreate { tool_returns, group_id, otid, type } > | null
The messages to be sent to the agent.
MessageCreate { content, role, batch_item_id, 5 more }
Request to create a message
The content of the message.
Array<LettaMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolCallContent { id, input, name, 2 more }
ReasoningContent { is_native, reasoning, signature, type }
ApprovalCreate { approval_request_id, approvals, approve, 4 more }
Input to approve or deny a tool call request
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
The list of approval responses
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolReturnCreate { tool_returns, group_id, otid, type }
Submit tool return(s) from client-side tool execution.
This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case.
List of tool returns from client-side execution
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
override_model?: string | null
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?: string | null
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?: boolean
If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang).
return_token_ids?: boolean
If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns ‘turns’ field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking.
LettaResponse { messages, stop_reason, usage, 2 more }
Response object from an agent interaction, consisting of the new messages generated by the agent and usage statistics.
The type of the returned messages can be either Message or LettaMessage, depending on what was specified in the request.
Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned by the agent. usage (LettaUsageStatistics): The usage statistics
The messages returned by the agent.
SystemMessage { id, content, date, 8 more }
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
UserMessage { id, content, date, 8 more }
A message sent by the user. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)
The message content sent by the user (can be a string or an array of multi-modal content parts)
Array<LettaUserMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ReasoningMessage { id, date, reasoning, 10 more }
Representation of an agent’s internal reasoning.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal[“reasoner_model”, “non_reasoner_model”]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step
otid?: string | null
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.
HiddenReasoningMessage { id, date, state, 9 more }
Representation of an agent’s internal reasoning where reasoning content has been hidden from the response.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal[“redacted”, “omitted”]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent
ToolCallMessage { id, date, tool_call, 9 more }
A message representing a request to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
Array<ToolCall { arguments, name, tool_call_id } >
ToolReturnMessage { id, date, status, 13 more }
A message representing the return value of a tool call (generated by Letta executing the requested tool).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal[“success”, “error”]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support
otid?: string | null
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.
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
AssistantMessage { id, content, date, 8 more }
A message sent by the LLM in response to user input. Used in the LLM context.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)
The message content sent by the agent (can be a string or an array of content parts)
Array<LettaAssistantMessageContentUnion { text, signature, type } >
ApprovalRequestMessage { id, date, tool_call, 9 more }
A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
The tool calls that have been requested by the llm to run, which are pending approval
Array<ToolCall { arguments, name, tool_call_id } >
ApprovalResponseMessage { id, date, approval_request_id, 11 more }
A message representing a response form the user indicating whether a tool has been approved to run.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
The list of approval responses
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
SummaryMessage { id, date, summary, 9 more }
A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
compaction_stats?: CompactionStats | null
EventMessage { id, date, event_data, 9 more }
A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.
stop_reason: StopReason { stop_reason, message_type }
usage: Usage { cache_write_tokens, cached_input_tokens, completion_tokens, 7 more }
The usage statistics of the agent.
cache_write_tokens?: number | null
The number of input tokens written to cache (Anthropic only). None if not reported by provider.
cached_input_tokens?: number | null
The number of input tokens served from cache. None if not reported by provider.
logprobs?: Logprobs | null
turns?: Array<Turn> | null
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.
LettaStreamingRequest { assistant_message_tool_kwarg, assistant_message_tool_name, background, 17 more }
Deprecatedassistant_message_tool_kwarg?: string
The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedassistant_message_tool_name?: string
The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
background?: boolean
Whether to process the request in the background (only used when streaming=true).
client_skills?: Array<ClientSkill> | null
Client-side skills available in the environment. These are rendered in the system prompt’s available skills section alongside agent-scoped skills from MemFS.
client_tools?: Array<ClientTool> | null
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.
Deprecatedenable_thinking?: string
If set to True, enables reasoning before responses or tool calls from the agent.
include_compaction_messages?: boolean
If True, compaction events emit structured SummaryMessage and EventMessage types. If False (default), compaction messages are not included in the response.
include_pings?: boolean
Whether to include periodic keepalive ping messages in the stream to prevent connection timeouts (only used when streaming=true).
input?: string | Array<TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 5 more> | null
Syntactic sugar for a single user message. Equivalent to messages=[{‘role’: ‘user’, ‘content’: input}].
Array<TextContent { text, signature, type } | ImageContent { source, type } | ToolCallContent { id, input, name, 2 more } | 5 more>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolCallContent { id, input, name, 2 more }
ReasoningContent { is_native, reasoning, signature, type }
messages?: Array<MessageCreate { content, role, batch_item_id, 5 more } | ApprovalCreate { approval_request_id, approvals, approve, 4 more } | ToolReturnCreate { tool_returns, group_id, otid, type } > | null
The messages to be sent to the agent.
MessageCreate { content, role, batch_item_id, 5 more }
Request to create a message
The content of the message.
Array<LettaMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolCallContent { id, input, name, 2 more }
ReasoningContent { is_native, reasoning, signature, type }
ApprovalCreate { approval_request_id, approvals, approve, 4 more }
Input to approve or deny a tool call request
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
The list of approval responses
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ToolReturnCreate { tool_returns, group_id, otid, type }
Submit tool return(s) from client-side tool execution.
This is the preferred way to send tool results back to the agent after client-side tool execution. It is equivalent to sending an ApprovalCreate with tool return approvals, but provides a cleaner API for the common case.
List of tool returns from client-side execution
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
override_model?: string | null
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?: string | null
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?: boolean
If True, returns log probabilities of the output tokens in the response. Useful for RL training. Only supported for OpenAI-compatible providers (including SGLang).
return_token_ids?: boolean
If True, returns token IDs and logprobs for ALL LLM generations in the agent step, not just the last one. Uses SGLang native /generate endpoint. Returns ‘turns’ field with TurnTokenData for each assistant/tool turn. Required for proper multi-turn RL training with loss masking.
stream_tokens?: boolean
Flag to determine if individual tokens should be streamed, rather than streaming per step (only used when streaming=true).
streaming?: boolean
If True, returns a streaming response (Server-Sent Events). If False (default), returns a complete response.
LettaStreamingResponse = SystemMessage { id, content, date, 8 more } | UserMessage { id, content, date, 8 more } | ReasoningMessage { id, date, reasoning, 10 more } | 10 more
Streaming response type for Server-Sent Events (SSE) endpoints. Each event in the stream will be one of these types.
SystemMessage { id, content, date, 8 more }
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
UserMessage { id, content, date, 8 more }
A message sent by the user. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)
The message content sent by the user (can be a string or an array of multi-modal content parts)
Array<LettaUserMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ReasoningMessage { id, date, reasoning, 10 more }
Representation of an agent’s internal reasoning.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal[“reasoner_model”, “non_reasoner_model”]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step
otid?: string | null
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.
HiddenReasoningMessage { id, date, state, 9 more }
Representation of an agent’s internal reasoning where reasoning content has been hidden from the response.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal[“redacted”, “omitted”]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent
ToolCallMessage { id, date, tool_call, 9 more }
A message representing a request to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
Array<ToolCall { arguments, name, tool_call_id } >
ToolReturnMessage { id, date, status, 13 more }
A message representing the return value of a tool call (generated by Letta executing the requested tool).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal[“success”, “error”]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support
otid?: string | null
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.
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
AssistantMessage { id, content, date, 8 more }
A message sent by the LLM in response to user input. Used in the LLM context.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)
The message content sent by the agent (can be a string or an array of content parts)
Array<LettaAssistantMessageContentUnion { text, signature, type } >
ApprovalRequestMessage { id, date, tool_call, 9 more }
A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
The tool calls that have been requested by the llm to run, which are pending approval
Array<ToolCall { arguments, name, tool_call_id } >
ApprovalResponseMessage { id, date, approval_request_id, 11 more }
A message representing a response form the user indicating whether a tool has been approved to run.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
The list of approval responses
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
LettaPing { id, date, is_err, 7 more }
A ping message used as a keepalive to prevent SSE streams from timing out during long running requests.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format
message_type?: "ping"
The type of the message. Ping messages are a keep-alive to prevent SSE streams from timing out during long running requests.
LettaErrorMessage { error_type, message, message_type, 3 more }
Error messages are used to notify the client of an error that occurred during the agent’s execution.
LettaStopReason { stop_reason, message_type }
LettaUsageStatistics { cache_write_tokens, cached_input_tokens, completion_tokens, 7 more }
Usage statistics for the agent interaction.
Attributes: completion_tokens (int): The number of tokens generated by the agent. prompt_tokens (int): The number of tokens in the prompt. total_tokens (int): The total number of tokens processed by the agent. step_count (int): The number of steps taken by the agent. cached_input_tokens (Optional[int]): The number of input tokens served from cache. None if not reported. cache_write_tokens (Optional[int]): The number of input tokens written to cache. None if not reported. reasoning_tokens (Optional[int]): The number of reasoning/thinking tokens generated. None if not reported.
cache_write_tokens?: number | null
The number of input tokens written to cache (Anthropic only). None if not reported by provider.
cached_input_tokens?: number | null
The number of input tokens served from cache. None if not reported by provider.
LettaUserMessageContentUnion = TextContent { text, signature, type } | ImageContent { source, type }
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
Message = SystemMessage { id, content, date, 8 more } | UserMessage { id, content, date, 8 more } | ReasoningMessage { id, date, reasoning, 10 more } | 8 more
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
SystemMessage { id, content, date, 8 more }
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
UserMessage { id, content, date, 8 more }
A message sent by the user. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)
The message content sent by the user (can be a string or an array of multi-modal content parts)
Array<LettaUserMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
ReasoningMessage { id, date, reasoning, 10 more }
Representation of an agent’s internal reasoning.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal[“reasoner_model”, “non_reasoner_model”]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step
otid?: string | null
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.
HiddenReasoningMessage { id, date, state, 9 more }
Representation of an agent’s internal reasoning where reasoning content has been hidden from the response.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal[“redacted”, “omitted”]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent
ToolCallMessage { id, date, tool_call, 9 more }
A message representing a request to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
Array<ToolCall { arguments, name, tool_call_id } >
ToolReturnMessage { id, date, status, 13 more }
A message representing the return value of a tool call (generated by Letta executing the requested tool).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal[“success”, “error”]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support
otid?: string | null
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.
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
AssistantMessage { id, content, date, 8 more }
A message sent by the LLM in response to user input. Used in the LLM context.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)
The message content sent by the agent (can be a string or an array of content parts)
Array<LettaAssistantMessageContentUnion { text, signature, type } >
ApprovalRequestMessage { id, date, tool_call, 9 more }
A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
The tool calls that have been requested by the llm to run, which are pending approval
Array<ToolCall { arguments, name, tool_call_id } >
ApprovalResponseMessage { id, date, approval_request_id, 11 more }
A message representing a response form the user indicating whether a tool has been approved to run.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status
approvals?: Array<ApprovalReturn { approve, tool_call_id, reason, type } | ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
The list of approval responses
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
SummaryMessage { id, date, summary, 9 more }
A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
compaction_stats?: CompactionStats | null
EventMessage { id, date, event_data, 9 more }
A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.
ReasoningMessage { id, date, reasoning, 10 more }
Representation of an agent’s internal reasoning.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal[“reasoner_model”, “non_reasoner_model”]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step
otid?: string | null
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, agent_id, background, 14 more }
Representation of a run - a conversation or processing session for an agent. Runs track when agents process messages and maintain the relationship between agents, steps, and messages.
request_config?: RequestConfig | null
SummaryMessage { id, date, summary, 9 more }
A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
compaction_stats?: CompactionStats | null
SystemMessage { id, content, date, 8 more }
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
ToolCallMessage { id, date, tool_call, 9 more }
A message representing a request to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
Array<ToolCall { arguments, name, tool_call_id } >
ToolReturn { status, tool_call_id, tool_return, 3 more }
The tool return value - either a string or list of content parts (text/image)
Array<TextContent { text, signature, type } | ImageContent { source, type } >
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
UpdateAssistantMessage { content, message_type }
The message content sent by the assistant (can be a string or an array of content parts)
Array<LettaAssistantMessageContentUnion { text, signature, type } >
UpdateUserMessage { content, message_type }
The message content sent by the user (can be a string or an array of multi-modal content parts)
Array<LettaUserMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
UserMessage { id, content, date, 8 more }
A message sent by the user. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)
The message content sent by the user (can be a string or an array of multi-modal content parts)
Array<LettaUserMessageContentUnion>
ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }
AgentsSchedule
Schedule Agent Message
List Scheduled Agent Messages
Retrieve Scheduled Agent Message
Delete Scheduled Agent Message
ModelsExpand Collapse
ScheduleListResponse { has_next_page, scheduled_messages }
scheduled_messages: Array<ScheduledMessage>
message: Message { messages, callback_url, include_return_message_types, max_steps }
messages: Array<Message>
ScheduleRetrieveResponse { id, agent_id, message, 2 more }
message: Message { messages, callback_url, include_return_message_types, max_steps }
messages: Array<Message>
AgentsBlocks
Retrieve Block For Agent
Update Block For Agent
List Blocks For Agent
Attach Block To Agent
Detach Block From Agent
AgentsTools
List Tools For Agent
Attach Tool To Agent
Detach Tool From Agent
Update Approval For Tool
Run Tool For Agent
ModelsExpand Collapse
ToolExecutionResult { status, agent_state, func_return, 3 more }
Representation of an agent’s state. This is the state of the agent at a given time, and is persisted in the DB backend. The state has all the information needed to recreate a persisted agent.
Deprecated: Use model field instead. The LLM configuration used by the agent.
model_endpoint_type: "openai" | "anthropic" | "google_ai" | 27 more
The endpoint type for the model.
enable_reasoner?: boolean
Whether or not the model should use extended thinking if it is a ‘reasoning’ style model
frequency_penalty?: number | null
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.
max_reasoning_tokens?: number
Configurable thinking budget for extended thinking. Used for enable_reasoner and also for Google Vertex models like Gemini 2.5 Flash. Minimum value is 1024 when used with enable_reasoner.
max_tokens?: number | null
The maximum number of tokens to generate. If not set, the model will use its default value.
Deprecatedparallel_tool_calls?: boolean | null
Deprecated: Use model_settings to configure parallel tool calls instead. If set to True, enables parallel tool calling. Defaults to False.
put_inner_thoughts_in_kwargs?: boolean | null
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.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
return_logprobs?: boolean
Whether to return log probabilities of the output tokens. Useful for RL training.
return_token_ids?: boolean
Whether to return token IDs for all LLM generations via SGLang native endpoint. Required for multi-turn RL training with loss masking. Only works with SGLang provider.
strict?: boolean
Enable strict mode for tool calling. When true, tool schemas include strict: true and additionalProperties: false, guaranteeing tool outputs match JSON schemas.
temperature?: number
The temperature to use when generating text with the model. A higher temperature will result in more random text.
tool_call_parser?: string | null
SGLang tool call parser name (e.g. ‘glm47’, ‘qwen25’, ‘hermes’). Used by the SGLang native adapter to parse tool calls from raw model output.
Deprecatedmemory: Memory { blocks, agent_type, file_blocks, 2 more }
Deprecated: Use blocks field instead. The in-context memory of the agent.
file_blocks?: Array<FileBlock>
Special blocks representing the agent’s in-context memory of an attached file
Deprecatedsources: Array<Source>
Deprecated: Use folders field instead. The sources used by the agent.
embedding_config: EmbeddingConfig { embedding_dim, embedding_endpoint_type, embedding_model, 7 more }
compaction_settings?: CompactionSettings | null
Configuration for conversation compaction / summarization.
Per-model settings (temperature, max tokens, etc.) are derived from the default configuration for that handle.
clip_chars?: number | null
The maximum length of the summary in characters. If none, no clipping is performed.
model?: string | null
Model handle to use for sliding_window/all summarization (format: provider/model-name). If None, uses lightweight provider-specific defaults.
model_settings?: OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more } | SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more } | AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more } | 14 more | null
Optional model settings used to override defaults for the summarizer model.
OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more }
SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GoogleAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
GoogleVertexModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AzureModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Azure OpenAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
XaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
xAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Moonshot/Kimi model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
ZaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Z.ai (ZhipuAI) model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotCodingModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
Kimi Code model configuration (Anthropic-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GroqModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Groq model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
DeepseekModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Deepseek model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
TogetherModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Together AI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
BedrockModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
AWS Bedrock model configuration.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
OpenRouterModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
OpenRouter model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
embedding?: string | null
The embedding model handle used by the agent (format: provider/model-name).
Deprecatedembedding_config?: EmbeddingConfig { embedding_dim, embedding_endpoint_type, embedding_model, 7 more } | null
enable_sleeptime?: boolean | null
If set to True, memory management will move to a background agent thread.
identities?: Array<Identity>
Deprecatedidentity_ids?: Array<string>
Deprecated: Use identities field instead. The ids of the identities associated with this agent.
last_run_completion?: string | null
The timestamp when the agent last completed a run.
managed_group?: ManagedGroup | null
The multi-agent group that this agent manages
max_message_buffer_length?: number | null
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_files_open?: number | null
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?: boolean
If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case.
model_settings?: OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more } | SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more } | AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more } | 14 more | null
The model settings used by the agent.
OpenAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 4 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
SgLangModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 5 more }
SGLang model configuration (OpenAI-compatible runtime with SGLang-specific parsing).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AnthropicModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GoogleAIModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
GoogleVertexModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
response_schema?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
AzureModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Azure OpenAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
XaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
xAI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Moonshot/Kimi model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
ZaiModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 3 more }
Z.ai (ZhipuAI) model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
MoonshotCodingModelSettings { effort, max_output_tokens, parallel_tool_calls, 6 more }
Kimi Code model configuration (Anthropic-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
strict?: boolean
Enable strict mode for tool calling. When true, tool outputs are guaranteed to match JSON schemas.
GroqModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Groq model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
DeepseekModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Deepseek model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
TogetherModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
Together AI model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
BedrockModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
AWS Bedrock model configuration.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
OpenRouterModelSettings { max_output_tokens, parallel_tool_calls, provider_type, 2 more }
OpenRouter model configuration (OpenAI-compatible).
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
Deprecatedmulti_agent_group?: MultiAgentGroup | null
Deprecated: Use managed_group field instead. The multi-agent group that this agent manages.
max_message_buffer_length?: number | null
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.
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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } | ToolCallDelta { arguments, name, tool_call_id }
otid?: string | null
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.
tool_calls?: Array<ToolCall { arguments, name, tool_call_id } > | ToolCallDelta { arguments, name, tool_call_id } | null
The tool calls that have been requested by the llm to run, which are pending approval
Array<ToolCall { arguments, name, tool_call_id } >
per_file_view_window_char_limit?: number | null
The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent.
response_format?: TextResponseFormat { type } | JsonSchemaResponseFormat { json_schema, type } | JsonObjectResponseFormat { type } | null
Deprecatedtool_exec_environment_variables?: Array<AgentEnvironmentVariable { agent_id, key, value, 7 more } >
Deprecated: use secrets field instead.
tool_rules?: Array<ChildToolRule { children, tool_name, child_arg_nodes, 2 more } | InitToolRule { tool_name, args, prompt_template, type } | TerminalToolRule { tool_name, prompt_template, type } | 6 more> | null
The list of tool rules.
ChildToolRule { children, tool_name, child_arg_nodes, 2 more }
InitToolRule { tool_name, args, prompt_template, type }
Represents the initial tool rule configuration.
args?: Record<string, unknown> | null
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.
ConditionalToolRule { child_output_mapping, tool_name, default_child, 3 more }
A ToolRule that conditionally maps to different child tools based on the output.
MaxCountPerStepToolRule { max_count_limit, tool_name, prompt_template, type }
Represents a tool rule configuration which constrains the total number of times this tool can be invoked in a single step.
ParentToolRule { children, tool_name, prompt_template, type }
A ToolRule that only allows a child tool to be called if the parent has been called.
AgentsFolders
Attach Folder To Agent
Detach Folder From Agent
List Folders For Agent
ModelsExpand Collapse
FolderListResponse { id, embedding_config, name, 8 more }
(Deprecated: Use Folder) Representation of a source, which is a collection of files and passages.